.po vs .mo vs .pot : Explication des fichiers de traduction WordPress

Vous ouvrez le dossier languages d'un thème WordPress et vous trouvez trois fichiers qui semblent presque identiques : twentytwentyfour.pot, twentytwentyfour-de_DE.po et twentytwentyfour-de_DE.mo. Même thème, même langue, trois extensions différentes. Lequel devez-vous modifier ? Lequel WordPress charge-t-il réellement ? Et pourquoi la modification du mauvais fichier fait-elle disparaître silencieusement vos traductions ?

Si vous vous êtes déjà demandé quel fichier était important dans le débat fichier .po vs .mo, vous n'êtes pas seul. Ces trois extensions sont l'épine dorsale de chaque site WordPress traduit, pourtant la différence entre elles déroute aussi bien les débutants que les développeurs expérimentés. Modifiez le mauvais fichier et vos visiteurs allemands verront toujours l'anglais. Modifiez le bon mais sautez une étape et rien ne changera non plus.

Ce guide explique exactement ce que sont les fichiers .pot, .po et .mo, comment ils sont liés au sein du flux de travail GNU Gettext, où ils se trouvent dans WordPress, et pourquoi vous ne devriez jamais ouvrir un fichier .mo dans un éditeur de texte. À la fin, vous saurez quel fichier toucher et quel fichier laisser tranquille.

Que sont les fichiers .pot, .po et .mo ?

En bref : un fichier .pot est le modèle vierge, un fichier .po est votre traduction modifiable, et un fichier .mo est le binaire compilé que WordPress lit à l'exécution. Ils forment une chaîne, et chaque maillon a exactement une tâche.

Ces trois formats proviennent tous de GNU Gettext, le système de localisation sur lequel s'appuient WordPress, Drupal et des milliers de projets PHP et C. Gettext sépare les chaînes sources qu'un développeur écrit des traductions qu'un traducteur fournit, de sorte que la même base de code puisse parler des dizaines de langues sans toucher une seule ligne de PHP.

Imaginez cela comme une fiche de recette. Le .pot est la fiche vierge avec des emplacements pour les ingrédients, mais sans quantités. Le .po est la fiche remplie pour un plat spécifique. Le .mo est la copie laminée, lisible par machine, que la cuisine utilise réellement pendant le service. Vous écrivez sur la fiche en papier ; vous ne griffonnez jamais sur celle qui est laminée.

Le fichier .pot : le modèle maître

Un fichier .pot (Portable Object Template) contient chaque chaîne traduisible d'un thème ou d'une extension avec les traductions laissées vides. C'est la liste principale que les développeurs fournissent afin que les traducteurs sachent exactement ce qui doit être traduit. Les lignes msgstr sont vides car aucune langue n'a encore été choisie.

#: includes/checkout.php:42
msgid "Add to Cart"
msgstr ""

#: includes/account.php:108
msgid "Your order has been shipped to %s"
msgstr ""

Remarquez le msgstr "" vide. Un .pot est un modèle, pas une traduction. Vous le copiez une fois par langue et remplissez les blancs. Vous éditez rarement un .pot à la main ; il est régénéré à partir du code source chaque fois que les chaînes changent.

Le fichier .po : votre traduction modifiable par un humain

Un fichier .po (Portable Object) est une copie du .pot avec les lignes msgstr remplies pour une seule langue. C'est le fichier que les traducteurs et les développeurs éditent réellement. Il s'agit de texte brut, lisible par l'homme et compatible avec le contrôle de version.

#: includes/checkout.php:42
msgid "Add to Cart"
msgstr "In den Warenkorb"

#: includes/account.php:108
msgid "Your order has been shipped to %s"
msgstr "Ihre Bestellung wurde an %s versandt"

Le msgid est la chaîne source originale en anglais et ne doit jamais changer. Le msgstr est votre traduction. Le %s est un espace réservé qui doit rester intact dans la traduction — le supprimer ou le réorganiser est la cause la plus fréquente de mises en page cassées, ce que nous couvrons en profondeur dans comment traduire les fichiers PO sans casser les variables de code.

Le fichier .mo : le binaire compilé

Un fichier .mo (Machine Object) est la version compilée et binaire de votre .po. WordPress ne peut pas lire les fichiers .po efficacement à l'exécution, il charge donc le .mo pré-compilé à la place. Ouvrir un .mo dans un éditeur de texte affiche des octets illisibles — il est destiné aux machines, pas aux humains.

Lorsque WordPress appelle load_textdomain() ou load_theme_textdomain(), il recherche un fichier .mo, analyse sa table de hachage binaire et échange chaque msgid contre le msgstr correspondant à la volée. Ce format binaire rend les recherches rapides même sur des sites avec des milliers de chaînes.

Comment les trois fichiers sont-ils liés dans le flux de travail Gettext ?

Ils forment un pipeline unidirectionnel : le code source devient un .pot, le .pot devient un .po par langue, et chaque .po se compile en un .mo. Les traductions coulent toujours vers le bas.

Voici le cycle de vie complet dans l'ordre :

1. Un développeur encapsule les chaînes destinées à l'utilisateur dans des fonctions Gettext comme __() et _e() à l'intérieur du code source PHP.
2. Un outil de balayage lit la source et génère le modèle .pot contenant chaque chaîne encapsulée.
3. Un traducteur copie le .pot dans un .po spécifique à une langue (par exemple de_DE.po) et remplit chaque msgstr.
4. Le .po terminé est compilé en un .mo binaire.
5. WordPress charge le .mo à l'exécution et affiche le site traduit.

Lorsque le développeur ajoute de nouvelles chaînes plus tard, le .pot est régénéré, les nouvelles entrées sont fusionnées dans chaque .po existant (en conservant les anciennes traductions), le traducteur comble les lacunes, et le .po est recompilé en .mo. Le cycle se répète pendant toute la durée de vie du projet.

