Comment créer un fichier .pot pour un thème ou un plugin

Vous venez de terminer un plugin WordPress que vous souhaitez partager avec le monde. Le code fonctionne, les fonctionnalités sont solides, et quelqu'un en Allemagne vous envoie un e-mail demandant comment le traduire en allemand. Vous les dirigez vers le dossier languages et réalisez qu'il n'y a rien. Pas de modèle, pas de chaînes, aucun moyen pour un traducteur de savoir ce qui doit être traduit. Votre plugin est techniquement « prêt pour la traduction » de nom seulement.

Chaque projet WordPress traduisible commence par un fichier : le modèle .pot. Avant que quiconque puisse produire une version allemande, française ou japonaise, vous devez créer un fichier POT qui répertorie chaque chaîne visible par l'utilisateur dans votre code. Sautez cette étape et les traducteurs seront contraints de lire votre code source ligne par ligne, devinant quelles chaînes sont censées être visibles.

Ce guide explique les deux moitiés du travail : préparer votre code source afin que les chaînes soient découvrables, puis générer le .pot lui-même avec trois outils différents. Nous utiliserons WP-CLI, Poedit, et l'approche historique makepot/grunt, avec des commandes réelles que vous pouvez copier. À la fin, vous disposerez d'un modèle propre, prêt à être remis à n'importe quel traducteur.

Étape Un : Marquez vos chaînes comme traduisibles

Avant de pouvoir créer un fichier POT, chaque chaîne qu'un utilisateur pourrait voir doit être enveloppée dans une fonction Gettext. Un scanner ne peut extraire que les chaînes qu'il reconnaît, et il les reconnaît grâce à ces appels de fonction — les littéraux de chaîne simples lui sont invisibles.

WordPress fournit une famille de fonctions de localisation, chacune pour un contexte légèrement différent :

// Return a translated string
$label = __( 'Add to Cart', 'my-plugin' );

// Echo a translated string directly
_e( 'Your cart is empty', 'my-plugin' );

// Translate with context to disambiguate identical words
$verb = _x( 'Post', 'verb: to publish', 'my-plugin' );

// Translate AND escape for safe HTML output
echo esc_html__( 'Welcome back', 'my-plugin' );

Le deuxième argument dans chaque appel — 'my-plugin' — est le domaine de texte. Il regroupe toutes les chaînes d'un plugin ou d'un thème sous un seul espace de noms afin que WordPress sache quel fichier .mo charger pour celles-ci. Chaque chaîne traduisible de votre projet doit partager exactement le même domaine de texte, sinon certaines chaînes ne seront jamais traduites.

Utilisez _x() chaque fois qu'un mot est ambigu. Le mot anglais « Post » peut être un nom ou un verbe, et de nombreuses langues les traduisent différemment. Les chaînes de contexte permettent aux traducteurs de les distinguer. Et utilisez les variantes esc_html__() et esc_attr__() chaque fois que la chaîne traduite est imprimée en HTML, afin de rester sécurisé et localisé en même temps.

Quelques habitudes permettent de maintenir vos chaînes extractibles. Passez toujours un littéral de chaîne simple comme premier argument — jamais une variable ou une concaténation comme __( 'Hello ' . $name, 'my-plugin' ), car le scanner lit le texte source de manière statique et ne peut pas résoudre les valeurs d'exécution. Pour les phrases avec un nombre, utilisez _n() afin que les formes plurielles soient correctement capturées, et pour les phrases avec une valeur dynamique, utilisez sprintf() autour d'un espace réservé tel que %s plutôt que de coller des chaînes ensemble. La cohérence ici est ce qui permet à l'étape suivante — la génération du modèle — de produire un résultat complet et utilisable.

Étape Deux : Déclarez le domaine de texte dans votre en-tête

WordPress a besoin de deux champs d'en-tête pour savoir où se trouvent vos traductions : le Domaine de texte et le Chemin du domaine. Définissez-les dans le fichier principal de votre plugin ou dans le style.css de votre thème, et WordPress chargera automatiquement le bon fichier .mo au moment de l'exécution.

<?php
/**
 * Plugin Name:       My Plugin
 * Description:        A perfectly localized WordPress plugin.
 * Version:            1.0.0
 * Requires at least: 6.4
 * Text Domain:       my-plugin
 * Domain Path:       /languages
 */

Le Domaine de texte doit correspondre à la chaîne que vous avez passée à chaque appel __() et _e() — my-plugin ici. Le Chemin du domaine indique à WordPress quel sous-dossier contient les fichiers de traduction, par rapport à la racine du plugin ou du thème. La convention est /languages, et c'est exactement là que votre fichier .pot généré devrait se trouver.

Une fois les chaînes enveloppées et l'en-tête déclaré, votre code est prêt à être scanné. La vue d'ensemble de la préparation d'un projet pour la traduction — y compris les thèmes qui ne sont pas les vôtres — est couverte dans comment localiser n'importe quel thème WordPress même si vous n'êtes pas développeur.

Comment générer le fichier .pot ? Trois méthodes

Vous générez un .pot en exécutant un scanner sur votre code source qui trouve chaque appel Gettext et écrit les chaînes dans un modèle. Voici trois façons fiables de le faire, de la méthode moderne par défaut à l'approche historique.

Méthode 1 : WP-CLI (Recommandée)

La méthode officielle et moderne pour créer un fichier POT est WP-CLI avec la commande i18n. Elle est livrée avec les outils de base de WordPress, comprend les chaînes PHP et JavaScript, et produit un modèle conforme aux normes en une seule ligne.

# Run from your plugin or theme root directory
wp i18n make-pot . languages/my-plugin.pot

