Encodage fautif d’un fichier .mo : une sortie parasite avant l’affichage

« établissement » à la place d’« établissement », en haut de page, dans le titre de l’onglet du navigateur : ce genre de caractères parasites, visibles avant même que le reste du contenu ne s’affiche, trahit presque toujours un problème d’encodage dans le fichier de traduction du thème, pas une erreur de code PHP. Ce chantier ne traite pas le cas voisin d’un fichier functions.php enregistré avec un indicateur d’ordre des octets qui provoque des espaces avant les balises <?php : ici, la source du problème est bien le fichier .mo lui-même.

Le format .mo est binaire : il stocke des chaînes traduites accompagnées d’un en-tête qui précise notamment le jeu de caractères utilisé au moment de la compilation depuis le fichier source .po. Quand cet en-tête ne correspond pas à l’encodage réellement utilisé par WordPress pour la page (UTF-8, dans la quasi-totalité des installations actuelles), certains caractères accentués ressortent sous forme de mojibake : une suite de caractères issue d’une double conversion d’encodage.

Symptôme : des caractères illisibles localisés, pas une page blanche

Contrairement à une erreur fatale PHP, ce défaut ne casse rien visuellement de façon globale. Il touche précisément les chaînes qui passent par la fonction de traduction du thème : le titre du site dans l’onglet du navigateur, un libellé de menu, un texte de bouton généré par __() ou _e(). Le reste du site continue de s’afficher normalement, ce qui retarde souvent le diagnostic : l’équipe corrige d’abord la chaîne visible, sans comprendre pourquoi elle réapparaît identique après correction dans l’interface de traduction.

• Les caractères accentués (é, è, à, ç) sont les premiers touchés.
• Le problème persiste après une modification de la chaîne dans l’outil de traduction, tant que le fichier .mo n’est pas régénéré avec le bon charset.
• Le site fonctionne normalement dans la langue par défaut du thème, seule la langue traduite est affectée.

Diagnostic : lire l’en-tête du fichier .po source

Le fichier .po à l’origine du .mo contient un en-tête de métadonnées qui précise le jeu de caractères utilisé :

msgid ""
msgstr ""
"Project-Id-Version: Mon Theme 1.0\n"
"Content-Type: text/plain; charset=ISO-8859-1\n"
"Content-Transfer-Encoding: 8bit\n"

Si cette ligne indique un jeu de caractères différent d’UTF-8 alors que le fichier a en réalité été saisi ou modifié en UTF-8 par un traducteur, la compilation vers .mo produit un fichier binaire dont les octets ne correspondent plus à ce que WordPress attend au moment de l’affichage. La commande wp i18n make-mo de WP-CLI ne corrige pas ce type de décalage : elle compile fidèlement ce que contient le fichier .po, y compris son en-tête erroné.

Correctif : régénérer proprement, pas rustiner l’affichage

La tentation la plus fréquente consiste à corriger le caractère fautif directement dans l’outil de traduction visuel, sans toucher à l’en-tête du fichier .po. Le résultat reste identique, car le problème ne se situe pas dans le contenu de la chaîne mais dans la déclaration du charset qui encadre tout le fichier. La correction correcte suit trois étapes :

1. Ouvrir le fichier .po dans un éditeur qui affiche l’encodage réel du fichier, et vérifier que la ligne Content-Type indique bien charset=UTF-8.
2. Si ce n’est pas le cas, réenregistrer le fichier en UTF-8 sans BOM, puis corriger la ligne d’en-tête pour qu’elle reflète ce choix.
3. Recompiler le fichier .mo avec wp i18n make-mo chemin/vers/fichier.po, puis vider tout cache d’objets ou de page qui pourrait conserver l’ancienne version compilée.

Prévention : verrouiller l’encodage dans le processus de traduction

Le moyen le plus fiable d’éviter que ce défaut ne se reproduise consiste à imposer l’UTF-8 comme seul encodage accepté dans la chaîne d’outils de traduction du projet, du premier export du .pot jusqu’à la compilation finale. Un simple contrôle avant mise en production suffit à l’automatiser :

file --mime-encoding languages/mon-theme-fr_FR.po

Si la commande retourne autre chose que utf-8, le fichier doit être corrigé avant toute recompilation. Ce contrôle, ajouté à une routine de vérification avant déploiement, coûte une ligne et évite des heures de diagnostic sur un symptôme qui, au premier regard, ressemble à un bug d’affichage bien plus complexe qu’il ne l’est réellement.

Un caractère illisible dans un titre traduit n’est presque jamais un bug du thème : c’est un fichier de traduction qui ment sur son propre encodage.

En résumé

Le mojibake provoqué par un fichier .mo mal encodé se reconnaît à sa localisation précise, limitée aux chaînes traduites, et à sa persistance malgré une correction de contenu qui ne touche pas l’en-tête du fichier source. La solution ne relève ni du thème ni de son functions.php, mais de la chaîne de compilation des traductions elle-même, qu’il vaut mieux vérifier une fois pour toutes plutôt que de corriger chaîne par chaîne.