Comment traduire un plugin WordPress (étape par étape)

Vous avez trouvé le plugin WordPress parfait pour votre projet. Il fait exactement ce dont vous avez besoin, les avis sont élogieux, puis vous l'activez et vous réalisez que chaque bouton, libellé et message d'erreur est en anglais. Vos visiteurs allemands, français ou japonais sont sur le point de se heurter à un mur de texte qu'ils ne peuvent pas lire.

La bonne nouvelle est que la plupart des plugins bien conçus sont prêts à être traduits, ce qui signifie que le développeur a encapsulé ses chaînes de caractères dans des fonctions Gettext spécifiquement pour que des personnes comme vous puissent les traduire. Le défi est de savoir où se trouvent les fichiers, comment nommer votre traduction et où la placer pour que la prochaine mise à jour du plugin n'efface pas votre travail.

Ce guide vous montre comment traduire un plugin WordPress du début à la fin : trouver le domaine de texte et le dossier de langue, obtenir ou générer le modèle .pot, construire des fichiers .po et .mo correctement nommés, et les placer là où WordPress les chargera de manière fiable. Nous aborderons également le seul type de plugin que cette approche ne peut pas entièrement traduire, afin que vous ne perdiez pas d'heures à vous battre contre un cas impossible.

Comment trouver les fichiers de traduction d'un plugin ?

Avant de traduire quoi que ce soit, vous avez besoin de deux informations du plugin : son domaine de texte et son dossier de langues. Le domaine de texte est la chaîne de caractères unique que le plugin utilise pour identifier ses propres traductions, et le dossier de langues est l'endroit où se trouve le modèle source.

Localiser le dossier de langues et le domaine de texte

Ouvrez le répertoire du plugin à l'adresse wp-content/plugins/your-plugin/ et recherchez un sous-dossier /languages. À l'intérieur, vous trouverez généralement un fichier .pot, le modèle vide contenant chaque chaîne de caractères traduisible.

Pour confirmer le domaine de texte, ouvrez le fichier PHP principal du plugin et examinez son bloc d'en-tête :

/**
 * Plugin Name: Awesome Plugin
 * Text Domain: awesome-plugin
 * Domain Path: /languages
 */

Ici, le domaine de texte est awesome-plugin. Cette valeur est critique, car vos fichiers de traduction doivent l'inclure dans leurs noms, sinon WordPress ne les associera jamais au plugin. Vous le verrez également dans chaque appel de chaîne de caractères tout au long du code :

echo __( 'Settings saved successfully.', 'awesome-plugin' );

Ce deuxième argument, awesome-plugin, est à nouveau le domaine de texte. Chaque chaîne qui l'utilise peut être traduite par votre catalogue. Si une chaîne dans l'interface du plugin manque cet enveloppement, par exemple un développeur qui a codé en dur echo 'Save' sans __(), alors cette chaîne n'est pas traduisible du tout, et aucun fichier .po ne peut l'atteindre. La plupart des plugins réputés encapsulent tout correctement, mais si vous remarquez une ou deux chaînes récalcitrantes qui refusent de se traduire, un enveloppement Gettext manquant dans la source est un coupable probable.

Un moyen rapide d'évaluer si un plugin est vraiment prêt à être traduit est de consulter sa fiche sur le répertoire WordPress.org, qui affiche un pourcentage de traduction et des liens vers un modèle /languages. Un plugin avec un projet de traduction actif est beaucoup plus susceptible d'avoir des chaînes propres et entièrement encapsulées qu'un plugin abandonné.

Que faire si le plugin n'a pas de fichier POT ?

Certains plugins sont livrés sans modèle .pot. Si le dossier /languages est vide ou manquant, vous devez générer le modèle vous-même en scannant le code source à la recherche de chaînes traduisibles.

L'outil standard pour cela est WP-CLI, qui extrait chaque appel Gettext dans un nouveau fichier .pot.

wp i18n make-pot wp-content/plugins/awesome-plugin \
  wp-content/plugins/awesome-plugin/languages/awesome-plugin.pot

