Internationalisation (i18n) : comment traduire nos blocs Gutenberg ?

La traduction de vos extensions de blocs peut vite être un calvaire, surtout que la procédure a pas mal changé avec le temps, et la documentation n’est pas forcément bien à jour.

Pour ne pas simplifier la tâche, il va falloir être en mesure de traduire les chaînes de texte en PHP, mais également celles en JavaScript, du côté de l’éditeur.

Dans ce cours, on va voir comment rendre tous vos textes traduisibles, qu’ils soient dans le PHP, dans le JS, ou même déclarés en PHP mais utilisés en JS. Le tout, sans devenir fou.

Voici notre feuille de route pour traduire nos blocs et notre extension WordPress :

• Déclarer le Text domain et le Domain path en PHP ;
• Rendre les chaînes PHP traduisibles via la fonction __() ;
• Rendre les blocs traduisibles dans le JS grâce à la librairie @wordpress/i18n ;
• Créer le dossier /languages qui accueillera les traductions ;
• Générer le catalogue des traductions au format .pot via WP-CLI ;
• Traduire les chaînes dans une nouvelle langue grâce à Loco translate ou PoEdit ;
• Générer les fichiers de traductions .mo, .php et .json pour chaque situation ;
• Lier les traductions aux blocs grâce à la fonction wp_set_script_translations() ;

Les traductions devraient alors fonctionner autant dans l’administration WordPress en PHP que dans l’éditeur Gutenberg en JS.

Pour cela, on va avoir besoin de WP-CLI, l’utilitaire de lignes de commandes fourni avec WordPress.

Abordons maintenant ça étape par étape :

Déclarer le textdomain et traduire le PHP

On va commencer avec la base de toute extension WordPress : déclarer le nécessaire pour la traduction des chaînes en PHP.

Aujourd’hui, c’est beaucoup plus simple qu’avant puisque ça se passe dans la déclaration des informations de l’extension, dans les commentaires PHP du premier fichier :

Il y a deux éléments importants à prendre en compte :

• Text Domain qui permet d’isoler les traductions du reste de WordPress ;
• Domain Path qui permet d’indiquer où trouver les traductions.

Si vous avez généré votre extension avec create-block, seul Text Domain sera présent. Il vous faudra alors ajouter Domain Path.

Pour écrire des chaînes de texte traduisibles en PHP, utilisez les fonctions __(), _e(), __x() ou même encore esc_html_e() pour échapper le texte en même temps… Voici un exemple :

Les fonctions comme __() et _e() et _esc_html_e() acceptent 2 arguments :

• La chaîne de texte à traduire, que l’on définit habituellement en anglais par défaut ;
• Le textdomain, qui doit être le même que celui déclaré au début de l’extension.

Le textdomain est très important dans un thème ou une extension, il permet d’isoler vos traductions et éviter les conflits avec des chaînes équivalentes de WordPress ou d’autres extensions.

Après tout, un texte dans votre extension n’aura peut-être pas le même sens ailleurs, et donc la même traduction dans un autre contexte.

C’est tout ce dont on a besoin pour rendre nos textes traduisibles dans une extension classique en PHP. C’était la partie la plus simple et qui n’a quasiment pas changé depuis les débuts de WordPress.

Rendre vos blocs traduisibles

Pour préparer vos blocs à la traduction, il y a quelques petites étapes à respecter.

Tout d’abord, il va falloir indiquer le même textdomain dans le block.json que dans l’extension :

Vous pourriez indiquer un textdomain unique par bloc, mais ça présente peu d’intérêt et ça demanderait plus de manipulations pour les traductions.

Ensuite, dans edit.js, vous pouvez traduire vos chaînes grâce à la fonction __() du package @wordpress/i18n :

Au final, c’est quasiment comme en PHP. On n’utilisera par contre que __() et pas _e(), car en JS la gestion du template est différente : tout est retourné via la fonction return() à React et c’est lui qui s’occupera d’injecter ça dans le DOM ensuite.

Générer le catalogue de traductions (.pot)

Maintenant, on va devoir générer un catalogue de tous les textes traduisibles présents dans notre extension, que ce soit en PHP ou en JS.

Et pour cela, on va utiliser une commande WP-CLI.

Si vous utilisez Local WP, ça va être très simple. Affichez le panneau de gestion de votre site et cliquez sur « Site shell » en haut, sous le titre du site.

Votre terminal préféré devrait s’ouvrir. Vous pouvez d’ailleurs le configurer dans les réglages de LocalWP. Pour ma part, j’utilise Hyper lorsque je suis hors IDE.

Voici les 3 commandes que l’on va exécuter :

La première commande permet de nous déplacer dans le dossier de notre extension. Pensez à modifier selon le nom de votre dossier d’extension.

