Les développeurs PHP WordPress savent déjà comment internationaliser leurs extensions et thèmes (rappel : doc. officielle). Pour les modules Gutenberg développés en JavaScript (via le framework React.js), que ce soit des blocks ou des plugins, il faut suivre cette documentation officielle que je vous détaille dans cet article.
Utilisation de la librairie JS de WordPress
Pour internationaliser une chaîne de caractère dans vos fichier React.js, vous devez importer la librairie wp.i18n :
import { __ } from '@wordpress/i18n'
Et non pas de cette manière :
const { __ } = wp.i18n
La raison est qu’à la compilation via webpack, la variable __ va être renommée car elle ne fait pas référence à une librairie externe.
Si ce n’est pas déjà fait, vous devez ajouter cette librairie externe à Webpack :
module.exports = {
externals: {
'@wordpress/i18n': 'wp.i18n'
},
...
}
Utilisez ensuite la fonction importée __('chaîne à traduire', 'textdomain)
Déclaration du textdomain côté PHP
Côté PHP, vous devez indiquer le textdomain (‘myguten’ dans notre exemple) de votre module Gutenberg :
function myguten_set_script_translations() {
wp_set_script_translations('myguten-script', 'myguten', 'FULL_PATH_TO/myguten/lang/');
}
add_action('init', 'myguten_set_script_translations');
Note : le slug 'myguten-script' doit être le même que celui déclaré lors du chargement du javascript de votre module Gutenberg wp_enqueue_script('myguten-script', ...)
Gestion des fichiers de traduction
Maintenant que votre module Gutenberg est bien développé et compilé ($ npm run build (en fonction de votre package.json)), nous allons voir pour gérer les traductions, notamment via WP-CLI (>v.2.2.0) et les commandes relatives à l’internationalisation (voir la doc).
Depuis votre terminal, rendez-vous dans le dossier racine de votre plugin (on préfère développer les modules Gutenberg dans un plugin plutôt que dans un thème)
$ cd ~/my-workspace/myguten/
Lancez la commande suivante :
$ wp i18n make-pot ./ lang/myguten.pot
Cette commande nécessite WP-CLI > v.2.2.0 – elle génère un fichier POT à partir de vos sources (PHP/JS)
Rendez-vous maintenant dans le dossier lang/ puis dupliquez ce fichier en un fichier spécifique à une langue, dans notre exemple notre module est écrit en anglais et nous souhaitons une traduction en français :
$ cd lang/
$ cp myguten.pot myguten-fr_FR.po
Note : on passe d’un fichier .pot à un fichier .po.
Maintenant vous pouvez éditer le fichier myguten-fr_FR.po depuis Poedit (ou autre) et faire vos traductions.
Terminez par la commande suivante :
wp i18n make-json myguten-fr_FR.po --no-purge
Note : Cette commande va générer autant de fichiers {textdomain}-{locale}-{hash-md5}.json que vous avez de fichiers .js comprenant des chaînes traduites.
Si vous rencontrez le message suivant : Success: Created 0 files. voici les possibles raisons :
- les chaînes de caractères de votre fichier .po ne proviennent pas d’un fichier .js
- vous avez indexé uniquement des fichiers .jsx (alors que la commande
wp i18n make-jsoncherche des correspondances dans des fichiers .js)- vous devez compiler votre module Gutenberg en veillant à bien importer la librairie
@wordpress/i18nde la bonne manière
- vous devez compiler votre module Gutenberg en veillant à bien importer la librairie
Mise à jour des traductions
Maintenant, si vous voulez mettre à jour vos traductions lorsque vous modifiez votre module Gutenberg (ajout ou suppression de chaînes de caractères)
Lancez à nouveau la commande suivante depuis la racine de votre plugin :
$ wp i18n make-pot ./ lang/myguten.pot
Elle va mettre à jour votre fichier .pot
Ouvrez votre ancien fichier myguten-fr_FR.po dans Poedit et allez dans le menu Catalogue > update from POT file et selectionnez votre fichier .pot à jour. Ensuite vous n’avez plus qu’à mettre à jour vos traductions.
Terminez par la commande suivante pour mettre à jour les fichiers json :
wp i18n make-json myguten-fr_FR.po --no-purge
Et si vous développez vos modules Gutenberg dans un thème WP
La documentation officielle indique que l’internationalisation Javascript est supportée pour les plugins et les thèmes. Vous n’avez qu’à suivre les même étapes que pour un plugin avec juste une attention sur le nommage des fichiers de langue.
En effet, les thèmes doivent avoir des fichiers de langues MO nommés {locale}.mo (ex. : fr_FR.mo). Cependant il faudra bien veiller à ce que vos fichiers de langue soient nommés de la bonne manière pour générer les fichiers JSON utiles à Gutenberg, à savoir :
{textdomain}-{locale}.po (ex. : myguten-fr_FR.po)
Et donc lorsque vous éditerez vos traductions via Poedit, à l’enregistrement il génèrera automatiquement le fichier MO, vous aurez donc un fichier nommé myguten-fr_FR.mo, il faudra alors le renommer en fr_FR.mo
Pour le reste c’est strictement le même chose.