# Add a text domain explicitly if auto-detection misses it
wp i18n make-pot . languages/my-plugin.pot --domain=my-plugin

# Scan only specific paths and exclude vendor folders
wp i18n make-pot . languages/my-plugin.pot --exclude=vendor,node_modules

Le premier argument est le répertoire source (. pour le dossier actuel), et le second est le chemin de sortie. WP-CLI parcourt vos fichiers, extrait chaque chaîne enveloppée, enregistre le fichier source et le numéro de ligne comme commentaire, et écrit le .pot. C'est rapide, scriptable et le bon choix pour tout projet sérieux.

Le modèle généré inclut des métadonnées utiles que vous pouvez ajuster avec des drapeaux supplémentaires. Passez --headers pour définir le nom du projet, la version et l'adresse de contact des traducteurs, afin que le bloc d'en-tête du .pot soit correctement rempli plutôt que laissé comme des espaces réservés. WP-CLI extrait également automatiquement les chaînes JavaScript des appels wp_set_script_translations(), ce qui est important pour les thèmes de blocs modernes et les plugins Gutenberg où la moitié du texte visible par l'utilisateur se trouve en JavaScript plutôt qu'en PHP. Une seule commande couvre les deux mondes.

Méthode 2 : Poedit (Graphique)

Si vous préférez une application de bureau, Poedit peut scanner votre source et générer le modèle via son interface. Ouvrez Poedit, choisissez de créer une nouvelle traduction à partir de POT ou de scanner directement les sources, indiquez-lui le dossier de votre projet et configurez les mots-clés sources (__, _e, _x, esc_html__) sous les propriétés du catalogue.

Les fonctionnalités de scan de sources et de génération de .pot de Poedit se trouvent dans son édition Pro, mais le flux de travail est convivial pour les développeurs qui préfèrent cliquer plutôt que taper des commandes. C'est aussi un éditeur solide pour la phase de traduction qui suit. Poedit et plusieurs autres options de bureau sont comparés dans les 5 meilleurs outils gratuits pour éditer et traduire des fichiers PO sur Mac et Windows.

Méthode 3 : makepot / grunt (Héritée)

Avant WP-CLI, l'outil standard était le script makepot.php du dépôt WordPress i18n-tools, souvent intégré à une tâche de build Grunt avec grunt-wp-i18n. Vous le rencontrerez encore dans les anciens plugins et thèmes.

# Legacy makepot.php invocation
php makepot.php wp-plugin /path/to/my-plugin languages/my-plugin.pot

Cela fonctionne, mais c'est moins maintenu que WP-CLI et plus lent à configurer. Utilisez-le uniquement lorsque vous maintenez un projet hérité qui en dépend déjà ; pour tout nouveau projet, préférez wp i18n make-pot.

Maintenez le modèle à jour au fur et à mesure que votre code évolue

Un .pot est un instantané de vos chaînes à un moment donné. Chaque fois que vous ajoutez une fonctionnalité, modifiez une étiquette ou corrigez une faute de frappe dans une chaîne visible, le modèle devient obsolète et les traducteurs manquent la nouvelle formulation.

Faites de la régénération une partie de votre routine de publication. Réexécutez wp i18n make-pot avant chaque montée de version, puis fusionnez le modèle actualisé dans les traductions existantes avec wp i18n update-po ou msgmerge afin que les traducteurs conservent leur travail terminé et ne voient que les nouvelles lacunes. Traitez le .pot comme un artefact de build que vous régénérez, et non comme un fichier que vous éditez manuellement.

Un modèle obsolète provoque une défaillance subtile et frustrante : de nouvelles chaînes apparaissent en anglais même sur un site « entièrement traduit », car elles n'étaient jamais dans le fichier .pot à partir duquel le traducteur a travaillé. Détecter cela est aussi simple que de scriptériser la régénération dans votre build, afin que le modèle ne puisse jamais être en décalage par rapport au code. Certaines équipes ajoutent une vérification CI qui fait échouer le build si la régénération du .pot produit un diff, garantissant que le modèle committé correspond toujours à la source actuelle.

Une fois que les traducteurs renvoient les fichiers .po terminés, ceux-ci doivent encore être compilés en fichiers binaires .mo que WordPress charge réellement — et si vous préférez sauter toute la boucle de téléchargement-traduction-recompilation, un outil cloud peut gérer cela de bout en bout. SimplePoTranslate accepte directement votre .pot, le traduit avec une IA contextuelle qui comprend ce que chaque chaîne signifie dans votre interface, et renvoie un seul ZIP avec les fichiers .po, .mo et plus déjà construits et nommés. Son Verrouillage de syntaxe gèle les espaces réservés comme %s et %1$s afin que vos variables ne soient jamais cassées lors de la traduction.

En résumé

Pour créer un fichier POT correctement, rendez d'abord votre code découvrable — enveloppez chaque chaîne visible dans __(), _e(), _x(), ou une variante d'échappement, toutes partageant un seul domaine de texte, et déclarez ce domaine ainsi que le Domain Path dans votre en-tête. Ensuite, générez le modèle avec WP-CLI pour les nouveaux projets, Poedit si vous préférez une interface graphique, ou makepot uniquement lors de la maintenance de code hérité.

Générez tôt, régénérez souvent, et ne laissez jamais votre modèle prendre du retard sur votre code. Un fichier .pot à jour fait la différence entre un plugin réellement prêt pour le monde et un plugin qui ne fait que le prétendre.

Prêt à transformer votre modèle .pot en traductions finalisées sans la danse manuelle de compilation ? Essayez SimplePoTranslate gratuitement — aucune carte de crédit requise. Téléchargez votre modèle sur le niveau gratuit et téléchargez des fichiers de traduction prêts à l'emploi en quelques minutes.