Rendre les blocs Gutenberg personnalisés traduisibles

Découvrez comment spécifier quels blocs Gutenberg personnalisés que vous avez développés doivent être traduisibles. Vous pouvez le faire en configurant le fichier wpml-config.xml à l’aide de l’extension de test Multilingual Tools.

Ce guide s’adresse aux développeurs qui créent leurs propres blocs personnalisés pour l’éditeur Gutenberg. Si vous n’êtes pas un auteur d’extension, découvrez comment traduire le contenu créé avec l’éditeur Gutenberg.

Premiers pas

Pour commencer, installez et activez :

1. L’extension principale WPML
2. WPML Traduction de chaînes
3. Multilingual Tools

L’extension Multilingual Tools ne doit pas être utilisée sur des sites en direct ou de production. Utilisez-la uniquement pour effectuer des tests.

Générer et tester le code XML pour enregistrer les blocs Gutenberg pour la traduction

1. Créez un nouvel article ou une nouvelle page et ajoutez les blocs Gutenberg que vous souhaitez enregistrer. Assurez-vous d’ajouter du contenu de test dans chaque champ que vous souhaitez rendre traduisible, puis publiez.

Faites défiler vers le bas jusqu’à la section WPML: Gutenberg Blocks et copiez le code XML généré.

2. Accédez à WPML → Paramètres et collez le code XML généré sous l’onglet Configuration XML personnalisée.

Assurez-vous de réviser attentivement le code généré automatiquement. Vous devrez peut-être supprimer certains champs qui ne sont pas censés être traduits, tels que les champs de configuration avec des valeurs spécifiques.

Cliquez sur Enregistrer lorsque vous avez terminé.

3. Retournez à la page que vous avez publiée et apportez de petites modifications, comme la modification du texte d’un bouton ou d’un titre.

Cliquez sur l’icône plus dans la section Langue pour ouvrir l’Éditeur de traduction avancé. Les champs des blocs Gutenberg apparaissent dans l’éditeur et sont disponibles pour la traduction.

Une fois que vous avez enregistré les blocs Gutenberg que vous souhaitez rendre traduisibles, vous pouvez créer votre fichier de configuration de langue. Si vous en avez déjà un, il vous suffit de le modifier pour ajouter votre code XML finalisé.

Exemples d’enregistrement de blocs Gutenberg comme traduisibles

Traduire les images

Supposons que vous ayez une image qui s’affiche à l’aide du code suivant :

<!-- wp:image {"id":3} -->
<figure class="wp-block-image"><img src="http://example.com/wp-content/uploads/2018/07/figure-2.png" alt="Image alt text" class="wp-image-3"/><figcaption>Image Caption</figcaption></figure>
<!-- /wp:image -->

Vous souhaitez traduire les valeurs des attributs figcaption et alt de cette image.

Pour y parvenir, vous devez insérer le code suivant dans wpml-config.xml :

<wpml-config>
  <gutenberg-blocks>
    <gutenberg-block type="core/image" translate="1">
        <xpath>//figure/figcaption</xpath>
        <xpath>//figure/img/@alt</xpath>
    </gutenberg-block>
  </gutenberg-blocks>
</wpml-config>

Veuillez garder à l’esprit que le type est core/image et non wp:image, car il s’agit de la valeur renvoyée par l’API du bloc.

Traduire les liens

Vous pouvez spécifier quels champs de blocs Gutenberg sont des liens. WPML remplacera ensuite tous les liens par leurs traductions si elles sont disponibles.

<wpml-config>
  <gutenberg-blocks>
    <gutenberg-block type="core/some-block" translate="1">
        <xpath type="link">//a/@href</xpath>
    </gutenberg-block>
  </gutenberg-blocks>
</wpml-config>

Traduction des attributs de bloc

Voici un exemple de format pour la définition d’un bloc d’éditeur :

<wpml-config>
  <gutenberg-blocks>
    <gutenberg-block type="my-plugin/my-block" translate="1">
        <xpath label="My Block">//p</xpath>
        <key name="title" />
        <key name="foo">
            <key name="bar1" />
            <key name="bar2" />
        </key>
        <key name="/^[^_]\S+$/" search-method="regex" />
        <key name="something" search-method="wildcards" />
    </gutenberg-block>
  </gutenberg-blocks>
