Comment traduire WordPress et ses extensions avec Poedit

Poedit permet de traduire localement un thème ou une extension WordPress à partir de fichiers POT ou PO. Il crée ensuite le fichier MO utilisé par WordPress. Pour le cœur de WordPress et les extensions publiques, privilégiez toutefois les paquets officiels et la plateforme translate.wordpress.org.

WordPress, ses thèmes et ses extensions utilisent principalement le système Gettext pour traduire les textes affichés dans leur interface.

Poedit fournit une interface graphique pour modifier ces catalogues sans éditer directement les fichiers PHP. Il permet ainsi de traduire une extension privée, un thème commercial ou un développement sur mesure.

La procédure reste assez simple. Encore faut-il choisir le bon fichier, respecter le domaine de traduction et installer le résultat au bon endroit. Sinon, WordPress contemplera votre traduction avec une indifférence toute professionnelle.

Faut-il encore traduire WordPress avec Poedit ?

Poedit reste utile, mais il ne constitue plus la solution adaptée à toutes les situations.

Le bon outil dépend de ce que vous souhaitez traduire.

Élément à traduire	Méthode recommandée
Le cœur de WordPress	Choisir la langue dans l’administration
Une extension de WordPress.org	Utiliser la traduction officielle ou contribuer sur translate.wordpress.org
Un thème de WordPress.org	Utiliser la traduction officielle ou contribuer sur translate.wordpress.org
Une extension premium	Utiliser Poedit ou l’outil fourni par l’éditeur
Une extension privée	Créer ou modifier ses catalogues avec Poedit ou WP-CLI
Une traduction propre à un seul site	Utiliser Poedit, Loco Translate ou un chargement personnalisé
Un projet automatisé	Utiliser les commandes i18n de WP-CLI

Ne téléchargez donc plus manuellement une traduction française du cœur de WordPress. WordPress sait gérer ses langues et leurs mises à jour depuis l’administration.

Traduire le cœur de WordPress en français

Pour afficher WordPress en français, ouvrez simplement :

1. Réglages ;
2. Général ;
3. Langue du site ;
4. sélectionnez Français ;
5. enregistrez les modifications.

WordPress télécharge alors les fichiers de langue nécessaires et les place dans le répertoire wp-content/languages.

Les anciennes procédures qui demandaient de télécharger un fichier fr_FR.mo puis de modifier la constante WPLANG dans wp-config.php ne sont plus nécessaires sur une installation normale.

Chaque utilisateur peut également choisir la langue de sa propre interface depuis son profil, sans changer la langue publique du site.

Comprendre les fichiers POT, PO, MO et JSON

Avant d’ouvrir Poedit, il faut distinguer les différents fichiers utilisés par WordPress.

Le fichier POT : le modèle de traduction

Le fichier .pot, pour Portable Object Template, contient les chaînes originales extraites du code.

Il ne correspond à aucune langue particulière. Il sert de modèle pour créer les catalogues PO de chaque langue.

Un projet nommé sky-plugin peut, par exemple, fournir ce fichier :

languages/sky-plugin.pot

Le fichier PO : le catalogue éditable

Le fichier .po, pour Portable Object, contient les chaînes originales et leur traduction dans une langue donnée.

Il reste lisible et modifiable avec un éditeur comme Poedit.

msgid "Settings"
msgstr "Réglages"Langage du code : JavaScript (javascript)

Le fichier français d’une extension dont le domaine est sky-plugin sera généralement nommé :

sky-plugin-fr_FR.poLangage du code : CSS (css)

Le fichier MO : le catalogue compilé

Le fichier .mo, pour Machine Object, constitue la version compilée du fichier PO.

WordPress peut charger ce fichier pour afficher les traductions. Poedit le génère normalement lors de l’enregistrement du catalogue PO.

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

Les fichiers JSON pour JavaScript et Gutenberg

Les interfaces écrites en JavaScript, notamment certains écrans Gutenberg, utilisent des catalogues JSON au format Jed.

Une traduction peut donc fonctionner dans les écrans PHP du plugin, mais rester en anglais dans ses blocs ou ses composants React si les fichiers JSON manquent.