Le point essentiel à retenir : vous modifiez le .po, puis vous compilez en .mo. Vous ne modifiez jamais le .mo directement, et vous ne traduisez jamais à l'intérieur du .pot. Si vous voulez une vue d'ensemble plus approfondie, le guide ultime de la localisation WordPress parcourt l'ensemble du pipeline avec des exemples.

Conventions de nommage et emplacement des fichiers

WordPress est strict en matière de noms de fichiers. Si le nom est incorrect, votre fichier .mo parfaitement traduit sera simplement ignoré, car WordPress recherche une correspondance exacte basée sur le domaine de texte et la locale.

Le modèle de nommage pour les traductions de thèmes et d'extensions est :

# Pattern: textdomain-locale.po / .mo
twentytwentyfour-de_DE.po      # German (Germany) translation
twentytwentyfour-de_DE.mo      # compiled binary WordPress loads
twentytwentyfour-fr_FR.po      # French (France)
twentytwentyfour.pot           # template, no locale suffix

Le textdomain correspond à la chaîne passée comme deuxième argument aux fonctions Gettext comme __( 'Add to Cart', 'twentytwentyfour' ). La locale est un code de locale WordPress tel que de_DE, fr_FR ou pt_BR. Le modèle .pot ne porte pas de suffixe de locale car il est neutre en matière de langue.

L'emplacement est tout aussi important que le nommage. WordPress recherche quelques chemins prévisibles :

• Les traductions de thèmes sont livrées dans le dossier wp-content/themes/your-theme/languages/ du thème lui-même.
• Les traductions d'extensions sont livrées dans wp-content/plugins/your-plugin/languages/.
• Les traductions de translate.wordpress.org et les surcharges utilisateur atterrissent dans les répertoires globaux wp-content/languages/themes/ et wp-content/languages/plugins/, qui ont la priorité et survivent aux mises à jour.

Placez un fichier de_DE.mo correctement nommé dans le bon dossier et les visiteurs allemands verront l'allemand. Placez-le un dossier trop profond, ou orthographiez mal le domaine de texte, et WordPress reviendra silencieusement à l'anglais sans message d'erreur. Si vos traductions n'apparaissent pas, une non-concordance de nommage ou de chemin est le coupable habituel, et le guide de dépannage pour les traductions manquantes couvre chaque cause courante.

Pourquoi vous ne devriez jamais modifier un fichier .mo directement

Parce qu'un .mo est un binaire compilé, il n'y a pas de moyen sûr de le modifier à la main — et toute modification que vous forcez sera écrasée la prochaine fois que le .po sera recompilé. Le .po est la source de vérité ; le .mo est un artefact de construction jetable.

Cette seule règle explique une grande partie des tickets de support "ma traduction a changé mais le site ne s'est pas mis à jour". Quelqu'un modifie une chaîne, enregistre le .po, et oublie de recompiler le .mo. WordPress continue de charger l'ancien binaire, de sorte que la nouvelle formulation n'apparaît jamais. La solution est toujours : modifier le .po, recompiler en .mo, recharger.

Il y a une deuxième raison pour laquelle cette règle est importante : les fichiers .mo ne sont pas compatibles avec les différences (diff-friendly) dans le contrôle de version. Parce qu'ils sont binaires, un minuscule changement de formulation produit un blob opaque dans votre historique Git qu'aucun réviseur ne peut lire. Garder le .po comme source de vérité suivie et traiter le .mo comme un artefact généré permet de maintenir la révision de votre dépôt et l'audit de vos traductions.

Faire cela manuellement pour des dizaines de langues est fastidieux et sujet aux erreurs. C'est là qu'un flux de travail dans le cloud permet de gagner un temps précieux. Des outils comme SimplePoTranslate traduisent vos chaînes .po et vous renvoient un seul ZIP contenant les fichiers .po et .mo correspondants ensemble — déjà compilés, correctement nommés, prêts à être déposés dans wp-content/languages/. Il n'y a rien à compiler manuellement et aucune chance d'avoir un .mo périmé.

Il applique également le Verrouillage Syntaxique, qui gèle chaque espace réservé comme %s, %1$s et {name}, ainsi que les balises HTML, avant la traduction. Vos variables restent intactes, de sorte que vous n'expédierez jamais un .mo qui casserait une mise en page. Et parce qu'il fonctionne entièrement dans le cloud, il n'y a pas de plugin supplémentaire pour alourdir votre site — vous téléchargez un fichier et téléchargez des traductions terminées et compilées.

Tout assembler

Une fois que la distinction entre fichiers .po et .mo est claire, tout le système de traduction WordPress cesse de paraître mystérieux. Le .pot est le modèle du développeur, le .po est la copie de travail modifiable du traducteur, et le .mo est le binaire compilé que WordPress sert réellement aux visiteurs. Les traductions circulent dans une seule direction — du modèle au .po puis au .mo — et vous ne modifiez jamais que celui du milieu.

Retenez les trois règles qui évitent quatre-vingt-dix pour cent des maux de tête liés à la traduction : ne jamais traduire à l'intérieur d'un .pot, toujours recompiler le .mo après avoir modifié un .po, et respecter exactement le nommage textdomain-locale. Suivez ces règles et vos chaînes traduites apparaîtront à chaque fois.

Prêt à arrêter de vous battre avec la compilation et le nommage manuel des fichiers de traduction ? Essayez SimplePoTranslate gratuitement — aucune carte de crédit requise. Téléchargez votre .po ou .pot et obtenez un pack .po + .mo prêt à l'emploi sur le niveau gratuit en quelques minutes.