</wpml-config>

Vous pouvez utiliser l’élément key de la même manière qu’il est utilisé avec la configuration Textes d’administration / wp_options. Cela signifie également que vous pouvez avoir des éléments clés à l’intérieur d’éléments clés parents.

Vous pouvez utiliser l’attribut label pour ajouter des étiquettes personnalisées facultatives qui s’affichent dans l’Éditeur de traduction avancé à côté des éléments du bloc. Lorsque l’attribut label fait partie de la balise gutenberg-block, il sera utilisé comme étiquette de secours pour les éléments du bloc qui n’ont pas d’étiquette spécifique définie.

<wpml-config>
    <gutenberg-blocks>
        <gutenberg-block type="my-plugin/mybutton" translate="1" label="My fallback block label">
            <xpath>//span</xpath>
            <xpath>//a@href</xpath>
        </gutenberg-block>
    </gutenberg-blocks>
</wpml-config>

L’attribut search-method peut avoir l’une des deux valeurs suivantes :

• wildcards (par défaut)
• regex.

Vous pouvez utiliser des caractères génériques (wildcards) de la même manière que pour les textes d’administration. Cela signifie qu’un astérisque (*) peut être utilisé dans l’attribut name. Voici un exemple d’un bloc :

<!-- wp:my-plugin/my-block
    {
        "myp": {
            "mypTitle":"The title",
            "mypContent":"The Content",
            "_mypSystem:"Meta attribute to not translate"
        }
    }
/-->

Vous pouvez définir la configuration du bloc à l’aide d’un caractère générique :

<wpml-config>
  <gutenberg-blocks>
    <gutenberg-block type="my-plugin/my-block" translate="1">
      <key name="myp">
          <key name="myp*" />
      </key>
    </gutenberg-block>
  </gutenberg-blocks>
</wpml-config>

Cela vous permettra de traduire « The title » (le titre) et « The content » (le contenu) car ce sont les seuls attributs commençant par myp.

L’attribut regex vous permet d’avoir une expression régulière dans l’attribut name. Cela peut être extrêmement utile pour les configurations complexes. Voici un exemple d’un bloc :

<!-- wp:my-plugin/my-block
    {
        "data": {
            "title":"The title",
            "_title":"e980759463943209f6f1ae09a239e353",
            "content":"The Content",
            "_content":"1502a7b825dfe7b789c63830609f1701"
        }
    }
/-->

Vous pouvez définir la configuration du bloc avec une expression régulière :

<wpml-config>
  <gutenberg-blocks>
    <gutenberg-block type="my-plugin/my-block" translate="1">
        <key name="data">
            <key name="/^[^_]\S+$/" search-method="regex" />
        </key>
    </gutenberg-block>
  </gutenberg-blocks>
</wpml-config>

Cela vous permettra de traduire « The title » (le titre) et « The content » (le contenu) car ce sont les seuls attributs ne commençant pas par un trait de soulignement (_).

Certaines extensions de blocs enregistrent les données dans une chaîne JSON codée en URL à l’intérieur de l’attribut d’un bloc. L’attribut encoding vous permet de décoder la chaîne et d’enregistrer ses sous-clés pour la traduction.

Par exemple, l’extension LazyBlocks stocke le contenu du champ répéteur dans une chaîne JSON codée :

<!-- wp:lazyblock/testwpml {"name":"%5B%7B%22firstname%22:%22Shekhare%22,%22lastname%22:%22Bhandari%22%7D,%7B%22firstname%22:%22Compatibility%22,%22lastname%22:%22Escalation%22%7D%5D","blockId":"Z169b0O","blockUniqueClass":"lazyblock-testwpml-Z169b0O"} /-->

Vous pouvez enregistrer les sous-clés firstname et lastname à l’aide de la configuration XML suivante :

