Créer un bloc Gutenberg personnalisé – Partie 8 : Prise en charge de la traduction

Dans cette partie, nous allons nous concentrer sur la façon de traduire les textes et les valeurs dans notre bloc Gutenberg personnalisé. Nous utilisons WP-CLI pour générer les fichiers nécessaires afin que Gutenberg puisse charger nos traductions lors du changement de langue WordPress.

Avant de continuer, vous devez avoir installé WP CLI (interface de ligne de commande pour WordPress). Si vous ne l’avez pas, suivez simplement le guide sur WordPress Handbook for CLI.

Pour expliquer en bref comment traduire pour les scripts Javascript (Gutenberg): WordPress nécessite .modes fichiers pour la traduction des fichiers PHP, mais pour Javascript, WordPress nécessite un .jsonfichier. Chaque fichier Javascript nécessite un fichier JSON pour la traduction. Le JSON doit être d’un format spécifique (WP CLI le générera pour nous) avec nos chaînes traduites. Nous avons besoin d’un fichier JSON par langue dans laquelle nous souhaitons traduire.

Donc, ce que nous devons faire, c’est d’abord ajouter les fonctions gettext (__(), _e()etc.) dans nos fichiers Javascript et générer un fichier PO comme d’habitude pour notre thème ou plugin. Parce que nous avons enveloppé les textes dans nos fichiers de script avec par exemple __(), le fichier PO devrait pouvoir les inclure. Ensuite, nous faisons la traduction comme d’habitude dans notre fichier PO. Et enfin, nous utilisons WP CLI pour extraire les chaînes nécessaires du fichier PO et générer des fichiers JSON pour tous nos fichiers Javascript.

Gardez à l’esprit que les fichiers/fichiers de votre thème ou plugin .pon’auront .mojamais d’effet sur vos fichiers Javascript, même s’ils contiennent des chaînes traduites à partir de nos fichiers Javascript.

Implémentation de la traduction en Javascript

La première étape consiste à envelopper tous les textes dans notre fichier Javascript dans les fonctions de traduction. Si vous avez géré la traduction de WordPress en PHP, vous connaissez probablement très bien les fonctions __(), _e(), esc_html__()etc. WordPress a un package wp.i18nqui contient ces fonctions, qui fonctionnent exactement comme en PHP.

Comme avec PHP, vous devez fournir un domaine textdomain (nom/handle). Cela peut être ce que vous voulez, mais soyez bref car vous devrez probablement le taper très souvent. Pour mon thème, j’ai configuré mon textdomain avec le domaine awhitepixel. Donc dans PHP je vais faire __('My string', 'awhitepixel')pour traduire les chaînes, et ce sera exactement la même chose dans les fichiers Javascript.

Commençons à éditer notre fichier Javascript. Nous devons d’abord déstructurer la fonction __et _edu wp.i18npackage. En raison de la nature de React, vous utiliserez probablement la __fonction principalement ou peut-être uniquement.

const { __, _e } = wp.i18n;

Et puis il s’agit de retrouver tous nos textes codés en dur dans le fichier Javascript et de les mettre à jour. Gardez à l’esprit que les fonctions __et _enécessitent un contexte Javascript. Cela signifie que lorsque nous tapons des chaînes comme par exemple des valeurs de propriété d’objet, nous utilisons __()tout de suite, mais comme valeurs pour, par exemple, des accessoires, nous devons tout envelopper à l’intérieur { }pour signifier qu’il s’agit de code Javascript.

Par exemple, notre registerBlockTypesupport pour la traduction ressemblera à :