Poedit gère le travail de traduction du catalogue PO. Cependant, la génération des fichiers JSON WordPress s’effectue généralement avec WP-CLI ou avec le processus de compilation du projet.

Qu’est-ce que le domaine de traduction ?

Le domaine de traduction, ou text domain, identifie le catalogue auquel appartient une chaîne.

Dans une extension, il correspond généralement au slug du projet :

<?php
/**
 * Plugin Name: Sky Plugin
 * Text Domain: sky-plugin
 * Domain Path: /languages
 */Langage du code : HTML, XML (xml)

Les fonctions de traduction doivent utiliser exactement le même domaine :

<?php
esc_html_e( 'Settings', 'sky-plugin' );Langage du code : HTML, XML (xml)

Si le code utilise sky-plugin, mais que les fichiers s’appellent another-plugin-fr_FR.mo, WordPress ne fera pas le rapprochement.

Avant de traduire une extension existante, recherchez donc son domaine dans :

• l’en-tête de son fichier principal ;
• son fichier POT ;
• ses appels à __(), _e() ou leurs variantes ;
• son fichier block.json ;
• sa documentation.

Installer Poedit

Poedit est disponible pour Windows, macOS et Linux. Téléchargez-le depuis le site officiel de Poedit, puis installez-le comme n’importe quelle application.

La version gratuite suffit pour ouvrir, traduire et enregistrer des catalogues PO. Certaines fonctions avancées, notamment l’intégration directe avec des installations WordPress distantes, appartiennent à la version Pro.

Travaillez toujours sur une copie locale de l’extension ou du thème. N’éditez pas directement les fichiers sur un site en production sans sauvegarde.

Méthode 1 : traduire un plugin depuis son fichier POT

Cette méthode convient lorsqu’une extension fournit déjà un fichier POT dans son répertoire languages.

1. Repérer le fichier POT

Téléchargez une copie du plugin sur votre ordinateur, puis recherchez un fichier semblable à :

wp-content/plugins/sky-plugin/languages/sky-plugin.pot

Le répertoire peut aussi s’appeler lang, locale ou translations. Le nom languages reste toutefois le plus courant dans WordPress.

2. Créer une traduction dans Poedit

1. Ouvrez Poedit.
2. Choisissez l’option permettant de créer une traduction à partir d’un fichier POT.
3. Sélectionnez le fichier sky-plugin.pot.
4. Choisissez Français comme langue cible.
5. Vérifiez que l’encodage utilisé est UTF-8.
6. Enregistrez le catalogue sous le nom attendu par WordPress.

Pour une traduction française de France, utilisez la locale fr_FR :

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

Poedit génère normalement le fichier MO lors de l’enregistrement. Vérifiez la présence des deux fichiers avant de les transférer.

3. Traduire les chaînes

Sélectionnez chaque chaîne originale, puis saisissez sa traduction dans le champ prévu.

Respectez soigneusement :

• les variables comme %s, %d ou %1$s ;
• les balises HTML présentes dans la chaîne ;
• les espaces et signes de ponctuation utiles ;
• le contexte fourni par les commentaires ;
• les formes singulières et plurielles ;
• le niveau de formalité du reste de l’interface.

Ne traduisez jamais un spécificateur comme %s. WordPress le remplacera par une valeur lors de l’exécution.

Cette traduction est correcte :

Original : "%s item deleted"
Traduction : "%s élément supprimé"Langage du code : JavaScript (javascript)

Celle-ci provoquera probablement un avertissement ou une sortie incorrecte :

Original : "%s item deleted"
Traduction : "Élément supprimé"Langage du code : JavaScript (javascript)

4. Vérifier les formes plurielles

Poedit connaît les règles de pluriel de la langue choisie. Il affiche donc plusieurs champs lorsque la chaîne source possède une forme singulière et une forme plurielle.

Ne saisissez plus manuellement une formule de pluriel copiée dans un ancien tutoriel. Choisissez correctement la langue du catalogue et laissez Poedit créer les en-têtes adaptés.

Pour le français, une unité utilise la forme singulière et les autres nombres utilisent généralement la forme plurielle. L’éditeur se charge de produire la syntaxe attendue par Gettext.

5. Valider puis enregistrer le catalogue

