Formation « Créer des blocs avec Gutenberg »

i18n : internationaliser le Javascript de Gutenberg

Lecture : 6 minutes • 8

Dans ce cours on va voir comment gérer l’internationalisation de nos chaines de texte en PHP et en JS afin que nos blocs puissent être traduits dans toutes les langues.

Afin de rendre notre extension traduisible dans toutes les langues possibles, il y a quelques manipulations supplémentaires à faire, comme détecter les chaines, générer le catalogue de traduction et enfin traduire les chaines.

On va également voir que la manipulation n’est pas identique selon que vous souhaitez faire de votre extension : la publier sur wordpress.org, ou alors la garder privée ou la rendre premium.

Déclarer le textdomain et les traductions en PHP

Conseil

Normalement, si vous avez bien utilisé create-block, vous n’avez rien à faire dans cette première partie : tout est déjà prêt pour la traduction.

Dans chaque projet WordPress, que ce soit un thème ou une extension, il faut déclarer un Text Domain : C’est l’identifiant unique de nos chaines de traduction.

Dans notre cas, il est déclaré dans les données du plugin, au début du fichier PHP :

PHP
capitaine-gut-bases.php

On peut remarquer que le textdomain correspond au nom de dossier de notre extension, dans mon cas : capitainewp-gut-bases.

Le saviez-vous ?

Le text domain permet de distinguer les traductions du coeur, des extensions et thèmes. Cela vous permet d’éviter les conflits avec une chaine qui serait la même dans une autre extension, mais dont la traduction serait différente.

Comme notre extension est faite en majorité à base de Javascript, il va falloir envoyer ces traductions de PHP à JS, et pour cela WordPress possède une fonction dédiée à cette tâche. C’est wp_set_script_translations().

On peut la voir en action juste après la déclaration de notre script JS principal destiné à l’éditeur :

PHP
capitaine-gut-bases.php

Du coup, tout est paré côté PHP.

Utiliser les fonctions d’internationalisation en JS

Côté Javascript maintenant, on va avoir accès à la fonction __() qui va nous permettre de rendre nos chaines traduisibles. Et si vous avez suivi toute la formation, vous avez vu qu’on a déjà préparé toutes nos chaines en vue d’une traduction.

JSX

Le premier paramètre est notre chaine, en anglais, et le second est le Text Domain.

Pour que ça fonctionne, il faudra bien penser à charger la librairie @wordpress/i18n au début de chaque fichier JS qui utilisera la fonction __() :

JSX

Pour en savoir plus sur l’internationalisation des chaines dans WordPress, consultez mon cours sur l’i18n. Et pour en savoir plus sur l’internationalisation d’extensions, consultez la documentation officielle en ligne.

Le saviez-vous ?

i18n veut dire internationalization : il y a 18 lettres entre le premier i et le dernier n.

Tout est prêt, on va maintenant pouvoir passer à la suite, et il existe 2 cas :

  • Si vous publiez votre extension gratuitement sur wordpress.org, alors vous allez bénéficier d’une interface de traduction en ligne ;
  • Mais dans le cas d’une extension premium, alors il faudra générer vos fichiers de traduction vous-même.

On va voir les 2 cas !

Si vous publiez votre extension sur le répertoire officiel

Si vous publiez votre extension sur le répertoire officiel de WordPress, vous n’avez plus grand chose à faire désormais.

Une fois en ligne, votre extension sera analysée par wordpress.org, qui détectera automatiquement les chaines traduisibles.

De là, vous ou tout autre contributeur pourra proposer ses propres traductions.

La page officielle d'une extension wordpress.org
Le bandeau vert vous invite à traduire l’extension

Lorsque vous êtes sur la page officielle de votre extension, un bandeau vert vous invite à améliorer la traduction. Cliquez dessus.

Vous arriverez ensuite sur le tableau des traductions, vous pourrez y voir la progression des traductions dans chaque langue :

L'interface pour choisir la langue à traduire dans votre extension.
En vert, les traductions les plus avancées

Cliquez à l’intersection de Français et Stable pour lister les chaines à traduire. Enfin, vous arriverez sur le tableau des traductions :