Cette commande parcourt les fichiers PHP et JavaScript du plugin, trouve chaque appel __(), _e(), _n(), et les appels similaires, et écrit un modèle complet. Si vous préférez une méthode graphique, Poedit Pro peut scanner le code source de la même manière. Dans tous les cas, le résultat est un fichier .pot contenant toutes les chaînes source avec des traductions vides, prêt à être transformé en un véritable fichier de langue.

Générer votre propre modèle présente un avantage caché : il capture les chaînes que le développeur original a pu oublier d'inclure dans un fichier .pot livré. Les plugins évoluent rapidement, et un modèle livré avec la version 2.1 pourrait manquer des chaînes ajoutées en 2.4. La régénération à partir de la source actuelle garantit que votre catalogue reflète ce que le plugin affiche réellement aujourd'hui, et non ce qu'il affichait il y a deux versions. Si vous maintenez des traductions pour un plugin au fil du temps, relancer make-pot après chaque mise à jour majeure est une habitude fiable.

Créer les fichiers PO et MO avec le bon nom

L'erreur la plus courante lors de la traduction d'un plugin est le nom du fichier. WordPress trouve les traductions de plugins en faisant correspondre un modèle très spécifique, et un seul caractère incorrect signifie que votre traduction est entièrement ignorée.

La formule du nom de fichier

Pour les traductions de plugins, le modèle est text-domain-locale. Ainsi, pour le domaine de texte awesome-plugin traduit en allemand, les fichiers doivent être nommés :

awesome-plugin-de_DE.po
awesome-plugin-de_DE.mo

Le code de locale est le code de langue du site WordPress : de_DE pour l'allemand, fr_FR pour le français, es_ES pour l'espagnol, pt_BR pour le portugais brésilien. Si la locale est incorrecte, WordPress ignorera silencieusement votre fichier. Vous les créez à partir du modèle .pot dans un éditeur comme Poedit, qui compile automatiquement le fichier binaire .mo lorsque vous enregistrez. Si vous débutez avec cet éditeur, le guide complet de Poedit vous guide pas à pas dans la création d'une traduction à partir d'un modèle.

Où placer les fichiers pour que les mises à jour ne les effacent pas

Il existe deux emplacements possibles, et choisir le bon est important.

# RISKY: inside the plugin — wiped on every plugin update
wp-content/plugins/awesome-plugin/languages/awesome-plugin-de_DE.mo

# SAFE: the global languages override folder — survives updates
wp-content/languages/plugins/awesome-plugin-de_DE.mo

Utilisez toujours wp-content/languages/plugins/. WordPress vérifie d'abord ce répertoire de surcharge, et comme il se trouve en dehors du dossier du plugin, la mise à jour du plugin ne touche jamais vos traductions. Les fichiers placés à l'intérieur du propre dossier du plugin sont écrasés dès l'installation d'une nouvelle version.

Ce comportement de surcharge est l'une des fonctionnalités les plus utiles et les moins connues de la localisation WordPress. Cela signifie que vous pouvez livrer des traductions personnalisées ou corrigées pour n'importe quel plugin tiers sans jamais le forker, et vos modifications sont entièrement sécurisées contre les mises à jour. Si vous gérez plusieurs sites clients exécutant le même plugin, vous pouvez même conserver un seul ensemble de fichiers .mo de surcharge et les déployer sur tous, sachant que chaque site les récupérera automatiquement tant que la locale correspond.

Comment WordPress charge votre traduction

Un plugin prêt à être traduit indique à WordPress de charger son catalogue en appelant load_plugin_textdomain() lors de l'initialisation :

add_action( 'init', function() {
    load_plugin_textdomain(
        'awesome-plugin',
        false,
        dirname( plugin_basename( __FILE__ ) ) . '/languages'
    );
} );