Avant de quitter Poedit :

• enregistrez le fichier PO ;
• corrigez les erreurs signalées ;
• vérifiez que le fichier MO a été créé ;
• conservez une copie locale de vos fichiers ;
• notez la version du plugin utilisée pour la traduction.

Méthode 2 : mettre à jour une traduction PO existante

Lorsqu’une extension évolue, de nouvelles chaînes apparaissent et d’autres disparaissent. Il ne faut pas recommencer la traduction depuis zéro.

1. Ouvrez votre fichier PO français dans Poedit.
2. Choisissez la fonction de mise à jour depuis un fichier POT.
3. Sélectionnez le nouveau fichier POT fourni par l’extension.
4. Examinez les nouvelles chaînes et les correspondances approximatives.
5. Corrigez les traductions marquées comme incertaines.
6. Enregistrez le catalogue pour recréer le fichier MO.

Poedit tente de conserver les traductions existantes lorsque les chaînes changent légèrement. Vérifiez toujours les suggestions automatiques. Une proximité textuelle ne garantit pas que le sens soit resté identique.

Méthode 3 : créer le fichier POT d’un plugin

Une extension privée ou ancienne ne fournit pas toujours de fichier POT. Dans ce cas, il faut extraire les chaînes depuis son code source.

Poedit Pro sait analyser directement un projet WordPress. Pour un processus reproductible, WP-CLI reste toutefois préférable.

Placez-vous dans le répertoire de l’extension, puis lancez :

wp i18n make-pot . languages/sky-plugin.pot

La commande analyse notamment les fichiers PHP, JavaScript, block.json et theme.json. Elle utilise le domaine déclaré dans l’en-tête de l’extension lorsque celui-ci existe.

Vous pouvez également auditer le projet avant de créer son catalogue :

wp i18n audit .

Cette commande détecte plusieurs erreurs fréquentes : domaine incohérent, chaîne impossible à extraire ou mauvaise utilisation des fonctions de traduction.

Générer les fichiers MO et JSON avec WP-CLI

Poedit génère normalement le fichier MO automatiquement. WP-CLI permet néanmoins d’automatiser cette compilation dans un script de construction ou une intégration continue.

Pour créer les fichiers MO à partir des catalogues PO :

wp i18n make-mo languages

Pour générer les catalogues JSON nécessaires aux chaînes JavaScript :

wp i18n make-json languages

Pour mettre à jour les fichiers PO après la régénération du POT :

wp i18n update-po languages/sky-plugin.pot languages

Ces commandes conviennent particulièrement aux extensions développées sous Git. Elles évitent de dépendre de réglages locaux propres à un poste de travail.

Où installer les fichiers de traduction ?

L’emplacement dépend du type de projet et de la manière dont il charge son domaine de traduction.

Pour une extension

WordPress utilise notamment le répertoire global suivant pour les traductions d’extensions :

wp-content/languages/plugins/

Pour notre exemple, vous pouvez y placer :

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

Certains plugins commerciaux chargent plutôt les fichiers stockés dans leur propre répertoire :

wp-content/plugins/sky-plugin/languages/

Consultez leur documentation ou observez les fichiers de langue déjà présents.

Pour un thème

Les traductions globales des thèmes se trouvent généralement dans :

wp-content/languages/themes/

Un thème dont le domaine est sky-theme utilisera, par exemple :

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

Le thème peut aussi charger ses catalogues depuis son propre répertoire languages.

Attention aux traductions écrasées par les mises à jour

Ne modifiez jamais directement les fichiers livrés avec un plugin ou un thème sans conserver une copie externe.

Une mise à jour du projet remplacera son répertoire et supprimera probablement vos modifications.

Le répertoire global wp-content/languages/plugins protège vos fichiers d’une mise à jour classique du code du plugin. Cependant, une mise à jour automatique des paquets de traduction peut remplacer un fichier portant le même nom.

Pour une traduction personnalisée importante :

• conservez toujours les fichiers PO dans un dépôt Git ou une sauvegarde ;
• documentez leur emplacement et leur version ;
• testez les mises à jour sur un environnement de préproduction ;
• utilisez un emplacement personnalisé avec un chargeur dédié si nécessaire ;
• réappliquez la traduction après chaque modification importante du catalogue source.

