Poedit : mettre à jour les traductions WordPress d’un thème ou plugin

Poedit permet de traduire facilement un thème ou un plugin WordPress à partir de fichiers .pot, .po et .mo. C’est pratique, visuel, et nettement plus agréable que de traduire des chaînes dans un éditeur brut en espérant ne pas casser une forme plurielle au passage.

Mais le workflow WordPress a évolué. Aujourd’hui, il faut aussi penser aux chaînes JavaScript, aux blocs Gutenberg, aux fichiers JSON de traduction, aux language packs, et aux traductions personnalisées qui ne doivent pas être écrasées à la prochaine mise à jour.

Voici donc une méthode moderne pour mettre à jour les traductions d’un thème ou d’un plugin WordPress avec Poedit, tout en gardant un workflow propre avec WP-CLI quand vous contrôlez le code.

Comprendre les fichiers de traduction WordPress

WordPress utilise principalement le système gettext. Pour un thème ou un plugin, on rencontre généralement trois types de fichiers :

• .pot : le modèle de traduction, contenant les chaînes originales à traduire ;
• .po : le fichier éditable, contenant les traductions humaines ;
• .mo : le fichier compilé, lu par WordPress côté PHP.

Avec les interfaces modernes, WordPress peut aussi utiliser des fichiers .json pour les chaînes présentes dans les fichiers JavaScript, notamment dans les blocs et les écrans React de l’administration.

En clair : .po et .mo restent indispensables pour beaucoup de chaînes PHP. Mais si le thème ou le plugin contient du JavaScript internationalisé, les fichiers JSON peuvent aussi être nécessaires.

À quoi sert Poedit ?

Poedit est un éditeur de traduction spécialisé dans les fichiers gettext. Il permet d’ouvrir un fichier .po, de voir les chaînes originales, de saisir les traductions, puis d’enregistrer automatiquement le fichier .mo correspondant.

Poedit peut aussi créer ou mettre à jour un fichier .po depuis un fichier .pot. C’est précisément le cas le plus courant quand un thème ou un plugin ajoute de nouvelles chaînes après une mise à jour.

La version Pro de Poedit ajoute des fonctions plus orientées WordPress, comme la détection de projets WordPress, la traduction de thèmes et plugins, et certains workflows distants. Mais pour un workflow développeur maîtrisé, la combinaison WP-CLI pour extraire les chaînes + Poedit pour traduire reste très efficace.

Avant de commencer : sauvegarder les traductions personnalisées

Avant de modifier quoi que ce soit, sauvegardez vos fichiers de traduction. C’est particulièrement important si vous avez déjà personnalisé des chaînes dans un thème ou un plugin tiers.

cp -av wp-content/languages wp-content/languages.backup.$(date +%F-%H%M%S)Langage du code : JavaScript (javascript)

Si vous travaillez uniquement sur un plugin précis :

cp -av wp-content/languages/plugins wp-content/languages/plugins.backup.$(date +%F-%H%M%S)Langage du code : JavaScript (javascript)

Et pour les thèmes :

cp -av wp-content/languages/themes wp-content/languages/themes.backup.$(date +%F-%H%M%S)Langage du code : JavaScript (javascript)

Ce n’est pas glamour, mais une sauvegarde de 10 secondes évite parfois deux heures de jurons très créatifs.

Où placer les traductions WordPress ?

Il existe plusieurs emplacements possibles, et ils n’ont pas le même niveau de sécurité face aux mises à jour.

• wp-content/languages/plugins/ pour les traductions personnalisées de plugins ;
• wp-content/languages/themes/ pour les traductions personnalisées de thèmes ;
• wp-content/languages/ pour certaines traductions globales ;
• le dossier languages du plugin ou du thème, surtout pour un projet que vous développez vous-même.

Pour un plugin tiers, évitez de modifier directement les fichiers de traduction dans le dossier du plugin. Une mise à jour peut les écraser. Préférez le dossier global wp-content/languages/plugins/.

Pour un thème tiers, même logique : évitez de modifier directement le thème parent. Placez les traductions personnalisées dans wp-content/languages/themes/, ou utilisez un thème enfant si vous contrôlez aussi le code.

