Créer un fichier de traduction .po sous WordPress

Les thèmes et les plugins WordPress sont développés en anglais et doivent faire l’objet d’une traduction française pour être compréhensibles du plus grand nombre.

Ce tutoriel abordera 3 cas : quand un fichier .po existe déjà, quand il est absent alors même que le thème ou le plugin dispose de chaînes traduisibles, et quand le thème ou le plugin n’est pas prêt à être traduit.

Avant de vous lancer, vérifiez que la traduction n’existe pas déjà : pour les thèmes et les extensions du répertoire officiel, la communauté traduit les textes sur translate.wordpress.org, et WordPress installe automatiquement les traductions françaises dans le dossier wp-content/languages. Vous pouvez aussi les récupérer sans attendre avec le bouton Mettre à jour les traductions de l’écran Tableau de bord > Mises à jour. Si la traduction y est incomplète, y contribuer profitera à tous les utilisateurs.

Cas n°1 – Un fichier .po est présent

C’est le cas le plus courant et le plus simple. Le thème ou l’extension dispose d’un fichier .po généralement situé dans un sous-dossier /languages ou /lang, parfois à la racine du dossier. Les traductions installées depuis translate.wordpress.org se trouvent, elles, dans wp-content/languages/plugins ou wp-content/languages/themes : un fichier .po, un fichier .mo, un fichier .l10n.php et parfois des fichiers .json pour les textes affichés en JavaScript. Celles de WordPress lui-même sont rangées à la racine de wp-content/languages (fr_FR.po, admin-fr_FR.po…).

Pour procéder à la traduction, éditez ce catalogue de chaînes de traduction à l’aide de Poedit. Ce logiciel, disponible pour Windows, macOS et Linux et gratuit dans sa version de base, génère à chaque enregistrement le fichier compilé .mo qui sert à afficher les textes traduits sur votre site.

Pour en savoir plus, reportez-vous au tutoriel dédié à Poedit.

Vous préférez traduire sans quitter l’administration ? L’extension Loco Translate intègre un éditeur de traduction à WordPress. Dans Loco Translate > Extensions (ou Thèmes), choisissez l’élément à traduire, puis Nouvelle langue ; à l’étape Choisissez un emplacement, sélectionnez Personnalisé. Vos fichiers sont alors enregistrés dans wp-content/languages/loco, à l’abri des mises à jour, et Loco Translate les charge en priorité tant qu’il reste activé. À chaque enregistrement, il génère aussi les fichiers .mo et .l10n.php.

Il est important de nommer correctement vos fichiers .po / .mo, sinon impossible de faire fonctionner la traduction. Pour une extension, le nom associe son domaine de traduction, indiqué par l’en-tête Text Domain de son fichier principal, et le code de la langue : wpchannel-fr_FR.po et wpchannel-fr_FR.mo pour une extension dont le domaine est wpchannel. Dans le dossier d’un thème, le code de la langue suffit : fr_FR.po et fr_FR.mo. Dans wp-content/languages/themes, en revanche, le domaine du thème revient en tête, par exemple twentytwentyfive-fr_FR.mo.

Attention à l’ordre de chargement : WordPress cherche d’abord dans wp-content/languages/plugins (ou themes), puis seulement dans le dossier de l’extension ou du thème. Si une traduction officielle y est installée, vos fichiers placés dans le dossier de l’extension sont donc ignorés. Depuis WordPress 6.5, un fichier .l10n.php est en outre chargé à la place du .mo du même nom : après avoir corrigé un .po, régénérez ce fichier avec la commande wp i18n make-php présentée plus bas, ou supprimez-le, sinon vos corrections n’apparaîtront pas.

Enfin, les fichiers rangés dans le dossier d’une extension disparaissent à chaque mise à jour de celle-ci, et ceux de wp-content/languages peuvent être remplacés lors d’une mise à jour des traductions. Pour corriger durablement la traduction d’une extension du répertoire officiel, je vous conseille donc l’emplacement personnalisé de Loco Translate.

Cas n°2 – Aucun fichier .po existant

Ce cas est le plus complexe car il faut d’abord extraire du code les chaînes à traduire. Dans cette situation, il n’existe aucun fichier de traduction pré-configuré mais le thème ou le plugin est annoncé comme étant prêt à traduire.

Vérifiez d’abord la présence d’un fichier .pot, souvent dans le sous-dossier /languages : ce modèle contient toutes les chaînes à traduire et sert à créer un .po. S’il existe, passez directement à l’étape n°3.

Étape n°1 – Récupération des sources de traduction

Rapatriez dans un premier temps le dossier de votre thème ou du plugin à traduire sur votre bureau. Ce sera plus simple par la suite.

Étape n°2 – Création du modèle .pot

Il faut savoir qu’une chaine de traduction est facilement identifiable dans le code PHP d’un thème ou d’un plugin WordPress. En effet, elle est entourée d’une fonction de traduction comme __(), _e() ou leurs variantes sécurisées esc_html__() et esc_html_e(), comme dans cet exemple :

<h1><?php esc_html_e( 'Hello World', 'wpchannel' ); ?></h1>
<h1><?php echo esc_html__( 'Hello World', 'wpchannel' ); ?></h1>
<?php
$wpc_count = (int) get_comments_number();
/* translators: %d: number of comments. */
printf( esc_html( _n( '%d comment', '%d comments', $wpc_count, 'wpchannel' ) ), $wpc_count );