Une traduction spécifique au site n’est pas un simple fichier jetable. Traitez-la comme du code personnalisé.

Contribuer à la traduction officielle d’un plugin

Lorsqu’un plugin ou un thème provient de WordPress.org, évitez de garder pour vous une traduction qui pourrait profiter à tous ses utilisateurs.

La plateforme translate.wordpress.org permet de traduire directement les chaînes détectées dans les projets publics.

1. Connectez-vous avec votre compte WordPress.org.
2. Recherchez le plugin ou le thème concerné.
3. Choisissez la locale française.
4. Ouvrez le projet stable, développement ou JavaScript approprié.
5. Proposez vos traductions.
6. Attendez leur validation par un responsable de traduction.

Après validation et une fois le seuil requis atteint, WordPress peut distribuer le paquet de langue automatiquement aux sites concernés.

Poedit reste utile pour travailler hors ligne, mais GlotPress constitue la voie normale pour contribuer aux traductions communautaires de WordPress.org.

Poedit ou Loco Translate : quelle solution choisir ?

Poedit et Loco Translate répondent à des usages proches, mais leur fonctionnement diffère.

Poedit	Loco Translate
Application installée sur l’ordinateur	Extension installée dans WordPress
Travail local et hors ligne	Modification depuis l’administration
Adapté à Git et aux projets de développement	Pratique pour une correction rapide
N’ajoute aucune extension au site	Ajoute du code dans WordPress
Demande un transfert des fichiers	Écrit directement sur le serveur
Convient aux développeurs et traducteurs	Convient aux administrateurs de site

Pour une traduction maintenue dans un projet professionnel, Poedit associé à WP-CLI et Git offre généralement le meilleur contrôle.

Pour modifier rapidement quelques libellés sur un seul site, Loco Translate peut être plus accessible. Il faut néanmoins protéger et sauvegarder ses fichiers personnalisés.

Pourquoi ma traduction WordPress ne s’affiche-t-elle pas ?

Une traduction absente provient rarement de Poedit lui-même. Vérifiez les points suivants dans cet ordre.

• La langue du site correspond bien à la locale du fichier.
• Le nom du fichier contient le bon domaine de traduction.
• La locale utilise le bon format, par exemple fr_FR.
• Le fichier MO existe et n’est pas vide.
• Les fichiers se trouvent dans un répertoire effectivement chargé.
• Le plugin utilise correctement les fonctions de traduction WordPress.
• La chaîne originale correspond exactement à celle du catalogue.
• La chaîne n’est pas construite dynamiquement dans le code.
• Le cache de page, le cache objet et le cache PHP ont été purgés.
• Les fichiers JSON existent pour les textes affichés en JavaScript.

Vérifiez également que vous traduisez bien une chaîne fournie par le plugin. Certains textes proviennent des réglages du site, de la base de données, d’un constructeur de pages ou d’une autre extension.

Le plugin n’est peut-être pas traduisible

Poedit ne peut traduire que les chaînes correctement internationalisées dans le code.

Cette chaîne peut être extraite :

<?php
echo esc_html__( 'Save settings', 'sky-plugin' );Langage du code : HTML, XML (xml)

Cette chaîne ne passe par aucune fonction de traduction :

<?php
echo 'Save settings';Langage du code : HTML, XML (xml)

Dans ce second cas, aucun fichier PO ou MO ne pourra la remplacer. Le développeur doit d’abord rendre la chaîne traduisible.

La chaîne est générée dynamiquement

Les outils d’extraction recherchent des chaînes littérales dans les fonctions de traduction.

Ce code pose donc problème :

<?php
$label = 'Settings';

echo esc_html__( $label, 'sky-plugin' );Langage du code : HTML, XML (xml)

Même si WordPress peut tenter une traduction lors de l’exécution, l’outil qui crée le POT ne sait pas quelle valeur prendra la variable.

Utilisez plutôt une chaîne littérale :

<?php
echo esc_html__( 'Settings', 'sky-plugin' );Langage du code : HTML, XML (xml)

Bonnes pratiques pour traduire une extension WordPress