Si votre souci concerne plutôt les language packs WordPress globaux, l’article sur les notifications de version localisée WordPress complète bien ce guide.

Convention de nommage des fichiers

Le nom du fichier dépend du text domain du thème ou plugin, puis de la locale. Pour le français de France, la locale est généralement fr_FR.

Pour un plugin dont le text domain est mon-plugin, les fichiers seront souvent :

mon-plugin-fr_FR.po
mon-plugin-fr_FR.moLangage du code : CSS (css)

Dans le dossier global des plugins :

wp-content/languages/plugins/mon-plugin-fr_FR.po
wp-content/languages/plugins/mon-plugin-fr_FR.mo

Pour un thème dont le text domain est mon-theme :

wp-content/languages/themes/mon-theme-fr_FR.po
wp-content/languages/themes/mon-theme-fr_FR.mo

Le text domain doit correspondre au code du thème ou plugin. Si le nom est faux, WordPress ne chargera pas votre traduction. C’est vexant, mais cohérent.

Trouver le text domain d’un plugin ou thème

Pour un plugin, inspectez l’en-tête du fichier principal :

grep -R "Text Domain:" wp-content/plugins/nom-du-plugin -n | headLangage du code : JavaScript (javascript)

Pour un thème, regardez dans style.css :

grep "Text Domain:" wp-content/themes/nom-du-theme/style.cssLangage du code : JavaScript (javascript)

Vous pouvez aussi chercher les appels gettext dans le code :

grep -R "__(" wp-content/plugins/nom-du-plugin -n | head
grep -R "_e(" wp-content/plugins/nom-du-plugin -n | headLangage du code : JavaScript (javascript)

Si plusieurs text domains apparaissent, le plugin peut charger plusieurs composants. Dans ce cas, traduisez le domaine réellement utilisé par les chaînes qui vous intéressent.

Mettre à jour une traduction avec Poedit

Voici le workflow classique avec Poedit :

1. ouvrez le fichier .po existant dans Poedit ;
2. allez dans Catalogue → Mettre à jour depuis un fichier POT ;
3. sélectionnez le fichier .pot du thème ou du plugin ;
4. traduisez les nouvelles chaînes ;
5. vérifiez les chaînes approximatives ou obsolètes ;
6. enregistrez le fichier ;
7. Poedit génère automatiquement le fichier .mo.

Après enregistrement, vérifiez que les deux fichiers existent :

ls -lh mon-plugin-fr_FR.po mon-plugin-fr_FR.moLangage du code : CSS (css)

Le fichier .po est votre fichier source éditable. Le fichier .mo est celui que WordPress lit pour traduire les chaînes PHP.

Créer un fichier PO depuis un POT avec Poedit

Si vous n’avez pas encore de fichier .po, créez-le depuis le fichier .pot :

1. ouvrez Poedit ;
2. choisissez Créer une nouvelle traduction ;
3. sélectionnez le fichier .pot ;
4. choisissez la langue, par exemple Français (France) ;
5. traduisez les chaînes ;
6. enregistrez sous le bon nom, par exemple mon-plugin-fr_FR.po.

Poedit créera aussi le fichier .mo si l’option de compilation automatique est active. Elle l’est généralement par défaut.

Générer un fichier POT avec WP-CLI

Si vous développez un thème ou un plugin, ne créez pas votre fichier POT à la main. Utilisez WP-CLI :

wp i18n make-pot wp-content/plugins/mon-plugin wp-content/plugins/mon-plugin/languages/mon-plugin.pot

Pour un thème :

wp i18n make-pot wp-content/themes/mon-theme wp-content/themes/mon-theme/languages/mon-theme.pot

Cette commande scanne les fichiers du projet et extrait les chaînes traduisibles. Elle évite d’oublier des chaînes ajoutées récemment dans le code PHP ou JavaScript.

Si vous maintenez aussi des snippets ou mini-plugins WordPress, ce workflow complète bien l’article sur l’exécution de shortcodes dans une fonction PHP : dans les deux cas, l’objectif est de produire du code maintenable, pas des rustines invisibles.