Pour la plupart des plugins modernes sur WordPress 4.6 et versions ultérieures, vous n'avez pas besoin d'y toucher. WordPress charge automatiquement les traductions depuis wp-content/languages/plugins/ tant que le nom de votre fichier et la locale de votre site correspondent. Si votre traduction finale n'apparaît toujours pas, la cause est presque toujours une non-concordance du nom de fichier, un fichier .mo obsolète, ou une langue de site définie sur la mauvaise locale. Notre guide de dépannage pour les traductions qui n'apparaissent pas examine chacun de ces points de défaillance.

Plugins qui stockent les chaînes de caractères dans la base de données

Voici la limitation importante. L'approche Gettext ne traduit que les chaînes de caractères qui résident dans le code du plugin. Certains plugins, en particulier les constructeurs de formulaires, les constructeurs de pages et les extensions de commerce électronique, vous permettent de créer du contenu (libellés de formulaire, attributs de produit, messages personnalisés) qui est enregistré dans la base de données WordPress. Ces chaînes sont des données générées par l'utilisateur, ne faisant pas partie du .pot, donc un fichier .po ne peut pas les atteindre. Pour le contenu de la base de données, vous avez besoin d'un plugin multilingue comme WPML ou Polylang, ou de la propre fonctionnalité de traduction de chaînes du plugin. Testez toujours si une chaîne donnée se trouve dans le code ou dans la base de données avant de supposer qu'un fichier .po peut la corriger.

Un test simple vous indique à quel type de chaîne vous avez affaire. Si le texte est quelque chose que vous avez tapé dans un champ de réglage, un libellé de formulaire que vous avez créé, un message de remerciement personnalisé, un nom de produit, il s'agit de contenu de base de données et un .po ne peut pas y toucher. Si le texte fait partie de l'interface intégrée du plugin, des libellés de bouton, des erreurs de validation, des avis d'administration livrés avec le plugin lui-même, il réside dans le code et un fichier .po est exactement l'outil approprié. Faire cette distinction tôt permet d'économiser des heures de frustration, car aucune quantité d'édition parfaite de .po ne traduira jamais une chaîne que le plugin extrait de la base de données au moment de l'exécution.

Traduire à grande échelle sans l'effort manuel

Traduire un plugin dans une langue à la main est gérable. Le traduire dans dix langues, ou traduire toute une pile de plugins pour le site d'un client, se transforme en des jours de travail répétitif, et chaque modification manuelle risque de gâcher un espace réservé comme %s ou %1$s et de casser la sortie.

C'est là qu'un flux de travail dans le cloud change la donne. Téléchargez le fichier .po ou .pot du plugin sur SimplePoTranslate, choisissez vos langues cibles, et l'IA sensible au contexte traduit l'ensemble du catalogue tandis que le verrouillage de syntaxe gèle chaque espace réservé, balise HTML et jeton de code afin que rien ne puisse être rompu. Le traitement par lots intelligent gère les grands catalogues en un seul passage, et vous téléchargez un ZIP contenant des fichiers .po, .mo, .json, .php et .xliff ensemble, correctement formatés et prêts à être déposés dans wp-content/languages/plugins/. Tout fonctionne entièrement dans le cloud, il n'y a donc pas d'installation de bureau et pas de surcharge sur votre site.

Notez que la traduction d'un plugin diffère de celle d'un thème, qui utilise une convention de dossier et une fonction de chargement légèrement différentes. Si un thème est votre cible, suivez plutôt notre guide dédié sur comment localiser n'importe quel thème WordPress même si vous n'êtes pas développeur.

Utilisez la méthode manuelle lorsque vous avez un seul plugin et une seule langue. Utilisez le cloud lorsque vous avez besoin de nombreuses langues, rapidement, sans sacrifier la sécurité des espaces réservés.

Prêt à traduire votre plugin WordPress dans toutes les langues parlées par votre public sans casser une seule variable ? Essayez SimplePoTranslate gratuitement — aucune carte de crédit requise. Le forfait gratuit vous permet de traduire votre premier fichier .po de plugin en quelques minutes, avec verrouillage de syntaxe sur chaque chaîne.