Traduire un thème WordPress : text domain, load_theme_textdomain et .pot

Le thème vendu à une chaîne de fromageries régionale devait être livré prêt à traduire, l’enseigne prévoyant une déclinaison en anglais pour sa boutique en ligne dans l’année à venir. Plutôt que d’ajouter l’internationalisation après coup — un travail fastidieux qui oblige à relire chaque fichier — la bonne pratique consiste à l’intégrer dès l’écriture des gabarits. Ce tutoriel couvre la chaîne complète : déclaration du text domain, fonctions de traduction dans le PHP, export JSON pour le JavaScript, et génération du fichier .pot source.

Cet article ne traite pas des sites multilingues avec plusieurs langues actives simultanément côté visiteur, un sujet qui relève de plugins comme WPML ou Polylang et qui vient se greffer après cette base, pas la remplacer.

Déclarer un text domain unique

Le text domain identifie l’ensemble des chaînes traduisibles du thème. Il se déclare dans l’en-tête de style.css et doit correspondre exactement au slug du dossier du thème :

/*
Theme Name: Fromagerie Vitrine
Text Domain: fromagerie-vitrine
Domain Path: /languages
*/

Le chargement du domaine se fait ensuite via load_theme_textdomain(), appelé sur le crochet after_setup_theme :

function fromagerie_setup() {
	load_theme_textdomain( 'fromagerie-vitrine', get_template_directory() . '/languages' );
}
add_action( 'after_setup_theme', 'fromagerie_setup' );

Depuis WordPress 4.6, cet appel explicite n’est en réalité plus strictement nécessaire pour les thèmes hébergés sur WordPress.org, le chargement se faisant automatiquement à condition que le Text Domain corresponde au slug du thème. Le garder explicitement reste néanmoins une bonne pratique pour un thème distribué hors de cet annuaire, où cette résolution automatique ne s’applique pas.

Entourer chaque chaîne visible des bonnes fonctions

Chaque texte affiché dans un gabarit doit passer par une fonction de traduction, choisie selon le contexte d’échappement nécessaire :

<h2><?php esc_html_e( 'Nos meules affinées', 'fromagerie-vitrine' ); ?></h2>

<a href="<?php echo esc_url( home_url( '/boutique' ) ); ?>">
	<?php esc_html_e( 'Voir la boutique', 'fromagerie-vitrine' ); ?>
</a>

<?php
printf(
	/* translators: %s: nom du fromage */
	esc_html__( 'Découvrez notre %s, affiné trois mois en cave.', 'fromagerie-vitrine' ),
	esc_html( $nom_fromage )
);
?>

Le commentaire /* translators: */ avant un printf() contenant un espace réservé n’est pas décoratif : il apparaît dans le fichier .pot généré et guide le traducteur qui ne voit, sans lui, qu’un %s sans contexte.

Traduire les chaînes injectées en JavaScript

Les chaînes utilisées côté JavaScript ne peuvent pas passer par __(), propre à PHP. La fonction wp_set_script_translations(), appelée après l’enregistrement du script, permet de leur associer un fichier JSON de traduction généré séparément :

wp_enqueue_script( 'fromagerie-filtre-produits', get_theme_file_uri( 'assets/js/filtre.js' ), array(), '1.0', true );
wp_set_script_translations( 'fromagerie-filtre-produits', 'fromagerie-vitrine', get_template_directory() . '/languages' );

Côté script, les chaînes s’entourent alors des équivalents JavaScript fournis par @wordpress/i18n, comme __() ou sprintf(), chargés via la dépendance wp-i18n.

Générer le fichier .pot avec WP-CLI

Une fois toutes les chaînes correctement entourées, la commande wp i18n make-pot scanne l’ensemble du thème et génère le fichier source de traduction :

wp i18n make-pot . languages/fromagerie-vitrine.pot --domain=fromagerie-vitrine

Ce fichier .pot sert ensuite de base à un traducteur, qui produira un fichier .po puis .mo par langue cible avec un outil comme Poedit. La commande vérifie aussi, en passant, les chaînes mal formées : un appel à __() avec une variable directement en premier argument plutôt qu’une chaîne littérale, par exemple, sera signalé comme non traduisible automatiquement.

Erreurs fréquentes à éviter

• Concaténer des morceaux de phrase autour d’une variable plutôt que d’utiliser un espace réservé avec printf() ou sprintf().
• Oublier le text domain en deuxième argument de __(), ce qui rend la chaîne invisible pour wp i18n make-pot.
• Utiliser une variable comme text domain au lieu d’une chaîne littérale, ce qui empêche l’outil d’analyse statique de la détecter.

Un thème pensé traduisible dès le départ coûte à peine plus de temps à écrire ; le même thème traduit après coup coûte, en général, une relecture complète de chaque fichier de gabarit.

En résumé

Text domain déclaré correctement, fonctions de traduction systématiques dans les gabarits, export JSON pour les scripts, puis génération du .pot via WP-CLI : cette chaîne complète, une fois en place, rend un thème réellement prêt pour une traduction professionnelle, sans reprise de code a posteriori.