« Pourquoi mes chaînes PHP se traduisent correctement mais pas celles de mon bloc, écrites en JavaScript ? » C’est une question récurrente chez les développeurs qui découvrent que la traduction des blocs Gutenberg personnalisés suit un circuit différent de la traduction PHP classique, avec sa propre fonction d’enregistrement et son propre format de fichier.
Ce tutoriel montre, étape par étape, comment relier correctement un script de bloc à ses fichiers de traduction grâce à wp_set_script_translations(), sans dépendre d’une extension tierce.
Étape 1 : écrire les chaînes avec la bibliothèque @wordpress/i18n
Côté JavaScript, les chaînes destinées à être traduites doivent passer par les fonctions fournies par le paquet @wordpress/i18n, importées en haut du fichier source du bloc, avant compilation par l’outillage de build officiel.
import { __ } from '@wordpress/i18n';
const label = __( 'Choisir une image de couverture', 'mon-bloc' );À ce stade, sans rien de plus, la chaîne reste figée en français : elle est bien repérable par les outils d’extraction, mais aucun mécanisme ne relie encore le script à un quelconque fichier de traduction chargé côté navigateur.
Étape 2 : enregistrer le script normalement
Le script du bloc est enregistré côté PHP comme n’importe quel script WordPress, avec wp_register_script(), en indiquant ses dépendances, dont wp-i18n qui correspond au paquet importé côté JavaScript.
wp_register_script(
'mon-bloc-editor',
plugins_url( 'build/index.js', __FILE__ ),
array( 'wp-blocks', 'wp-element', 'wp-i18n', 'wp-editor' ),
filemtime( plugin_dir_path( __FILE__ ) . 'build/index.js' )
);Étape 3 : relier le script à son domaine de traduction
C’est l’étape que beaucoup de développeurs oublient : l’appel à wp_set_script_translations(), qui relie explicitement le handle du script à un textdomain et à un dossier de fichiers de traduction. Sans cet appel, WordPress ne sait pas où chercher les traductions correspondant à ce script, et les chaînes restent affichées dans leur langue source quelle que soit la langue active du site.
wp_set_script_translations(
'mon-bloc-editor',
'mon-bloc',
plugin_dir_path( __FILE__ ) . 'languages'
);Étape 4 : générer les fichiers .json au bon format
Contrairement aux traductions PHP qui utilisent des fichiers .mo, les traductions JavaScript sont chargées depuis des fichiers .json, un par langue et par script, dont le nom suit une convention précise : le textdomain, la locale, puis un condensé MD5 du chemin relatif du fichier JavaScript source, séparés par des tirets.
wp i18n make-json languages/ --no-purgeLa commande wp i18n make-json, une fois les fichiers .po traduits pour chaque locale, génère automatiquement les fichiers .json nommés correctement à partir du fichier .po correspondant, en calculant elle-même le condensé attendu par WordPress.
Étape 5 : vérifier que la traduction s’affiche bien
Une fois le fichier .json généré et déposé dans le dossier languages déclaré à l’étape 3, il suffit de changer la langue de l’administration WordPress dans les réglages du profil utilisateur, puis de recharger l’éditeur de blocs. La chaîne __( 'Choisir une image de couverture', 'mon-bloc' ) doit s’afficher traduite si tout est correctement relié.
- Vérifier dans les outils de développement du navigateur que le fichier
.jsonattendu est bien chargé, sans erreur 404. - Vérifier que le nom du fichier correspond exactement au condensé calculé par WordPress pour ce script.
- Vérifier que le textdomain passé à
wp_set_script_translations()correspond à celui utilisé dans__()côté JavaScript.
Le piège du chemin relatif utilisé pour le condensé
Le condensé MD5 attendu dans le nom du fichier .json est calculé à partir du chemin du script tel qu’il est enregistré par wp_register_script(), relatif au dossier de l’extension. Un renommage du dossier de build après génération des fichiers .json, sans relancer wp i18n make-json, casse silencieusement la correspondance : les fichiers existent, mais ne sont jamais chargés parce que leur nom ne correspond plus au condensé attendu.
En résumé
La traduction des chaînes JavaScript d’un bloc personnalisé suit un circuit distinct de la traduction PHP, avec sa propre fonction de liaison, wp_set_script_translations(), et son propre format de fichier, le .json nommé par condensé. Oublier cette étape de liaison est l’erreur la plus fréquente : le code compile, le bloc fonctionne, mais aucune chaîne ne se traduit jamais, sans qu’aucun message d’erreur n’alerte le développeur.