<wpml-config>
  <gutenberg-blocks>
    <gutenberg-block type="lazyblock/team" translate="1">
      <key name="name" encoding="json">
        <key name="*">
          <key name="firstname" />
          <key name="lastname" />
        </key>
      </key>
    </gutenberg-block>
  </gutenberg-blocks>
</wpml-config>

Traduire les liens d’attributs de bloc

Pour permettre à WPML de traduire automatiquement les URL, vous pouvez déclarer les attributs de blocs Gutenberg comme des liens.

Voici un exemple d’un bloc Gutenberg personnalisé avec un lien cliquable :

<!-- wp:foo/link {"label":"Click here!","url":"https://example.com/some-page/"} /-->

Pour rendre les attributs label et url traduisibles, ajoutez ce qui suit à votre fichier wpml-config.xml :

<gutenberg-block type="foo/link" translate="1">
	<key name="label" />
	<key name="url" type="link" />
</gutenberg-block>

Dans cette configuration, spécifier type="link" pour l’attribut url permet à WPML de traduire automatiquement l’URL.

Espace de noms de bloc

Vous pouvez avoir une configuration globale pour l’espace de noms du bloc.

Le nom du bloc n’est plus une partie requise de la définition.

Si la configuration du bloc est la même pour tous les blocs d’un espace de noms, vous pouvez l’écrire comme ceci :

<wpml-config>
  <gutenberg-blocks>
    <gutenberg-block type="my-plugin" translate="1">
        <key name="data">
            <key name="/^[^_]\S+$/" search-method="regex" />
        </key>
    </gutenberg-block>
  </gutenberg-blocks>
</wpml-config>

Convertir automatiquement les ID dans les blocs

La conversion d’ID est polyvalente et essaie de s’adapter à la plupart des formats d’ID possibles (ID unique, liste d’ID, tableau sérialisé, tableau codé en JSON).

Considérez le bloc suivant :

<!-- wp:foo/form {"ids":[27,28]} -->
<div class="wp-block-foo-form-wrap">
  <form class="foo-form" action="" method="post">
    <input type="hidden" name="foo_form_post_ids" value="27,28" />
    <input type="submit" />
  </form>
</div>
<!-- /wp:foo/form -->

Vous pouvez déclarer, en tant qu’ID de publication, les ID d’attributs de bloc et la valeur d’attribut de balise HTML foo_form_post_ids comme ci-dessous :

<gutenberg-block type="foo/form" translate="0">
  <key name="ids">
      <key name="*" type="post-ids" sub-type="post" />
  </key>
  <xpath type="post-ids" sub-type="post">//*[@name="foo_form_post_ids"]/@value</xpath>
</gutenberg-block>

Le bloc sera converti avec la priorité la plus élevée sur le filtre render_block_data comme ci-dessous :

<!-- wp:foo/form {"ids":[42,43]} -->
<div class="wp-block-foo-form-wrap">
    <form class="foo-form" action="" method="post">
        <input type="hidden" name="foo_form_post_ids" value="42,43" />
        <input type="submit" />
    </form>
</div>
<!-- /wp:foo/form -→

Vous pouvez utiliser les attributs de configuration suivants :

• type – peut être post-ids ou taxonomy-ids
• sub-type (facultatif) : peut être l’entité spécifique du type si elle est déjà connue. Par exemple, product pour le type de publication personnalisé Product. Si elle n’est pas définie, l’entité spécifique sera devinée.

Ressources supplémentaires

Pour en savoir plus sur le fichier wpml-config.xml, consultez le guide Fichiers de configuration de langue.

Pour personnaliser d’autres éléments à l’aide du fichier wpml-config.xml, consultez nos guides supplémentaires :

• Traduire des shortcodes personnalisés avec WPML
• Enregistrer le contenu du constructeur de pages pour la traduction
• Enregistrer les widgets personnalisés du constructeur de pages pour la traduction
• Définir les options de traduction pour les champs personnalisés à l’aide du fichier de configuration WPML
• Enregistrer les termes, types et taxonomies personnalisés comme traduisibles
• Traduire les textes que le thème et les extensions enregistrent dans wp_options
• Personnaliser le sélecteur de langue WPML à l’aide du fichier de configuration WPML