Exemple complet pour un plugin maison

Imaginons un plugin situé dans :

wp-content/plugins/sky-example/

Son text domain est :

sky-example

Créez le dossier de langue :

mkdir -p wp-content/plugins/sky-example/languages

Générez le fichier POT :

wp i18n make-pot wp-content/plugins/sky-example wp-content/plugins/sky-example/languages/sky-example.pot

Ouvrez ensuite sky-example.pot avec Poedit, créez une traduction française, puis enregistrez :

wp-content/plugins/sky-example/languages/sky-example-fr_FR.po

Poedit générera aussi :

wp-content/plugins/sky-example/languages/sky-example-fr_FR.mo

Si le plugin contient du JavaScript internationalisé, ajoutez aussi l’étape JSON décrite plus bas.

Générer les fichiers JSON pour Gutenberg et JavaScript

Pour les chaînes JavaScript, WordPress peut avoir besoin de fichiers JSON séparés. C’est fréquent avec les blocs Gutenberg, les panneaux React, les scripts d’administration et certains plugins modernes.

Après avoir traduit votre fichier .po, générez les fichiers JSON avec WP-CLI :

wp i18n make-json wp-content/plugins/sky-example/languages --no-purge

Le paramètre --no-purge évite de retirer les chaînes JavaScript du fichier PO. Je le préfère dans un workflow simple, car il limite les surprises quand on revient dans Poedit.

Vous pouvez aussi spécifier un dossier de sortie :

wp i18n make-json wp-content/plugins/sky-example/languages --output-dir=wp-content/plugins/sky-example/languages/json --no-purge

Sans cette étape, certaines chaînes de l’éditeur de blocs ou de l’administration JavaScript peuvent rester en anglais, même si votre fichier .mo est correctement généré.

Mettre à jour les traductions installées avec WP-CLI

Pour les traductions officielles du cœur, des plugins et des thèmes installés depuis WordPress.org, WP-CLI peut mettre à jour les language packs :

wp language core update
wp language plugin update --all
wp language theme update --all

Pour voir ce qui serait mis à jour sans rien modifier :

wp language plugin update --all --dry-run
wp language theme update --all --dry-run

Attention : ces commandes concernent les traductions gérées comme language packs. Elles ne remplacent pas forcément vos fichiers personnalisés créés avec Poedit. Elles peuvent même écraser des fichiers si vous avez modifié directement des traductions officielles au mauvais endroit.

Ne pas modifier les traductions officielles au mauvais endroit

Si vous modifiez un fichier de traduction fourni par WordPress.org, un plugin ou un thème, votre modification peut disparaître à la prochaine mise à jour. C’est normal : le fichier appartient au paquet officiel.

Pour éviter cela, gardez vos traductions personnalisées dans les dossiers prévus :

wp-content/languages/plugins/
wp-content/languages/themes/

Ou, pour un projet maison, versionnez-les dans le dépôt du plugin ou du thème :

wp-content/plugins/mon-plugin/languages/
wp-content/themes/mon-theme/languages/

Dans un projet client, je préfère versionner les traductions custom importantes. Une traduction critique non versionnée finit toujours par disparaître le jour où quelqu’un clique sur “Mettre à jour”. Évidemment le vendredi.

Traduire un thème enfant

Pour un thème enfant, le text domain peut être celui du thème enfant si vous traduisez les chaînes ajoutées par le thème enfant. Ne mélangez pas les traductions du thème parent et celles du thème enfant.

Pour générer le POT du thème enfant :

wp i18n make-pot wp-content/themes/mon-theme-child wp-content/themes/mon-theme-child/languages/mon-theme-child.pot

Ensuite, créez :

mon-theme-child-fr_FR.po
mon-theme-child-fr_FR.moLangage du code : CSS (css)

Si vos chaînes ne se traduisent pas, vérifiez que le thème enfant charge bien son text domain avec load_child_theme_textdomain().

Exemple de chargement des traductions dans un plugin

Dans un plugin moderne, chargez le text domain proprement :

<?php
/**
 * Plugin Name: Sky Example
 * Description: Example plugin with translations.
 * Text Domain: sky-example
 * Domain Path: /languages
 */