La fonction est formée d’une part de la chaine à traduire et d’autres part du domaine du thème ou du plugin. Ce domaine permet de regrouper les chaines issus d’un même projet – utilisé notamment par des plugins comme WPML qui gère les sites multilingues.

Dans la première ligne, esc_html_e() ajoute automatiquement le echo et affiche donc la traduction. La seconde, avec esc_html__(), ne le fait pas. Ces variantes échappent le texte traduit : préférez-les à _e() et __(), qui afficheraient tel quel le code HTML d’une traduction malveillante. Enfin, _n() choisit la forme du singulier ou du pluriel selon le nombre, et le commentaire translators: guide les traducteurs.

Pour aller plus loin et comprendre comment gérer les variables dans les chaînes de traduction, reportez-vous au guide d’internationalisation des extensions WordPress (en anglais). Vous y apprendrez que WordPress s’appuie sur les outils et le format Gettext, à travers ses propres fonctions de traduction.

Pour extraire toutes ces chaînes, la méthode la plus fiable passe par WP-CLI, l’interface en ligne de commande de WordPress. Placez-vous dans le dossier du thème ou de l’extension, puis lancez :

wp i18n make-pot . languages/wpchannel.pot

La commande reconnaît toutes les fonctions de traduction de WordPress, y compris dans les fichiers JavaScript et block.json, reprend les commentaires destinés aux traducteurs et lit le domaine dans l’en-tête Text Domain. Elle fonctionne même sans installation de WordPress, par exemple sur la copie de votre bureau. Sans ligne de commande, Loco Translate propose un bouton Créer un modèle, et la version Pro de Poedit sait analyser un thème ou une extension WordPress.

Étape n°3 – Création du fichier .po

Lancez Poedit puis faites Fichier > Nouveau à partir d’un fichier POT/PO…, sélectionnez le fichier .pot et choisissez le français de France (code fr_FR) : Poedit applique automatiquement les formes plurielles du français (nplurals=2; plural=(n > 1);).

Bingo ! Toutes les traductions sont apparues… ou du moins les chaînes à traduire car maintenant c’est à vous de travailler.

Une fois la traduction terminée, enregistrez le fichier. Poedit propose le nom fr_FR.po, qui convient pour un thème ; pour une extension, renommez-le en wpchannel-fr_FR.po, avec le domaine de l’extension. Poedit crée le fichier .mo en même temps.

Et n’oubliez pas de transférer les fichiers .po et .mo à l’aide d’un client FTP dans le sous-dossier /languages du thème ou de l’extension concerné, ou dans wp-content/languages/plugins (ou themes), en respectant les règles de nommage vues au cas n°1.

WP-CLI sait aussi produire ces fichiers : make-mo crée les .mo, make-php les .l10n.php que WordPress charge en priorité depuis sa version 6.5, et make-json les fichiers .json des textes affichés en JavaScript, par exemple dans l’éditeur de blocs. L’option --no-purge conserve ces textes dans le .po :

wp i18n make-mo languages
wp i18n make-php languages
wp i18n make-json languages --no-purge

À chaque nouvelle version du thème ou de l’extension, régénérez le .pot, puis mettez à jour votre .po avec Traduction > Mettre à jour depuis un fichier POT… dans Poedit, ou avec la commande wp i18n update-po languages/wpchannel.pot languages : les traductions existantes sont conservées et seules les nouvelles chaînes restent à traduire.

Cas n°3 – Le thème ou le plugin n’est pas translation-ready

C’est le cas le plus rare… premièrement, contactez le développeur pour qu’il fasse un effort ! Deuxièmement, si vous développez vous-même le thème ou l’extension, rendez-le prêt à traduire : entourez chaque texte d’une fonction de traduction, comme vu au cas n°2, déclarez le domaine dans l’en-tête du fichier principal (ou du style.css d’un thème) et indiquez à WordPress où se trouvent les traductions livrées avec le code :

<?php
/**
 * Plugin Name: My Plugin
 * Text Domain: wpchannel
 * Domain Path: /languages
 */

add_action( 'init', 'wpc_load_textdomain' );

/**
 * Registers the plugin's languages folder; WordPress loads the files just in time.
 */
function wpc_load_textdomain() {
	load_plugin_textdomain( 'wpchannel', false, dirname( plugin_basename( __FILE__ ) ) . '/languages' );
}

Pour un thème, l’équivalent est load_theme_textdomain( 'wpchannel', get_template_directory() . '/languages' ), appelé sur l’action after_setup_theme. Pour un thème ou une extension hébergés sur le répertoire officiel, cet appel est même superflu depuis WordPress 4.6 : les traductions de translate.wordpress.org sont chargées automatiquement. Depuis WordPress 6.7, ces fonctions se contentent d’ailleurs d’indiquer le dossier : les traductions sont chargées « juste à temps », à la première chaîne traduite.

Si une fonction de traduction s’exécute trop tôt, par exemple dès le chargement du fichier principal de l’extension, WordPress le signale en mode débogage (WP_DEBUG) par la notice « Le chargement de la traduction pour le domaine wpchannel a été déclenché trop tôt » (fonction _load_textdomain_just_in_time) : déplacez ce code sur l’action init ou plus tard.

Dans tous les cas, rappelez-vous d’une chose concernant la gestion des traductions : ne jamais effectuer une traduction directement dans le code, jamais !

Pour traduire les contenus eux-mêmes, lisez mon retour d’expérience sur Polylang.