Le plugin est publié. Les chaînes sont enveloppées dans les bonnes fonctions, les fichiers de traduction sont compilés et livrés dans l'archive, la traduction française est complète et vérifiée. Pourtant, la fiche du plugin sur WordPress.org affiche imperturbablement « non traduit ». Aucune erreur, aucun avertissement, aucune explication.

Une hypothèse naturelle et fausse

Le réflexe est de chercher une erreur technique, et les pistes ne manquent pas : un domaine de texte incohérent entre les métadonnées et les appels de traduction, un chargement effectué trop tôt dans le cycle d'exécution, un nom de fichier qui ne respecte pas la convention attendue, des fichiers compilés à partir d'un catalogue obsolète.

Toutes ces causes sont réelles et méritent d'être vérifiées — mais dans ce cas précis, aucune n'est en jeu. Le plugin fonctionne parfaitement en local : installé manuellement, avec le site configuré en français, l'interface s'affiche intégralement traduite. Les fichiers sont valides, le chargement est correct.

Le malentendu vient d'ailleurs. Il tient à une différence entre ce que fait WordPress en tant que logiciel et ce que fait WordPress.org en tant que plateforme de distribution.

Deux circuits qui ne communiquent pas

WordPress, le logiciel, sait parfaitement charger un fichier de traduction fourni par un plugin. C'est un mécanisme documenté et fiable, utilisé par des milliers d'extensions distribuées hors du dépôt officiel.

WordPress.org, la plateforme, ne s'appuie pas du tout sur ce mécanisme. Elle gère les traductions via son propre outil communautaire, hébergé sur translate.wordpress.org. Ce système extrait automatiquement les chaînes traduisibles du code publié, les présente aux équipes de traduction de chaque langue, et distribue ensuite les traductions validées aux utilisateurs — indépendamment du contenu de l'archive du plugin.

Autrement dit : les fichiers de traduction livrés avec un plugin publié sur le dépôt officiel ne sont jamais consultés par la plateforme. Elle ne les lit pas, ne les importe pas, et ne les compte pas dans le pourcentage de traduction affiché. Ce pourcentage ne reflète qu'une chose : l'état d'avancement du projet de traduction communautaire correspondant.

Le message « non traduit » ne signifie pas « ce plugin n'a pas de traduction ». Il signifie « personne n'a encore traduit ce plugin sur notre plateforme ».

La cause profonde : la langue source

Reste à comprendre pourquoi le projet de traduction communautaire ne démarre pas. La réponse tient à une convention structurante du dépôt officiel : la langue source d'un plugin doit être l'anglais.

Ce n'est pas une préférence culturelle, c'est une contrainte de fonctionnement. Le système extrait les chaînes du code et les propose comme texte de référence aux équipes de traduction du monde entier. L'équipe italienne, l'équipe allemande, l'équipe espagnole travaillent toutes à partir de ce même texte source.

Si les chaînes du code sont rédigées en français, la conséquence est double :

Un plugin écrit en français est donc traité par la plateforme comme un plugin anglais dont toutes les chaînes seraient incompréhensibles. Le circuit de traduction est structurellement bloqué à sa source.

Le correctif : inverser la langue de référence

La correction est mécanique mais touche l'ensemble du code. Elle consiste à faire de l'anglais la langue des chaînes source, et du français une traduction comme les autres.

1. Réécrire les chaînes du code en anglais

Chaque appel aux fonctions de traduction doit contenir du texte anglais :

// Avant — le français comme langue source
__( 'Analyse terminée', 'mon-plugin' );

// Après — l'anglais comme langue source
__( 'Analysis complete', 'mon-plugin' );

C'est l'étape la plus longue sur un plugin existant, et elle ne peut pas être automatisée de façon fiable : une traduction automatique produirait un texte source approximatif que des dizaines de traducteurs reprendraient ensuite dans toutes les langues. Le texte source mérite d'être écrit avec soin, car il conditionne la qualité de toutes les traductions dérivées.

2. Régénérer le catalogue de chaînes

Le fichier modèle doit être reconstruit à partir du code mis à jour :

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

Ce fichier n'est pas utilisé par le dépôt officiel — qui extrait les chaînes lui-même — mais il reste indispensable pour produire les traductions embarquées et pour toute distribution hors plateforme.

3. Produire le français comme une traduction

Le texte français d'origine devient le contenu du catalogue français, puis est compilé au format binaire :

wp i18n make-mo languages/

Les versions les plus récentes de WordPress utilisent également un format PHP dédié, plus rapide à charger que le format binaire historique. Le générer coûte une commande supplémentaire et améliore le temps de chargement des pages traduites.

4. Contribuer les traductions à la plateforme

Dernière étape, et la seule qui fasse réellement changer le pourcentage affiché : proposer les traductions sur translate.wordpress.org. Rien n'oblige à attendre qu'un bénévole s'en charge — l'auteur d'un plugin peut soumettre lui-même ses traductions, qui passent ensuite en relecture par l'équipe linguistique concernée.

C'est ce dernier point qui explique la plupart des situations de blocage : beaucoup d'auteurs corrigent leur langue source, republient, et attendent un changement qui ne viendra pas tant que personne n'aura effectivement traduit les chaînes sur la plateforme.

Vérifier que le circuit est amorcé

Trois indices confirment que la configuration est correcte :

Si le projet de traduction reste vide après plusieurs jours, le problème est en amont : les chaînes ne sont probablement pas détectées, souvent parce que le domaine de texte déclaré dans l'entête ne correspond pas exactement à celui utilisé dans les appels.

Ce que cet épisode révèle

Le cas est instructif au-delà de son sujet. Le plugin était correct : code valide, fichiers valides, comportement conforme en local. L'erreur portait sur une hypothèse implicite — croire que la plateforme de distribution lit ce que le plugin embarque.

Ce genre de malentendu ne se résout pas en relisant son code, puisque le code n'a pas de défaut. Il se résout en lisant la documentation de la plateforme sur laquelle on publie, et en acceptant l'idée que le problème puisse se situer dans la relation entre deux systèmes plutôt que dans l'un ou l'autre.