declare(strict_types=1);

defined( 'ABSPATH' ) || exit;

add_action( 'init', 'sky_example_load_textdomain' );

/**
 * Load plugin translations.
 *
 * @return void
 */
function sky_example_load_textdomain(): void {
	load_plugin_textdomain(
		'sky-example',
		false,
		dirname( plugin_basename( __FILE__ ) ) . '/languages'
	);
}Langage du code : HTML, XML (xml)

Ensuite, utilisez le même text domain dans les chaînes :

esc_html__( 'Settings saved.', 'sky-example' );Langage du code : JavaScript (javascript)

Si le text domain diffère entre l’en-tête du plugin, le chargement et les chaînes, WordPress ne pourra pas associer correctement les traductions.

Exemple de chargement dans un thème

Dans un thème classique :

<?php
/**
 * Load theme translations.
 *
 * @return void
 */
function skyminds_theme_load_textdomain(): void {
	load_theme_textdomain(
		'skyminds-theme',
		get_template_directory() . '/languages'
	);
}
add_action( 'after_setup_theme', 'skyminds_theme_load_textdomain' );Langage du code : HTML, XML (xml)

Dans un thème enfant :

<?php
/**
 * Load child theme translations.
 *
 * @return void
 */
function skyminds_child_theme_load_textdomain(): void {
	load_child_theme_textdomain(
		'skyminds-child',
		get_stylesheet_directory() . '/languages'
	);
}
add_action( 'after_setup_theme', 'skyminds_child_theme_load_textdomain' );Langage du code : HTML, XML (xml)

Adaptez les text domains à votre thème. Le nom doit rester cohérent partout.

Vérifier qu’une traduction est bien chargée

Pour vérifier la locale active :

wp eval 'echo get_locale();'Langage du code : JavaScript (javascript)

Pour tester une chaîne traduisible avec WP-CLI :

wp eval 'echo __( "Settings saved.", "sky-example" );'Langage du code : JavaScript (javascript)

Si la chaîne reste en anglais, vérifiez :

• le text domain ;
• le nom du fichier .mo ;
• le dossier de traduction ;
• la locale du site ;
• le chargement via load_plugin_textdomain() ou load_theme_textdomain() ;
• les caches PHP, objet, OPcache ou page.

Vider les caches après modification

Après avoir modifié ou remplacé un fichier .mo ou .json, purgez les caches concernés :

wp cache flush

Si OPcache est actif, rechargez PHP-FPM si nécessaire :

sudo systemctl reload php8.3-fpmLangage du code : CSS (css)

Adaptez évidemment la version PHP au serveur. Sur un hébergement managé, purgez plutôt le cache via l’interface de l’hébergeur.

Poedit ou Loco Translate ?

Poedit est très pratique si vous aimez travailler localement, versionner vos fichiers, contrôler vos exports, et garder une logique développeur. C’est aussi très bien pour un plugin ou un thème maison.

Loco Translate est plus confortable si vous voulez modifier les traductions directement depuis l’administration WordPress. Il peut aussi gérer la génération de fichiers JSON pour les chaînes JavaScript quand les références de fichiers sont correctes.

Mon choix pratique : Poedit + WP-CLI pour les projets que je maintiens, Loco Translate pour de petites corrections rapides sur un site client sans workflow Git. Pas besoin de transformer chaque accent manquant en pipeline DevOps.

Checklist de mise à jour avec Poedit

• Identifier le text domain du thème ou plugin.
• Sauvegarder les traductions existantes.
• Générer ou récupérer le fichier .pot à jour.
• Ouvrir le fichier .po dans Poedit.
• Mettre à jour depuis le fichier .pot.
• Traduire les nouvelles chaînes.
• Vérifier les chaînes approximatives et obsolètes.
• Enregistrer pour générer le fichier .mo.
• Générer les fichiers JSON si le projet contient du JavaScript internationalisé.
• Placer les fichiers dans le bon dossier.
• Purger les caches.
• Tester les chaînes en front, admin et éditeur de blocs.