La seconde commande permet de créer le dossier qui accueillera nos traductions dans l’extension et que l’on nomme /languages/. Vous pourriez tout à fait créer ce dossier à la main depuis votre éditeur de code ou votre explorateur de fichiers.

La troisième permet de lancer la génération du fichier catalogue qui contiendra toutes les chaînes à traduire. Vous pouvez nommer le fichier .pot comme vous le souhaitez, mais c’est une bonne idée de lui donner le même nom que le textdomain.

Traduire les chaînes avec Loco Translate

Maintenant que notre catalogue de traductions est prêt, on va pouvoir créer à partir de celui-ci une traduction pour la langue française dans un premier temps.

Pour cela, installez l’extension gratuite Loco Translate sur votre site local. On va créer le fichier de traduction et traduire les textes grâce à elle.

Vous pourriez tout aussi bien utiliser le logiciel PoEdit, mais vous allez voir que c’est bien plus pratique avec Loco car il va compiler automatiquement les fichiers nécessaires !

Une fois l’extension installée et activée, rendez-vous dans Loco Translate > Accueil et cliquez sur votre extension dans la liste des extensions actives.

Ensuite, cliquez sur « Nouvelle langue » et vous arriverez sur cette interface :

Dans un premier temps, choisissez la langue à créer. Je sélectionne « French (France) » qui correspond à fr_FR.

Ensuite, il faut choisir un emplacement. On va placer le fichier dans notre extension. Sélectionnez donc « Auteur ».

Lorsqu’on souhaite traduire une extension que l’on a téléchargé sur le répertoire, on sélectionnera plutôt « Système », afin que nos traductions personnalisées ne soient pas écrasées lors de la prochaine mise à jour.

Mais dans notre cas, comme c’est notre extension, on va vouloir versionner la traduction avec le reste du code.

Cliquez ensuite sur « Commencer la traduction ».

Vous devriez voir apparaître toutes les chaînes de votre extension, autant celles présentes en PHP que celles écrites dans les fichiers JS.

Effectuez quelques traductions en cliquant sur une ligne et en saisissant une traduction dans le champ en bas de l’interface, puis cliquez sur « Enregistrez ».

Certains textes sont précédés d’une vignette grise, qui donne du contexte. En regardant de plus près, on remarque que ce sont les textes du fichier block.json de nos blocs !

WordPress permet donc de traduire le titre, la description, et même les mots-clés des blocs.

Notez par ailleurs la présence du bouton « Synchroniser » qui nous sera très utile lorsqu’on aura ajouté de nouvelle chaînes à notre extension.

On va maintenant aller jeter un œil du côté du dossier /languages/ de notre site. On peut remarquer que plusieurs fichiers ont été générés automatiquement par Loco :

Parmi les fichiers, voici leur usage :

• .pot : catalogue originel contenant toutes les chaînes à traduire ;
• .po : fichier contenant les traductions dans une langue particulière ;
• .mo : version compilée de la traduction, plus légère, qui sera utilisée par le site ;
• .php : les traductions des chaînes PHP qui seront utilisé dans l’éditeur en JS ;
• .json : contient les traductions des blocs en JS ;
• .po~ : sauvegardes automatiques faites par Loco Translate.

Ça en fait pas mal des fichiers ! Voici quelques explications supplémentaires pour bien comprendre :

Les fichiers .mo seront utilisés en PHP exclusivement. Ils sont compilés et donc plus légers à charger et exécuter. Il faut un module spécial pour les lire, c’est pour ça que ce n’est pas une solution viable pour les traductions JS dans le navigateur.

Les traductions des blocs, que vous avez déclarées dans des fichiers JavaScript, sont placées dans des fichiers JSON qui suivent le format standard JED. Il va y avoir un fichier par bloc, ne vous inquiétez donc pas si vous retrouvez de nombreux fichiers dans le dossier /languages/ au bout d’un moment.

Et on retrouve enfin également des traductions dans un fichier PHP. Ça commence à bien faire ! On a traité PHP et JS déjà, du coup il sert à quoi celui-là ?

En fait, il sert à transmettre des traductions déclarées en PHP vers l’éditeur, par exemple lorsque vous déclarez une nouvelle catégorie de blocs :

Dans cet exemple, cette chaîne déclarée en PHP sera en fait utilisée par l’éditeur Gutenberg, en front et donc en JS :

C’est pour cela que ce fichier existe.

Pas d’inquiétude en tous cas : tout est automatisé. WordPress sait quelles chaînes placer dans quels fichiers, et tout est généré automatiquement par Loco lors de l’enregistrement.

Générer les traductions PHP et JSON