L'interface de traduction des extensions sur wordpress.org
La liste des chaines à traduire

Pour faire valider vos traductions, il faudra faire un message à l’équipe de traduction francophone sur le Slack WordPress FR dans le channel #traductions.

Et ce, même si vous êtes l’auteur de votre extension. À terme, vous pourrez demander d’être PTE (Project Translation Editor)  et vous pourrez valider vous-même les chaines.

Il y aura quelques règles à respecter, comme se baser sur le glossaire WordPress, utiliser les apostrophes françaises : au lieu de ' et utiliser des espaces insécables.

Conseil

Si votre projet prend de l’ampleur, d’autres contributeurs viendront vous aider à collaborer sur les traductions !

Et si vous faites une extension premium ou privée

Dans ce cas, vous ne pourrez pas profiter de l’interface de wordpress.org. On va donc générer nous-même nos fichiers de traduction et les traduire via un outil. Et on va commencer par générer un premier fichier qui va lister toutes les chaines à traduire.

Indiquer qu’on va charger un fichier de traduction dans l’extension

La première chose à faire, c’est de modifier très légèrement notre code PHP pour indiquer que la traduction ne sera pas téléchargée depuis wordpress.org, mais devra être chargée depuis notre extension.

C’est dans la fonction wp_set_translation_script() qu’on va ajouter un troisième paramètre :

PHP
capitaine-gut-bases.php

Générer le catalogue .POT de traduction avec WP-CLI

On va devoir maintenant générer le catalogue de traduction, sous la forme d’un fichier .pot que l’on stockera dans le dossier languages.

Ce fichier servira de base pour créer des traductions dans toutes les langues, via des fichier .po et .mo que l’on traduira à l’aide de Loco Translate ou POedit.

Pour créer notre catalogue, on va utiliser WP-CLI qui permet de faire des actions avec WordPress en ligne de commande.

Installer WP-CLI

Si vous n’avez pas WP-CLI sur votre système, voici comment l’installer :

Installer WP-CLI

Si vous voulez en savoir plus, voici le lien vers le Handbook WP-CLI officiel.

Générer le catalogue .pot

Maintenant, à partir du dossier de notre plugin, on va créer un sous-dossier languages, et générer le catalogue à l’intérieur via ces commandes :

Shell

Pensez-bien à donner le même nom de fichier que le Text Domain, et qui devrait être du coup le même que le nom du dossier de l’extension.

Si tout s’est bien passé, votre terminal vous indique que la manoeuvre a bien fonctionné, et devriez avoir un nouveau dossier languages qui contient votre fichier .pot.

Le terminal indique que le fichier a bien été généré.
Notre fichier .pot a bien été généré et contient les chaines à traduire

En ouvrant le fichier, vous remarquerez que toutes les chaines de notre extension ont bien été détectées et listées.

Attention

Il faudra relancer la commande make-pot lorsque vous ajouterez de nouvelles chaines de texte dans votre extension, afin qu’elles soient prises en compte dans votre catalogue.

C’est donc tout bon, on va pouvoir commencer la traduction.

Lancer une traduction via Loco Translate

Il existe plusieurs solutions pour lancer des traductions, et les développeurs utilisent en général le logiciel POEdit.

Mais vous pouvez également utiliser une extension directement dans votre site qui s’appelle Loco Translate et qui fait le travail tout aussi bien :

Loco Translate

Loco Translate

Traduisez directement des thèmes et extensions WordPress depuis votre navigateur.

Tim Whitlock

Une fois installée et activée, allez dans Loco Translate > Extension > Votre extension.

On arrivera sur une interface qui ne liste aucune traduction pour le moment. C’est normal. Cliquez sur Nouvelle langue et choisissez Français.

Laissez l’emplacement auteur : on veut enregistrer la traduction dans le dossier de notre extension, afin de la versionner par la suite.

L'interface de traduction des chaines de l'extension Loco Translate
L’interface de traduction de Loco

Maintenant, il faut traduire chaque chaine. Pensez à cliquer sur Enregistrer une fois que c’est fait.

Vous verrez alors un fichier .po et un .mo en FR dans votre dossier languages.

