esc_html__()

Définition : esc_html__() traduit une chaîne WordPress puis l’échappe pour une sortie en texte HTML. Elle combine localisation et protection du balisage lorsque le résultat doit apparaître dans un élément.

Comprendre et utiliser

À quoi sert ce terme ?

Elle simplifie les interfaces PHP comprenant des titres et des libellés traduits. Un développeur évite ainsi d’oublier l’échappement au moment de l’impression d’une chaîne provenant d’un catalogue.

Fonctionnement technique

La fonction retourne une valeur localisée et HTML-échappée selon le textdomain fourni. Elle ne doit pas être utilisée pour un attribut, une URL ni un contenu dont le HTML autorisé doit être préservé.

Dans quels contextes l’utiliser ?

Utiliser pour du texte simple dans les panneaux d’administration ou les templates. Pour un attribut comme title, choisir esc_attr__() ; pour du HTML limité, adopter une politique explicite.

Cas concret : ATOOLPHA

ATOOLPHA souhaite afficher le titre « Ressources techniques » dans une section de son site en conservant la compatibilité avec des langues supplémentaires.

Exemple de code commenté

Extrait PHP destiné à un plugin ou à un template WordPress, dans le contexte indiqué ; pas au contenu HTML de l’article.

<?php
echo '<h2>' . esc_html__( 'Ressources techniques', 'atoolpha' ) . '</h2>';

Décryptage de l’exemple

Une seule fonction demande la traduction et protège le résultat pour être inséré comme texte du h2. Le textdomain atoolpha doit correspondre au catalogue chargé par l’extension ou le thème.

Résultat attendu

Le titre s’affiche dans la locale active si la traduction existe ; sinon il reprend la chaîne de référence.

Exercice pratique et vérification

Tester une traduction contenant une esperluette et des chevrons, puis comparer le HTML final à une sortie avec __() seule.

Précautions et limites

Un résultat déjà échappé ne doit pas être échappé une deuxième fois sans nécessité. Pour les textes contenant une mise en forme HTML permise, utiliser un autre traitement adapté.

À ne pas confondre

esc_html__() retourne une chaîne traduite prête au texte HTML ; esc_html_e() traduit et imprime directement ; __() retourne une traduction sans échappement.

Diagnostic avancé

Si le navigateur montre des entités telles que &amp;, rechercher un double échappement ou un catalogue contenant des entités déjà encodées.

Choix d’architecture et déploiement

La famille esc_*__() doit être choisie selon le contexte final du texte, et non pour raccourcir le code. L’accessibilité, les traductions longues et les caractères spéciaux doivent être testés dans l’interface avant toute publication publique.