• Partez du fichier POT de la même version que le plugin.
• Utilisez la locale exacte attendue par WordPress.
• Respectez le domaine de traduction du projet.
• Ne supprimez jamais les variables de substitution.
• Traduisez le sens plutôt que chaque mot isolément.
• Conservez la même terminologie dans toute l’interface.
• Testez les chaînes dans leur contexte réel.
• Contrôlez les singuliers et les pluriels.
• Générez aussi les fichiers JSON pour les interfaces JavaScript.
• Conservez les fichiers PO dans une sauvegarde ou un dépôt Git.
• Mettez le catalogue à jour après chaque nouvelle version.
• Contribuez à WordPress.org lorsque le projet y est distribué.

Une extension WordPress reste partiellement en anglais ?

Une traduction peut échouer à cause d’un mauvais domaine, d’un chargement trop tardif, de fichiers JSON absents ou de chaînes qui n’ont jamais été internationalisées.

• audit des domaines et fichiers de langue ;
• internationalisation de plugins sur mesure ;
• traduction des interfaces PHP et JavaScript ;
• génération automatisée des fichiers POT, MO et JSON ;
• protection des traductions personnalisées contre les mises à jour ;
• correction des extensions partiellement traduites.

Contactez-moi pour corriger ou internationaliser votre extension WordPress.

Questions fréquentes

Poedit est-il gratuit ?

Poedit propose une version gratuite suffisante pour ouvrir, traduire et compiler des fichiers PO. La version Pro ajoute notamment des fonctions avancées liées aux projets WordPress et à la traduction assistée.

Quelle différence existe-t-il entre PO et MO ?

Le fichier PO contient les traductions sous une forme lisible et modifiable. Le fichier MO constitue leur version compilée, conçue pour être chargée par Gettext et WordPress.

Comment traduire WordPress lui-même en français ?

Ouvrez Réglages, puis Général, et choisissez Français dans le champ Langue du site. WordPress télécharge automatiquement les paquets de langue nécessaires.

Où placer la traduction française d’un plugin ?

WordPress recherche notamment les traductions d’extensions dans wp-content/languages/plugins. Le nom doit généralement suivre le format domaine-fr_FR.po et domaine-fr_FR.mo. Certains plugins chargent aussi leur propre répertoire languages.

Pourquoi Poedit crée-t-il deux fichiers ?

Poedit conserve les traductions modifiables dans le fichier PO et génère leur version compilée dans le fichier MO. Gardez les deux : le PO servira aux prochaines modifications et le MO au chargement des traductions.

Pourquoi certaines parties de Gutenberg restent-elles en anglais ?

Les textes issus de JavaScript nécessitent des fichiers JSON au format attendu par WordPress. Un simple fichier MO peut traduire les écrans PHP sans couvrir les blocs ou les composants JavaScript.

Une mise à jour peut-elle supprimer ma traduction ?

Oui. Une traduction stockée dans le répertoire du plugin sera généralement supprimée lors de sa mise à jour. Un paquet de traduction officiel peut aussi remplacer un fichier global homonyme. Conservez toujours une copie externe de vos fichiers PO.

Conclusion

Poedit reste un excellent outil pour traduire un thème ou une extension WordPress, surtout lorsque le projet est privé, premium ou développé sur mesure.

Partez de préférence d’un fichier POT, créez un catalogue PO pour la locale souhaitée, puis laissez Poedit générer le fichier MO. Respectez surtout le domaine de traduction et la convention de nommage des fichiers.

Pour le cœur de WordPress et les projets publics de WordPress.org, utilisez plutôt les paquets de langue automatiques et la plateforme communautaire de traduction. Enfin, n’oubliez pas les fichiers JSON lorsque l’interface contient du JavaScript ou des blocs Gutenberg.

Sources

• WordPress Plugin Handbook : internationalisation des extensions
• WordPress Plugin Handbook : localisation et fichiers POT, PO et MO
• WordPress Block Editor Handbook : internationalisation de JavaScript
• WordPress Polyglots Handbook : utiliser Poedit
• WP-CLI : commandes d’internationalisation
• Poedit : traduction des thèmes et extensions WordPress
• WordPress.org : plateforme collaborative de traduction

Report a typo