# Traductions JavaScript manquantes tant qu’un bloc n’a pas déclaré son domaine

> Un tutoriel pas à pas pour traduire les chaînes JavaScript d'un bloc Gutenberg personnalisé grâce à la fonction cœur dédiée, sans extension tierce.

- Auteur : WordPress Développement
- Publié le : 2023-05-22
- Mis à jour le : 2023-05-22
- Catégorie : Multilingue
- URL : https://www.wpmoderne.fr/multilingue/traduire-chaines-javascript-bloc-domaine/

## L’essentiel

- wp_set_script_translations relie un script à ses fichiers de langue
- Les chaînes JS utilisent __ de la bibliothèque @wordpress/i18n
- Le fichier .json généré doit porter le hash md5 du chemin du script

« 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.

> L'essentiel à retenir : wp_set_script_translations relie un script à ses fichiers de langue ; Les chaînes JS utilisent __ de la bibliothèque @wordpress/i18n ; Le fichier .json généré doit porter le hash md5 du chemin du script

```
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-purge
```

La 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 `.json` attendu 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.