# Chaînes de thème qui refusent de se traduire : symptômes, causes et correctifs

> « Add to cart » qui reste en anglais sur un site pourtant traduit en français : ce bug classique a toujours la même poignée de causes. Voici comment le résoudre.

- Auteur : Clément Hadrot
- Publié le : 2022-03-08
- Mis à jour le : 2022-03-08
- Catégorie : Multilingue
- URL : https://wpmoderne.dev.wordpress-developpement.fr/multilingue/chaines-theme-non-traduites-diagnostic/

## L’essentiel

- Un domaine de texte non chargé rend toutes les chaînes invisibles au système de traduction
- Les fichiers .mo doivent correspondre exactement à la locale active
- Un texte codé en dur dans le thème n'est jamais traduisible

« Notre site est traduit en français, mais le bouton du panier affiche encore Add to Cart. » Cette phrase revient presque mot pour mot dans un audit sur cinq que nous menons sur des sites e-commerce multilingues. Le symptôme est toujours le même : une chaîne isolée, souvent un libellé de bouton ou un message système, refuse obstinément de basculer en français alors que le reste du contenu est parfaitement traduit.

Ce type de panne a une poignée de causes récurrentes, presque toujours les mêmes, qu'il s'agisse d'un thème du répertoire officiel, d'un thème premium, ou d'un développement sur mesure. Cet article détaille la méthode de diagnostic, cause par cause.

## Cause n°1 : un texte codé en dur, jamais passé par l'API i18n

La cause la plus fréquente, et la plus simple à vérifier : le texte n'est tout simplement pas internationalisé dans le code du thème. Un développeur pressé écrit parfois directement `echo 'Add to Cart';` au lieu de `echo esc_html__( 'Add to Cart', 'mon-theme' );`. Dans ce cas, aucune extension multilingue au monde ne peut proposer une traduction : le texte n'existe dans aucun système de chaînes traduisibles.

Le diagnostic est immédiat : rechercher la chaîne exacte dans les fichiers du thème actif.

```
grep -rn "Add to Cart" wp-content/themes/mon-theme/
```

Si le résultat montre une chaîne entre guillemets simples sans fonction `__()` ou `_e()` autour, la cause est confirmée. La correction consiste à réécrire le code source du thème pour internationaliser correctement la chaîne — une modification qui doit passer par un thème enfant si le thème parent est un thème du répertoire officiel mis à jour régulièrement, sous peine de voir la correction écrasée à la prochaine mise à jour.

## Cause n°2 : le domaine de texte du thème n'est pas chargé

Même correctement enveloppée dans `__()`, une chaîne reste invisible au système de traduction si le thème ne charge jamais son domaine de texte. Cette étape, obligatoire, s'effectue via `load_theme_textdomain()` (pour un thème classique) ou automatiquement pour les thèmes hébergés sur WordPress.org depuis WordPress 4.6, à condition que l'en-tête `Text Domain` du fichier `style.css` corresponde exactement au domaine utilisé dans le code :

```
<?php
add_action( 'after_setup_theme', function() {
    load_theme_textdomain( 'mon-theme', get_template_directory() . '/languages' );
} );
```

Une erreur fréquente : un domaine de texte qui diffère entre l'en-tête du fichier `style.css` (`Text Domain: mon-theme`) et celui utilisé dans les appels PHP (`__( 'Texte', 'montheme' )`, sans tiret). La moindre différence de casse ou de tiret empêche toute correspondance, sans qu'aucun message d'erreur ne s'affiche nulle part.

> L'essentiel à retenir : Un domaine de texte non chargé rend toutes les chaînes invisibles au système de traduction ; Les fichiers .mo doivent correspondre exactement à la locale active ; Un texte codé en dur dans le thème n'est jamais traduisible

## Cause n°3 : un fichier .mo absent ou mal nommé

Une fois le domaine de texte correctement chargé, encore faut-il qu'un fichier de traduction compilé existe pour la locale active. WordPress attend un fichier nommé selon la convention `domaine-locale.mo`, par exemple `mon-theme-fr_FR.mo`, placé dans le dossier déclaré lors du chargement du domaine de texte (généralement `/languages/` à la racine du thème).

Deux erreurs classiques ici : un fichier nommé `mon-theme-fr.mo` au lieu de `mon-theme-fr_FR.mo` (la locale complète avec le code de pays est requise), ou un fichier `.po` présent sans son équivalent `.mo` compilé — seul le fichier `.mo`, binaire, est lu par WordPress à l'exécution. Un outil comme Poedit ou la commande WP-CLI `wp i18n make-mo` permet de générer le fichier `.mo` à partir du `.po` :

```
wp i18n make-mo languages/
```

### Le cas particulier des chaînes gérées par un plugin multilingue

Si le thème est utilisé sur un site avec WPML ou Polylang, ces extensions proposent leur propre couche de traduction des chaînes (String Translation pour WPML, Chaînes de traduction pour Polylang), qui vient s'ajouter — ou parfois se substituer — au système de fichiers `.mo` classique. Une chaîne peut donc échouer à se traduire via `.mo` tout en étant traduisible via l'interface du plugin, à condition que le thème charge correctement son domaine de texte : sans ce chargement, ni les fichiers `.mo` ni la détection automatique du plugin multilingue ne peuvent fonctionner, puisque WPML et Polylang s'appuient tous deux sur les mêmes fonctions `__()` et `_e()` pour repérer les chaînes à traduire.

## Méthode de diagnostic complète, dans l'ordre

1. La chaîne est-elle enveloppée dans une fonction i18n (`__()`, `_e()`, `esc_html__()`) dans le code source du thème ?
2. Le domaine de texte utilisé correspond-il exactement à celui déclaré dans l'en-tête du thème ?
3. Le domaine de texte est-il bien chargé via `load_theme_textdomain()` ou automatiquement (thème hébergé WordPress.org) ?
4. Un fichier `.mo` correctement nommé existe-t-il pour la locale active, ou la chaîne apparaît-elle dans l'interface du plugin multilingue utilisé ?
5. Le cache d'objets ou de page ne sert-il pas une version figée d'avant la correction (à purger systématiquement après toute modification) ?

> Notre réflexe en audit : lancer une recherche `grep` sur la chaîne exacte signalée par le client avant toute autre vérification. Neuf fois sur dix, la réponse à « pourquoi ce texte ne se traduit pas » tient en une seule ligne de code mal écrite, repérable en quelques secondes.

## En résumé

Une chaîne de thème récalcitrante à la traduction obéit presque toujours à l'une de ces trois causes : un texte jamais internationalisé, un domaine de texte non chargé ou mal nommé, ou un fichier de traduction absent ou mal formé. Une vérification méthodique, commençant par une simple recherche dans le code source, résout la quasi-totalité de ces cas en quelques minutes, bien avant d'envisager une réinstallation de plugin ou une réinitialisation de cache hasardeuse.