le dossier languages contient les fichiers de traduction en français générés par Loco Translate
Les fichiers ont bien été générés

Vous apercevrez aussi des fichiers json qui ont été générés par la commande make-pot.

Le saviez-vous ?

Le fichier MO est la version binaire compilée du fichier PO. C’est le MO qui est utilisé par PHP car plus rapide à exécuter pour le script.

Par contre, on utilise le fichier PO via Loco pour éditer les traductions. Ce dernier s’occupe ensuite de la compilation.

Générer les fichiers JSON

Et enfin, il va falloir générer les fichiers JSON correspondants. Pour cela, il suffit de lancer une dernière commande depuis le terminal :

Shell

Il faudra le faire pour chaque fichier .po dans chaque langue.

Maintenant, essayez d’utiliser l’un de vos blocs afin de contrôler que les chaines apparaissent désormais bien en français.

Les textes apparaissent désormais en français dans vos blocs
Vos blocs sont désormais en français !

Et voilà c’est parfait !


Voilà pour l’internationalisation de Gutenberg. Votre extension est désormais prête pour être traduite dans tous les langues !

8

Questions, réponses et commentaires

  1. David Dufour

    Le 30 avril 2021

    Voici mon code avec la modification que tu as parlé:

    function register_scripts_block_editor_assets(){
    if ( ! function_exists( ‘register_block_type’ ) ) {
    // Gutenberg is not active.
    return;
    }

    $dir = CHACHA_FOLDER . ‘/assets/js/blocks/’;
    $blocks = array_filter( glob( $dir.’*’ ), ‘is_file’ );
    foreach( $blocks as $block ){
    $type = str_replace( $dir,  », $block );
    $type = str_replace( ‘.js’,  », $type );
    wp_enqueue_script(
    $type,
    plugins_url( ‘/assets/js/blocks/’.$type.’.js’, CHACHA_FILE ),
    [ ‘wp-edit-post’, ‘wp-i18n’ ],
    CHACHA_VERSION
    );
    }

    // Add language json file to script
    wp_set_script_translations( ‘column’, ‘chacha-gutenberg’, plugin_dir_path( __FILE__ ) . ‘lang’ );
    }

    1. Maxime BJ

      Le 30 avril 2021

      En fait, tu ne dois pas toucher le reste du code (généré par create-block) en dehors du paramètre que j’ajoute dans wp_set_script_translation. Le reste est déjà bon et fonctionnel de base.

      1. David Dufour

        Le 30 avril 2021

        Tu as un moyen qu’on puisse se parler plus efficacement?
        Btw, j’apprécie énormément ton aide. Nous sommes nouveau sur Gutenberg et nous aimons beaucoup le concept.

        1. Maxime BJ

          Le 30 avril 2021

          J’ai fait un channel #capitainewp sur le slack WordPress FR si jamais. Je ne suis pas hyper dispo en ce moment mais ce sera plus simple pour partager ton code. Essaie de voir si la traduction fonctionne avec mon plugin de ressources (dispo en début de formation) car j’avais fait la bonne config et tu devrais pouvoir comparer pour voir où ça plante.

  2. David Dufour

    Le 29 avril 2021

    J’ai fait tout ça. Ceci a généré un fichier json par bloc (J’en ai 2) et j’ajoute wp_set_script_translations pour chaque bloc. Cependant, ma traduction ne fonctionne pas plus. Une idée?

    1. Maxime BJ

      Le 29 avril 2021

      Normalement, tu ne devrais avoir qu’un seul wp_set_script_translations dans ton extension. Vérifie que tu as bien un fichier dans /build/index.asset.php

      1. David Dufour

        Le 30 avril 2021

        Même si j’ai plusieurs fichiers de blocs. La commande qui génère des fichiers json pour les langues a créé 2 fichiers. Et on doit passer le $handle
        (string) (Required) Script handle the textdomain will be attached to.

        1. Maxime BJ

          Le 30 avril 2021

          Oui car au final il n’y a qu’un seul script compilé à la fin pour l’ensemble de tes blocs, donc un seul appel aux traductions. Ensuite, il ira chercher le bon json en fonction du bon bloc et de la langue.

Laisser un commentaire