Si vous avez suivi mes conseils et que vous avez utilisé Loco Translate dans l’étape précédente, il n’y a rien à faire de plus dans cette partie, car ce dernier s’est occupé de générer tous les fichiers .mo, .php et même .json automatiquement !

Mais si ce n’est pas le cas, ou que vous souhaitez comprendre ce qu’il se passe sous le capot, voici comment générer les fichiers de traduction soi-même.

Pour cela, reprenez le terminal qui contient WP-CLI (celui de votre éditeur n’y accède pas directement) et exécutez les instructions suivantes :

C’est grâce aux 2 sous-commandes make-php et make-json de la commande i18n de WP-CLI que va opérer la magie !

Leur rôle est de générer les fichiers .php et .json de chaque bloc dans le dossier /languages/.

D’ailleurs, les noms de fichiers JSON suivent le modèle : {texdomain}-{lang}-{md5}.json. WordPress génère automatiquement un md5 du nom du script rattaché au bloc, mais d’après la documentation, vous pourriez avoir un nom plus explicite. Cela dit, ça n’a pas d’intérêt puisque la génération est automatisée ici.

WP-CLI est un outil très puissant d’automatisation pour les agences. Si vous ne connaissez pas encore, consultez la documentation globale. Vous verrez que vous pouvez installer WordPress, des extensions, modifier des options, remplacer des URL… et bien d’autres grâce à lui.

Et si vous voulez en savoir plus sur les commandes i18n, consultes les documentations de make-php et make-json.

Lier les traductions JS aux blocs

Tout est presque prêt pour afficher nos traductions. Mais il reste une dernière étape : on va devoir lier les traductions à nos blocs.

Pour cela, on va ajouter ce code, branché sur le hook init de WordPress, dans le fichier PHP principal de notre extension :

C’est la fonction wp_set_script_translation() qui est la clé ici. Elle permet de lier notre fichier de traduction JSON au script qui pilote le bloc dans l’éditeur. Elle possède 3 paramètres :

• $handle : le nom du script qui exécute le bloc dans l’éditeur ;
• $textdomain : le text domain du bloc, qui est le même que l’extension ;
• $path : le chemin vers le dossier de langues, dans notre cas /languages/.

Le handle est le nom unique donné au script. Problème : on ne le connait pas puisqu’il a été généré automatiquement par WordPress.

Heureusement pour nous, on va pouvoir le récupérer grâce à la fonction generate_block_asset_handle(). Cette fonction a 2 paramètres :

• $block_name : le nom unique du bloc, tel que défini dans le block.json ;
• $field_name : le type de script que l’on vise. Ici editorScript.

Dans cet exemple, j’ai mis le nom du premier bloc que l’on a réalisé : capitainewp/base.

On doit ensuite indiquer editorScript car dans le block.json, il nous arrive de définir plusieurs scripts :

Ce paramètre nous permet donc de cibler le bon handle de script.

Résultat : si on ajoute un var_dump() dans notre PHP, on verra que le handle affiché est : capitainewp-base-editor-script.

Parfait ! Les traductions vont fonctionner… mais pour notre premier bloc uniquement. Maintenant, on ne va pas faire ça à la main pour chaque bloc : on va automatiser.

Une boucle pour tous les blocs de notre extension

Pour lier les traductions à chacun de nos blocs automatiquement, on va écrire une fonction qui va charger toutes les traductions de blocs pour nous ! Voici le code :

On commence par charger le manifeste PHP qui contient la liste de tous les blocs. Pour rappel, ce fichier est généré automatiquement à la compilation de create-blocks.

On va ensuite itérer dans chaque bloc. On commence par vérifier que le bloc a bien son script editorScript, pour éviter de générer des erreurs. En théorie, ce sera toujours le cas puisque c’est le script qui permet d’afficher le bloc dans l’éditeur. Sans lui, pas de bloc, mais restons prudents !

Ensuite, on utilise la fonction wp_set_script_translations() en définissant :

• Le bon handle à partir du nom du bloc via $block_data['name'] ;
• Le textdomain ne change pas d’un bloc à l’autre ;
• Ni le dossier des langues qui sera toujours /languages/.

On peut vérifier dans l’inspecteur lorsqu’on est dans l’interface de Gutenberg :

Ici, on voit que les traductions sont listées juste avant l’appel du script qui exécute le bloc dans l’éditeur. Et il n’y a que les traductions concernant ce bloc en particulier !

Ok, quelle aventure ! Avec tout ça, bonne nouvelle, vos traductions devraient apparaître dans l’éditeur.

Résoudre les problèmes

Ça ne fonctionne pas ? C’est pas de chance hein ! Heureusement, j’ai quelques astuces pour vous aider.

Vider la build et redémarrer le compilateur