registerBlockType('awp/firstblock', {
    title: __('My first block', 'awhitepixel'), 
    category: 'common',
    icon: 'smiley',
    description: __('Learning in progress', 'awhitepixel'),
    keywords: [__('example', 'awhitepixel'), __('test', 'awhitepixel')],
    attributes: {
        ...

Et en ce qui concerne les accessoires, c’est-à-dire dans InspectorControls:

Enveloppez tous les textes dont vous souhaitez prendre en charge la traduction dans __()et _e(). Si vous avez suivi ce tutoriel étape par étape, vous ne devriez pas avoir de cas où vous devez utiliser _e(). Lorsque vous avez terminé, recompilez le Javascript et nous nous éloignerons de Javascript.

Configuration des fichiers po et/ou pot

Cette étape varie un peu en fonction de ce que vous avez déjà fait et configuré pour votre thème ou plugin. Vous écrivez peut-être vos scripts Gutenberg dans un nouveau plugin vide qui n’a pas été configuré pour la traduction PHP, ou dans un thème qui a déjà un domaine de texte enregistré. Vous pouvez avoir des fichiers PO (et MO) prêts, ou vous pouvez n’avoir qu’un fichier POT. Je ferai de mon mieux pour couvrir toutes les bases.

Mon thème ou plugin a déjà un fichier po(t)

Si vous avez déjà un fichier PO ou POT dans votre projet, vous avez probablement aussi la fonction PHP load_theme_textdomain(), load_child_theme_textdomain()ou load_plugin_textdomain()quelque part dans votre code. Veuillez vous assurer que le domaine enregistré est le même que celui que vous avez utilisé dans vos fichiers Javascript.

Tout ce que vous avez à faire est de charger le fichier PO pour la langue que vous souhaitez traduire (ou d’en générer un à partir du fichier POT) dans par exemple PoEdit. Cliquez sur "Mettre à jour à partir du code" (ou similaire dans d’autres programmes) afin que le programme puisse analyser tous les fichiers du projet (y compris nos fichiers Javascript récemment mis à jour) et mettre à jour le pool de chaînes à traduire. Les chaînes de notre fichier Javascript devraient apparaître. Ensuite il vous suffit de les traduire normalement et de les enregistrer.

PS : Si vous ne parvenez pas à cliquer sur "Mettre à jour à partir du code" ou à réanalyser les fichiers, le fichier PO n’a probablement pas été configuré correctement. Recherchez des conseils dans la section suivante.

Je n’ai pas de fichiers de traduction

Si votre thème ou projet n’a pas été configuré avec la traduction, vous devez soit générer un fichier POT à l’aide de WP-CLI, soit créer manuellement un fichier PO.

J’ai un guide complet sur la façon de créer un fichier PO dans mon didacticiel thématique pour débutants – partie 8. Le message décrit comment vous pouvez créer le fichier et le configurer correctement pour rechercher vos fichiers de thème, ainsi que les mots-clés à rechercher (__, _e, etc.).

Si vous souhaitez plutôt créer un fichier POT, vous pouvez utiliser la commande wp i18n make-pot dans WP-CLI, puis créer un fichier PO à partir de celui-ci en utilisant par exemple PoEdit. Gardez à l’esprit que vous devrez régénérer le fichier POT (puis le fichier PO) chaque fois que vous mettez à jour des chaînes dans votre code.

Résultat final

Ce dont vous avez besoin en fin de compte, c’est d’un fichier PO qui a trouvé vos chaînes Javascript là où elles ont été traduites. Je vous recommande de placer vos fichiers de traduction dans un dossier séparé de votre thème ou plugin. Lorsque nous commençons à générer des fichiers JSON, nous nous retrouvons avec un certain nombre de fichiers à traduire et ce sera bien de les garder tous ensemble dans leur propre dossier.

Comme point de référence, je place tous les fichiers de traduction dans mon fichier theme/assets/lang/. J’ai ajouté une traduction norvégienne pour mon thème, nommée nb_NO.po, qui contient les chaînes traduites de notre fichier Javascript de bloc personnalisé.

Génération de fichiers JSON à partir du fichier po

L’étape suivante consiste à utiliser WP-CLI pour générer des fichiers JSON à partir de notre fichier po. Pour ce faire, nous utilisons la commande wp i18n make-json.

Sachez que par défaut, cette commande extraira les chaînes traduites de votre fichier PO pour les utiliser dans la génération du fichier JSON. Cela peut être fastidieux au milieu du développement de votre thème ou plugin. Parce que lorsque vous ajoutez de nouvelles chaînes ou que vous les ajustez, vous devrez analyser à nouveau les fichiers et traduire à nouveau toutes les chaînes (et encore et encore). Heureusement, il y a un drapeau à la commande pour éviter cela.

Commençons! Dans votre terminal, accédez au répertoire de votre langue pour votre projet. Exécutez la commande suivante et reportez-vous à votre fichier po (comme mentionné, j’ai un nb_NO.pofichier prêt).

wp i18n make-json nb_NO.po --no-purge

Si vous n’avez aucun problème à supprimer les chaînes traduites de votre fichier PO (par exemple si vous faites votre version finale), vous pouvez ignorer le --no-purgedrapeau.

Le terminal doit indiquer "Succès" et indiquer le nombre de fichiers JSON créés. Si vous voyez qu’il a généré deux fichiers JSON, c’est parce qu’il a lu à la fois notre fichier Javascript de code source et le fichier de construction, et en a généré un pour chacun. Si vous avez plus de fichiers Javascript dans votre projet, vous vous retrouverez avec encore plus de fichiers JSON.

Au moment de la rédaction de ce document (WordPress v 5.3.2 et WP-CLI version 2.4.0), les fichiers JSON sont générés avec le code de langue et un hachage – une chaîne cryptée comme noms de fichiers. Nous devons trouver le bon et le renommer.

Renommer le fichier JSON et le charger en PHP

Votre dossier de langue ressemble probablement à ceci :

N’oubliez pas que la commande a généré un fichier JSON par fichier Javascript – et parce que nous avons en fait deux fichiers pour notre bloc personnalisé (la source et la construction), elle a généré deux fichiers. Si votre code Javascript est divisé en plusieurs fichiers, chacun recevra deux de ses propres fichiers JSON.

Si vous êtes assis avec seulement deux fichiers JSON (car aucun autre fichier Javascript n’a été trouvé), vous pouvez supprimer l’un d’entre eux maintenant. Si vous en avez plus de deux, vous devez ouvrir les fichiers JSON et voir à quel fichier ils sont destinés. Les fichiers JSON contiennent une propriété " source" qui vous indique à quel fichier Javascript ce fichier JSON est destiné. Utilisez-le pour déterminer quel fichier JSON conserver. Je recommande de trouver le fichier de construction final (par opposition aux fichiers de développement) car il doit contenir toutes les chaînes de tous les fichiers.

Lorsque vous avez trouvé le bon, nous devons le renommer. Nous devons le renommer pour suivre ce modèle :

[textdomain]-[language code]-[script handle].json

Utilisez le domaine de texte que vous avez utilisé partout (par exemple __('My string', 'awhitepixel')), ajoutez un tiret et le code de langue. Ensuite, fournissez un tiret et le descripteur de script que vous avez utilisé pour enregistrer votre fichier Gutenberg Javascript (wp_register_script()). À titre de référence, mon domaine de texte est awhitepixel, mon code de langue est nb_NO, et mon descripteur de script pour le script Gutenberg est awp-myfirstblock-js. Donc je renomme le fichier JSON en :

awhitepixel-nb_NO-awp-myfirstblock-js.json

Dites à WordPress de charger notre JSON

Il ne reste plus qu’à passer à l’étape finale : dire à WordPress de charger notre fichier JSON. Nous devons utiliser la fonction [wp_set_script_translations](https://developer.wordpress.org/reference/functions/wp_set_script_translations/)(). Il s’agit d’une toute nouvelle fonction WordPress, je vous recommande donc de l’envelopper dans un fichier function_exists(). Il accepte trois paramètres ; le descripteur de script pour notre bloc, le textdomain et le chemin vers notre dossier de traduction (note: le chemin, pas l’URL).

Dans notre fonction accrochée à init, où nous avons enregistré notre script de bloc et appelé, register_block_typenous pouvons également appeler cette nouvelle fonction pour charger notre fichier de traduction JSON. PS : Gardez à l’esprit que le crochet enqueue_block_assetsne fonctionnera pas pour enregistrer des traductions.

add_action('init', function() {
    wp_register_script('awp-myfirstblock-js', ....);
    register_block_type('awp/firstblock', ....
 
    if (function_exists('wp_set_script_translations')) {
        wp_set_script_translations('awp-myfirstblock-js', 'awhitepixel', get_template_directory(). '/assets/lang');
    }
});

Et c’est tout! Votre bloc devrait maintenant être traduit. Basculez la langue WordPress vers la langue dans laquelle vous avez traduit et vérifiez-la par vous-même. Lorsque je change ma langue WordPress en norvégien et que j’ajoute mon bloc, le nom et tout ce qu’il contient sont traduits :