Pourquoi vos chaînes restent en anglais malgré Loco Translate : le conflit de text domain

« Pourquoi la moitié de mes chaînes restent en anglais alors que j’ai bien créé mon fichier .mo avec Loco Translate ? » C’est la question qui revient le plus souvent lorsqu’un client traduit lui-même un thème enfant construit sur un thème premium anglophone.

La réponse tient en une ligne : un thème enfant qui ne déclare pas explicitement son propre chargement de traductions hérite du text domain du parent, mais pas forcément de son dossier de langues. Les deux notions sont distinctes, et c’est précisément là que la confusion s’installe.

Comprendre le mécanisme de chargement

Un thème déclare son text domain dans l’en-tête de style.css avec la ligne Text Domain: mon-theme, puis charge ses fichiers de traduction avec load_theme_textdomain( 'mon-theme', get_template_directory() . '/languages' ), généralement accroché au hook after_setup_theme. Le problème apparaît quand le thème enfant réutilise le même text domain que le parent — ce qui est fréquent, car de nombreux développeurs de thèmes premium ne changent pas le domaine pour le thème enfant généré automatiquement — sans reproduire l’appel à load_theme_textdomain() pointant vers son propre dossier /languages.

Résultat : WordPress charge les traductions du parent (situées dans wp-content/themes/theme-parent/languages/), et ignore totalement le fichier .mo déposé par Loco Translate dans wp-content/themes/theme-parent-enfant/languages/, car rien ne lui dit d’aller chercher là.

Où Loco Translate dépose réellement les fichiers

Loco Translate, par défaut, enregistre les traductions personnalisées dans wp-content/languages/themes/ plutôt que dans le dossier du thème lui-même, précisément pour survivre aux mises à jour. C’est une bonne pratique, mais elle ajoute un troisième emplacement possible à vérifier : WordPress cherche successivement dans wp-content/languages/themes/text-domain-fr_FR.mo, puis dans le dossier du thème actif, selon l’ordre défini par load_textdomain() en interne.

Diagnostic pas à pas

1. Vérifier le text domain déclaré dans style.css du thème parent ET du thème enfant : sont-ils identiques ?
2. Chercher dans functions.php du parent l’appel à load_theme_textdomain() et noter le dossier ciblé
3. Vérifier si le thème enfant appelle également load_theme_textdomain(), ou s’il compte uniquement sur l’héritage
4. Localiser les fichiers .mo générés par Loco Translate : dossier du thème enfant, ou wp-content/languages/themes/ ?
5. Confirmer que le nom de fichier respecte le format text-domain-fr_FR.mo avec le bon code de langue

Sur un cas récent, le thème parent chargeait son text domain via load_theme_textdomain( 'astra', get_template_directory() . '/languages' ). Le thème enfant, lui, ne faisait aucun appel équivalent : ses chaînes personnalisées ajoutées dans functions.php enfant utilisaient pourtant __( 'Prendre rendez-vous', 'astra' ), en réutilisant le même domaine. Sans second appel de chargement pointant vers le dossier de l’enfant, ces chaînes spécifiques ne trouvaient jamais leur traduction, même correctement saisie dans Loco Translate.

La correction en pratique

Deux approches fonctionnent, selon le niveau de contrôle souhaité :

// Dans functions.php du thème enfant
add_action( 'after_setup_theme', function() {
    load_theme_textdomain(
        'astra',
        get_stylesheet_directory() . '/languages'
    );
} );

Cette solution fonctionne si l’appel du thème enfant s’exécute après celui du parent, ou si l’on force un domaine distinct pour l’enfant, ce qui est plus propre à long terme :

// Utiliser un text domain distinct pour l'enfant
// dans style.css : Text Domain: astra-enfant

add_action( 'after_setup_theme', function() {
    load_child_theme_textdomain(
        'astra-enfant',
        get_stylesheet_directory() . '/languages'
    );
} );

La fonction load_child_theme_textdomain() existe précisément pour ce cas de figure : elle cible systématiquement le dossier du thème enfant, sans ambiguïté sur l’ordre des hooks.

Conseils pour Loco Translate et WPML

Avec Loco Translate, privilégier l’enregistrement de la traduction directement sous « Thèmes > Thème enfant » dans l’interface, plutôt que sous le thème parent, garantit que le fichier atterrit au bon endroit. Avec WPML, le module String Translation intercepte les appels à __() et _e() à un niveau différent, indépendant du chargement de fichiers .mo classique ; le symptôme de chaînes non traduites vient alors plutôt d’un défaut de scan des chaînes du thème enfant dans les réglages de WPML, à vérifier séparément.

Pour aller plus loin

Ce type de conflit se prévient en amont : dès la création d’un thème enfant destiné à être traduit par un client non technique, mieux vaut lui attribuer son propre text domain et documenter clairement, dans un fichier readme.txt du thème enfant, où déposer les fichiers .mo/.po. Deux minutes de configuration en début de projet évitent des heures de support a posteriori.