Première règle en informatique : dans le doute, reboot ! Si ça ne fonctionne pas :

1. coupez le compilateur avec « CTRL + C » ;
2. Profitez-en pour vous rendre dans le dossier /build/ et videz tout ;
3. Faites de même dans /languages/. Vous pouvez toutefois omettre le .pot et les .po pour éviter d’avoir à refaire toutes les traductions.
4. Redémarrez le compilateur avec la commande npm start.

En général, ça devrait faire ses preuves !

Vérifier le textdomain

Mais si ça ne fonctionne toujours pas, vérifiez que vous avez indiqué le bon text domain de partout :

• Au début du plugin dans les commentaires ;
• Dans la fonction wp_set_script_translations() ;
• Dans les chaînes PHP et JS des blocs…

La moindre petite inconsistance dans votre code pourrait avoir des effets néfastes.

Vérifier les noms des dossiers

Personnellement, j’ai perdu une journée car j’avais mis des espaces dans mes noms de dossiers de blocs dans /src/. Pourtant la règle est toute simple, c’est la même qu’avec les slugs :

• Pas d’accent ;
• Pas de caractère spécial ;
• Pas d’espace.

Même si ça ne pose pas de problème pour le compilateur, et que vos blocs fonctionneront dans l’éditeur, les traductions, elles, ne fonctionneront pas !

On résume le tout

Bravo, vous avez survécu jusque là. Je vous avoue que cette histoire d’internationalisation n’est pas simple du tout. J’ai moi-même passé plusieurs jours, malgré les documentations, à comprendre tous les mystères avant de trouver la bonne approche.

On va donc résumer toutes les étapes :

La première fois uniquement

La toute première fois, il faudra d’abord ajouter le Domain Path dans le fichier PHP principal du plugin, et vérifier le Text Domain :

Ensuite, il faudra ajouter la fonction universelle pour lier les traductions aux scripts des blocs :

Dans vos blocs, importez la fonction __() de traductions de vos chaînes et utilisez-les partout où vous avez un texte statique à traduire :

Une fois vos blocs créés, il faudra lancer quelques commandes grâce à WP-CLI :

Enfin, on traduit les chaînes grâce à Loco Translate qui s’occupe de générer les fichiers JSON et PHP contenant les traductions.

Si vous préférez utiliser PoEdit, il faudra alors lancer quelques dernières commandes :

Avec ça, vos traductions doivent fonctionner !

Les fois suivantes

Lorsque vous ajouterez de nouvelles chaînes dans vos blocs, il faudra mettre à jour le catalogue et les fichiers de traductions. Voici la méthodologie :

Commencez tout d’abord par mettre à jour le catalogue .pot en relançant la commande :

Allez ensuite dans Loco Translate et cliquez sur « Synchroniser », puis traduisez les nouvelles chaînes qui devraient apparaître dans la liste :

Concrètement, Loco translate va lire le catalogue .pot pour récupérer les chaînes manquantes et les ajouter à votre langue en cours dans le .po pour que vous puissiez les traduire.

Enfin, si vous n’utilisez pas Loco translate, générez à la main les fichiers de traduction :

Et voilà, vous avez votre procédure pour mettre à jour vos traductions à tout moment !

Extensions à destination du répértoire WP

Si vous réalisez une extension gratuite ou freemium à destination du répertoire des extensions de WordPress, tout va être beaucoup plus simple.

En effet, WordPress dispose d’une interface, GlotPress, qui permet de traduire en ligne les chaînes PHP et JS de votre extension, permettant ainsi à la communauté de contribuer à la traduction de votre extension.

Voici à quoi ressemble l’interface :

Il faudra par contre demander à des modérateurs de valider vos traductions (même si c’est votre extension) et il faudra bien respecter quelques règles typographiques.

Vous pourrez demander une vérification et une validation de vos traductions sur le Slack WordPress Francophone, dans le channel #traductions.

Du coup, dans ce cas de figure, vous n’aurez pas besoin de définir le Domain Path dans votre fichier PHP principal :

On fait cela car WordPress enverra les traductions de l’extension au site automatiquement et dans le dossier /wp-content/languages/.

Ensuite, il faudra simplifier la fonction de liaison des traductions au bloc :

Plus besoin de charger les traductions pour chaque bloc, WordPress s’occupe de tout. Et normalement, tout est bon !

---

Ce cours était intense, et beaucoup se sont cassé les dents sur cette internationalisation des blocs, à cause de changements de fonctionnements à répétition au fil des années et une documentation pas toujours à jour.

Avec la méthode présentée dans ce cours, vous devriez vous en sortir sans problème !

Dans le prochain cours, on va voir comment déployer notre extension en production mais aussi comment ajouter notre extension sur le répertoire officiel de WordPress.