# Attraper une régression de textdomain dès la revue de code d’un thème traduit

> Une checklist de revue de code pour repérer les régressions de textdomain avant qu'elles n'atteignent la production, chaîne par chaîne.

- Auteur : WordPress Développement
- Publié le : 2022-08-26
- Mis à jour le : 2022-08-26
- Catégorie : Multilingue
- URL : https://www.wpmoderne.fr/multilingue/checklist-revue-code-regression-textdomain/

## L’essentiel

- Un textdomain codé en dur casse dès qu'on renomme le thème
- Les chaînes ajoutées sans fonction de traduction passent inaperçues
- wp i18n make-pot révèle les oublis avant la mise en ligne

Une pull request qui ajoute trois nouvelles chaînes de texte à un thème traduit peut sembler anodine. Elle l'est rarement : un textdomain mal renseigné, une chaîne oubliée dans une fonction de traduction, ou un appel à `__()` sans domaine du tout suffisent à faire disparaître silencieusement une traduction en production, sans qu'aucune erreur PHP ne le signale.

Cette checklist rassemble les points à vérifier systématiquement lors d'une revue de code touchant à l'internationalisation d'un thème ou d'une extension, avant fusion sur la branche principale.

## Vérifier que chaque chaîne visible passe par une fonction de traduction

Le premier point, et le plus basique, consiste à s'assurer qu'aucune chaîne de caractères destinée à l'affichage n'échappe aux fonctions `__()`, `_e()`, `_x()` ou `_n()`. Une chaîne ajoutée directement dans un `echo`, sans fonction de traduction, ne sera jamais remontée par `wp i18n make-pot` et restera bloquée en français quel que soit le fichier de langue chargé.

```
// À corriger en revue
echo 'Ajouter au panier';

// Version correcte
echo esc_html__( 'Ajouter au panier', 'mon-theme' );
```

## Contrôler que le textdomain correspond à celui déclaré dans style.css

Chaque appel de fonction de traduction porte un second argument : le textdomain. Il doit correspondre exactement, caractère pour caractère, à l'en-tête `Text Domain` déclaré dans `style.css` pour un thème, ou dans l'en-tête du fichier principal pour une extension. Une faute de frappe ou un textdomain hérité d'un thème parent mal adapté casse le chargement des traductions sans qu'aucune erreur ne s'affiche : la chaîne reste simplement dans sa langue source.

> L'essentiel à retenir : Un textdomain codé en dur casse dès qu'on renomme le thème ; Les chaînes ajoutées sans fonction de traduction passent inaperçues ; wp i18n make-pot révèle les oublis avant la mise en ligne

- Comparer le textdomain de chaque nouvelle chaîne au `Text Domain` de `style.css`.
- Vérifier qu'aucun copier-coller n'a laissé le textdomain d'un thème précédent.
- Confirmer que le domaine est chargé via `load_theme_textdomain()` avant le premier usage.

## Repasser wp i18n make-pot après chaque lot de chaînes

La commande `wp i18n make-pot . languages/mon-theme.pot` régénère le fichier modèle de traduction à partir du code source. Lancée avant fusion d'une pull request, elle révèle immédiatement les chaînes mal formées : un appel de fonction avec un textdomain manquant apparaît comme une erreur d'analyse, une chaîne concaténée de façon dynamique n'apparaît tout simplement pas dans le fichier généré.

```
wp i18n make-pot . languages/mon-theme.pot --exclude=node_modules,vendor
diff languages/mon-theme.pot languages/mon-theme.pot.orig
```

### Ce que révèle un diff du fichier .pot

Un diff entre l'ancien et le nouveau fichier `.pot` montre exactement les chaînes ajoutées, modifiées ou supprimées par la pull request. C'est le moyen le plus fiable de vérifier qu'aucune chaîne n'a été oubliée : si une nouvelle fonctionnalité affiche du texte à l'écran mais qu'aucune entrée correspondante n'apparaît dans le diff, la chaîne n'est pas traduisible.

## Vérifier les chaînes dynamiques et les variables interpolées

Les fonctions de traduction WordPress n'acceptent que des chaînes littérales, jamais des variables. Un appel comme `__( $texte_dynamique, 'mon-theme' )` ne sera jamais extrait par les outils d'analyse statique, même s'il compile et s'exécute sans erreur. C'est un des oublis les plus fréquents lors de l'ajout de messages construits dynamiquement, par exemple des libellés de statut générés à partir d'une valeur de base de données.

## Contrôler les chaînes JavaScript séparément

Les chaînes affichées côté client, dans un fichier JavaScript de bloc ou de script d'administration, suivent un circuit différent : elles doivent être enregistrées via `wp_set_script_translations()` côté PHP, puis traduites avec les fonctions de la bibliothèque `@wordpress/i18n` côté JavaScript. Une revue de code qui ne vérifie que les fichiers PHP laisse systématiquement passer les régressions côté JavaScript.

## Checklist récapitulative

1. Chaque chaîne visible passe par une fonction de traduction (aucun `echo` brut).
2. Le textdomain de chaque appel correspond exactement à celui de `style.css`.
3. Aucune variable n'est passée en premier argument d'une fonction de traduction.
4. Le fichier `.pot` régénéré contient bien les nouvelles chaînes.
5. Les chaînes JavaScript sont enregistrées via `wp_set_script_translations()`.
6. Les commentaires translators accompagnent les chaînes avec espaces réservés.
7. Un test manuel en changeant la langue du site confirme l'affichage traduit.

## En résumé

Une régression de textdomain ne provoque aucune erreur visible : elle se traduit simplement par une chaîne qui reste obstinément en français malgré un site configuré dans une autre langue. C'est précisément ce qui la rend dangereuse en production et justifie qu'elle fasse l'objet d'une checklist systématique en revue de code, plutôt que d'une vérification informelle laissée au hasard des relectures.