Traduire les textes fixes d’un thème bloc directement issus de theme.json

Un client éditeur de thèmes blocs pour d’autres agences nous a demandé de rendre l’un de ses thèmes compatible multilingue, en vue d’une distribution à des clients francophones et anglophones. Le thème utilisait theme.json, introduit avec WordPress 5.8, pour définir non seulement la palette de couleurs et la typographie, mais aussi certains libellés destinés à l’affichage : des noms de styles de blocs personnalisés visibles dans l’éditeur, ainsi qu’un texte de motif (« pattern ») réutilisé sur plusieurs mises en page.

Le problème est apparu rapidement : ces libellés, définis directement en JSON dans un fichier statique, ne passent jamais par les fonctions de traduction PHP classiques (__(), _e()), et échappent donc complètement au scanner de chaînes de WPML qui, par défaut, analyse les fichiers PHP du thème à la recherche de ces appels.

Où se cachent ces libellés dans theme.json

Plusieurs sections de theme.json contiennent des libellés destinés à être affichés, notamment dans l’interface de l’éditeur de blocs :

{
  "version": 2,
  "settings": {
    "color": {
      "palette": [
        { "slug": "accent", "color": "#c0392b", "name": "Accent principal" }
      ]
    },
    "typography": {
      "fontSizes": [
        { "slug": "large", "size": "1.5rem", "name": "Grand titre" }
      ]
    }
  },
  "styles": {
    "blocks": {
      "core/quote": {
        "variations": {
          "citation-mise-en-avant": { "name": "Citation mise en avant" }
        }
      }
    }
  }
}

Les champs name associés à une couleur de palette, une taille de police ou une variation de style sont ceux qui apparaissent directement dans l’interface de l’éditeur de blocs, en français ici alors que le thème doit aussi être exploitable en anglais. Sans intervention, ces libellés restent strictement identiques quelle que soit la langue de l’administration WordPress choisie par l’utilisateur du thème.

La déclaration manuelle à WPML pour les fichiers JSON

WPML propose depuis plusieurs versions un support pour l’enregistrement de chaînes provenant de sources non-PHP via une fonction dédiée, appelée explicitement au chargement du thème plutôt que détectée par scan automatique :

add_action( 'after_setup_theme', function() {
    if ( ! function_exists( 'icl_register_string' ) ) {
        return;
    }
    $theme_json = wp_get_global_settings();
    icl_register_string( 'theme.json', 'palette_accent_principal', 'Accent principal' );
    icl_register_string( 'theme.json', 'typo_grand_titre', 'Grand titre' );
    icl_register_string( 'theme.json', 'citation_mise_en_avant', 'Citation mise en avant' );
});

Chaque chaîne enregistrée via icl_register_string() apparaît ensuite dans WPML → Traduction des chaînes, sous le domaine « theme.json » choisi ici comme regroupement, où elle peut être traduite comme n’importe quelle autre chaîne de thème. Le libellé traduit doit ensuite être réaffiché à l’endroit concerné via icl_t(), ce qui suppose souvent d’intercepter le rendu de l’éditeur via un filtre JavaScript plutôt qu’un simple appel PHP, ces libellés étant consommés côté client par l’éditeur de blocs.

Le piège classique des patterns PHP codés en dur

Au-delà de theme.json lui-même, ce thème contenait plusieurs fichiers de motifs (« block patterns ») enregistrés via register_block_pattern(), dont le contenu HTML embarquait du texte français codé en dur dans la chaîne de balisage, sans passer par __() :

// Fautif : texte non traduisible dans le contenu du pattern
register_block_pattern( 'mon-theme/accroche', array(
    'title'   => 'Accroche avec image',
    'content' => '<!-- wp:paragraph --><p>Découvrez notre nouvelle collection</p><!-- /wp:paragraph -->',
));

Le correctif consiste à envelopper chaque fragment de texte du pattern dans __(), ce qui le rend cette fois détectable par le scanner de chaînes classique de WPML, sans déclaration manuelle nécessaire :

'content' => '<!-- wp:paragraph --><p>' . esc_html__( 'Découvrez notre nouvelle collection', 'mon-theme' ) . '</p><!-- /wp:paragraph -->',

Ce que nous recommandons pour un thème bloc distribué à plusieurs clients

• Limiter au strict nécessaire les libellés définis directement dans theme.json destinés à l’affichage front, en préférant, quand c’est possible, des libellés génériques peu sensibles à la langue.
• Déclarer systématiquement via icl_register_string() les libellés qui doivent malgré tout y figurer.
• Envelopper tout texte de pattern PHP dans __() dès l’écriture du pattern, plutôt que de le corriger après coup sur un thème déjà distribué.

Un thème bloc pensé pour l’éditeur de site n’est pas automatiquement pensé pour le multilingue : les deux logiques se recoupent partiellement, mais theme.json introduit ses propres angles morts qu’un scanner de chaînes classique ne couvre pas.

Ce que cet article ne traite pas

Les chaînes de thème classiques appelées via __() ou _e() dans des templates PHP standards, détectées nativement par le scanner de chaînes WPML, ont été traitées dans un article dédié dès 2020 et ne sont pas reprises ici.

En résumé

Les libellés définis directement dans theme.json — noms de couleurs de palette, tailles de police, variations de style — échappent au scanner de chaînes automatique de WPML et nécessitent un enregistrement manuel via icl_register_string(). Le contenu des motifs de blocs enregistrés en PHP doit, lui, être systématiquement enveloppé dans les fonctions de traduction classiques dès l’écriture du thème, pour éviter un rattrapage coûteux après distribution.