Si vous utilisez WP-CLI pour toute la maintenance du site, le guide sur lister les articles publiés avec WP-CLI fournit aussi de bonnes bases pour automatiser proprement les opérations répétitives.

Commandes utiles à garder

Vérifier la locale :

wp eval 'echo get_locale();'Langage du code : JavaScript (javascript)

Générer un POT pour un plugin :

wp i18n make-pot wp-content/plugins/mon-plugin wp-content/plugins/mon-plugin/languages/mon-plugin.pot

Générer un POT pour un thème :

wp i18n make-pot wp-content/themes/mon-theme wp-content/themes/mon-theme/languages/mon-theme.pot

Générer les JSON depuis les fichiers PO :

wp i18n make-json wp-content/plugins/mon-plugin/languages --no-purge

Mettre à jour les language packs :

wp language core update
wp language plugin update --all
wp language theme update --all

Purger le cache objet :

wp cache flush

Erreurs fréquentes

La traduction ne s’affiche pas

Vérifiez le text domain, le nom du fichier, la locale et le dossier. Une seule différence entre mon-plugin et mon_plugin suffit à casser le chargement.

Poedit génère le PO mais pas le MO

Vérifiez les préférences de Poedit et assurez-vous que la compilation automatique du fichier .mo est activée. Vous pouvez aussi enregistrer à nouveau le fichier après correction des erreurs de syntaxe.

Les textes PHP sont traduits, mais pas l’éditeur de blocs

Générez les fichiers JSON avec wp i18n make-json. Les chaînes JavaScript ne sont pas toujours servies par le fichier .mo.

Les traductions disparaissent après mise à jour

Vous avez probablement modifié les fichiers officiels dans le dossier du plugin ou du thème. Déplacez vos traductions personnalisées dans wp-content/languages/plugins/ ou wp-content/languages/themes/, selon le cas.

Certaines chaînes restent introuvables dans le POT

Vérifiez que les chaînes utilisent bien les fonctions d’internationalisation WordPress, comme __(), _e(), esc_html__() ou esc_attr__(). Les chaînes dynamiques construites n’importe comment sont difficiles, voire impossibles, à extraire proprement.

Bonnes pratiques pour vos thèmes et plugins

• Utilisez un text domain unique et cohérent.
• Ajoutez Text Domain et Domain Path dans l’en-tête du plugin ou du thème.
• Évitez les chaînes dynamiques impossibles à extraire.
• Utilisez les fonctions esc_html__() et esc_attr__() quand vous affichez directement une chaîne.
• Générez le fichier POT à chaque release.
• Versionnez les fichiers .pot, .po et, selon votre stratégie, les fichiers .mo et .json.
• Testez l’administration, le front et l’éditeur de blocs.

Pour les projets WooCommerce, pensez aussi à tester le panier, le checkout, les emails et le compte client après une mise à jour de traductions. Le guide sur la mise à jour de la base WooCommerce avec WP-CLI rappelle une bonne logique de maintenance : tester ce qui a une valeur métier réelle.

Conclusion

Poedit reste un excellent outil pour mettre à jour les traductions WordPress d’un thème ou d’un plugin. Le workflow classique fonctionne toujours : ouvrir le fichier .po, le mettre à jour depuis le .pot, traduire les nouvelles chaînes, puis enregistrer pour générer le .mo.

Mais pour un site ou un plugin moderne, ajoutez WP-CLI à la boîte à outils. Utilisez wp i18n make-pot pour extraire les chaînes, puis wp i18n make-json pour les traductions JavaScript. Ensuite seulement, testez le rendu dans le front, l’administration et l’éditeur de blocs.

La traduction WordPress n’est plus seulement une affaire de fichiers PO/MO. C’est un petit écosystème. Heureusement, avec Poedit, WP-CLI et une convention de nommage propre, il reste très domptable.

Sources

• Poedit — Translation editor for PO, XLIFF, JSON and more
• Poedit — Translate WordPress themes and plugins
• Make WordPress Polyglots — Poedit
• WP-CLI — wp i18n make-pot
• WP-CLI — wp i18n make-json
• WordPress Block Editor Handbook — Internationalization

Report a typo