Options du Customizer restées identiques dans toutes les langues : le diagnostic

Sur un site vitrine pour un cabinet de conseil en stratégie, présent en français et en anglais, le développeur du thème enfant avait ajouté une option Customizer permettant de modifier le texte d’accroche affiché en haut de la page d’accueil, du type « Nous accompagnons les dirigeants dans leurs décisions stratégiques ». Une fois la version anglaise activée, ce même texte français restait affiché, alors que le reste du contenu de la page était parfaitement traduit par WPML.

Ce cas revient très régulièrement sur les thèmes enfants sur mesure, car une option Customizer, contrairement à un champ de contenu classique (titre de page, contenu d’article), n’est jamais traduisible par défaut aux yeux de WPML, quelle que soit la qualité de la configuration multilingue par ailleurs.

Symptôme : un texte figé indépendamment de la langue active

Le symptôme est toujours le même : un champ saisi une seule fois dans Apparence → Personnaliser s’affiche à l’identique sur toutes les langues du site, y compris lorsque toutes les autres chaînes de la page changent correctement selon la langue. Contrairement à une chaîne de thème classique détectée automatiquement par le scanner de chaînes WPML, une valeur de Customizer n’est pas exposée nativement à ce scanner.

Diagnostic : comprendre le stockage d’une option Customizer

Techniquement, une option définie via l’API du Customizer est enregistrée comme un theme_mod, stocké dans la table wp_options sous une clé unique de la forme theme_mods_nom-du-theme. Cette clé est globale au thème actif, pas rattachée à une langue : toutes les langues gérées par WPML sur la même installation lisent donc la même valeur via get_theme_mod().

// Déclaration typique dans le thème enfant, functions.php
function mon_theme_customize_register( $wp_customize ) {
    $wp_customize->add_setting( 'texte_accroche', array(
        'default'   => 'Nous accompagnons les dirigeants...',
        'transport' => 'refresh',
    ) );
    $wp_customize->add_control( 'texte_accroche', array(
        'label'   => "Texte d'accroche",
        'section' => 'title_tagline',
        'type'    => 'text',
    ) );
}
add_action( 'customize_register', 'mon_theme_customize_register' );

Rien dans ce code ne signale à WPML que texte_accroche est un champ traduisible. C’est un oubli fréquent, y compris chez des développeurs expérimentés en multilingue, car le réflexe d’enregistrement s’applique naturellement aux chaînes de thème (__(), _e()) mais rarement aux réglages du Customizer.

Correctif : déclarer le champ via wpml-config.xml

WPML propose un mécanisme dédié pour ce cas précis : le fichier wpml-config.xml, placé à la racine du thème ou d’un plugin, permet de déclarer des theme_mods comme traduisibles sans modifier le code du thème lui-même.

<wpml-config>
    <custom-fields>
    </custom-fields>
    <theme-mods>
        <key name="texte_accroche" translate="1" />
    </theme-mods>
</wpml-config>

Une fois ce fichier ajouté et le cache WPML vidé, le champ texte_accroche apparaît dans WPML → Traduction des chaînes comme n’importe quelle autre chaîne de thème, avec une traduction distincte possible par langue.

Attention à l’ordre de résolution

Un piège fréquent : si le champ a déjà été modifié dans le Customizer avant l’ajout de wpml-config.xml, WPML ne récupère pas automatiquement l’historique des valeurs passées. Il faut relancer le scanner de chaînes (WPML → Traduction des chaînes → Scanner les thèmes à la recherche de chaînes) pour que la valeur actuelle du champ soit reprise comme chaîne source à traduire.

Prévention pour les prochains projets de thème sur mesure

• Systématiser l’ajout d’un fichier wpml-config.xml dès la première option Customizer ajoutée à un thème enfant destiné à un site multilingue.
• Préférer, quand c’est possible, un champ ACF traduisible nativement plutôt qu’une option Customizer pour du contenu éditorial appelé à être traduit.
• Documenter dans le cahier de recette du thème la liste des theme_mods ajoutés, pour que l’équipe multilingue ne découvre pas le problème après livraison.

Une option Customizer ajoutée sans réflexion multilingue n’est pas un bug de WPML : c’est un oubli de déclaration, corrigible en une poignée de lignes XML, à condition de savoir où chercher.

Ce que cet article ne traite pas

Ce cas concerne spécifiquement les réglages du Customizer. La traduction des chaînes de thème classiques appelées via __() ou _e() dans les templates PHP suit un mécanisme de détection automatique différent, déjà traité précédemment.

En résumé

Une valeur saisie dans le Customizer reste, par défaut, partagée entre toutes les langues d’un site WPML car elle est stockée comme un simple theme_mod global. La déclarer traduisible ne nécessite ni modification du thème ni développement complexe : un fichier wpml-config.xml avec la clé concernée suffit, à condition de relancer le scanner de chaînes après son ajout.