Hacer traducibles los bloques personalizados de Gutenberg

Descubra cómo especificar qué bloques de Gutenberg personalizados que ha desarrollado deben ser traducibles. Puede hacerlo configurando el archivo wpml-config.xml con la ayuda del plugin de prueba Herramientas multilingües.

Esta guía es para desarrolladores que crean sus propios bloques personalizados para Gutenberg. Si no es autor de plugins, consulte cómo traducir el contenido creado con el editor Gutenberg.

Primeros pasos

Para empezar, instale y active:

El plugin del núcleo de WPML
WPML Traducción de cadenas
Herramientas multilingües

El plugin Herramientas multilingües no debe usarse en sitios en vivo o de producción. Úselo solo para pruebas.

Generar y probar el código XML para registrar bloques de Gutenberg para su traducción

1. Cree una nueva entrada o página y añada los bloques de Gutenberg que quiera registrar. Asegúrese de añadir contenido de prueba en cada campo que quiera hacer traducible y, a continuación, publíquela.

Desplácese hacia abajo hasta la sección WPML: Gutenberg Blocks y copie el código XML generado.

Copiar el código XML pregenerado para revisarlo

Importante: El código XML generado automáticamente no debe usarse tal cual. Debe probarlo y editarlo antes de ponerlo a disposición de sus usuarios. Consulte el siguiente paso.

2. Vaya a WPML → Configuración y pegue el XML generado en la pestaña Configuración XML personalizada.

Asegúrese de revisar minuciosamente el código generado automáticamente. Es posible que tenga que eliminar algunos campos que no están destinados a ser traducidos, como los campos de configuración con valores específicos.

Haga clic en Guardar cuando esté listo.

3. Vuelva a la página que publicó y haga pequeñas actualizaciones, como editar el texto de un botón o un encabezado.

Haga clic en el icono más en la sección Idioma para abrir el Editor de traducción avanzado. Los campos de los bloques de Gutenberg aparecen en el editor y están disponibles para su traducción.

Comprobar los bloques de Gutenberg traducibles en el Editor de traducción avanzado de WPML

Una vez que haya registrado los bloques de Gutenberg que quiere hacer traducibles, puede crear su archivo de configuración de idiomas. Si ya tiene uno, simplemente edítelo para añadir su código XML finalizado.

Ejemplos de registro de bloques de Gutenberg como traducibles

Traducir imágenes

Supongamos que tiene una imagen que se muestra usando el siguiente código:

Ejemplo de imagen que necesita ser traducida

<!-- 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 -->

Quiere traducir los valores de los atributos figcaption y alt de esta imagen.

Para lograrlo, debe insertar el siguiente código en wpml-config.xml:

Ejemplo de configuración para la traducción de un bloque de Gutenberg

<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>

Tenga en cuenta que el type es core/image y no wp:image, ya que este es el valor devuelto por la API del bloque.

Traducir enlaces

Puede especificar qué campos del bloque de Gutenberg son enlaces. A continuación, WPML reemplazará cualquier enlace con sus traducciones si están disponibles.

Traducción de enlaces en bloques de Gutenberg

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

Traducción de atributos de bloque

Este es un ejemplo de un formato para la definición de un bloque del editor:

Formato para la definición de un bloque del editor

<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>

Puede usar el elemento key de la misma manera que se usa con la configuración de textos de administración / wp_options. Esto también significa que puede tener elementos clave dentro de elementos clave principales.

Puede usar el atributo label para añadir etiquetas personalizadas opcionales que se muestran en el Editor de traducción avanzado junto a los elementos del bloque. Cuando el atributo label es parte de la etiqueta gutenberg-block, se usará como etiqueta de respaldo para los elementos del bloque que no tengan una etiqueta específica definida.

Ejemplo de una etiqueta de respaldo

<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>

El atributo search-method puede tener uno de dos valores:

wildcards (predeterminado)
regex.

Puede usar comodines (wildcards) de la misma manera que para los textos de administración. Esto significa que se puede usar un asterisco (*) en el atributo name. Este es un ejemplo de un bloque:

Ejemplo de un bloque

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

Puede establecer la definición del bloque usando un comodín:

Definición de bloque usando un comodín

<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>

Esto le permitirá traducir “The title” y “The content”, ya que estos son los únicos atributos que comienzan con myp.

La opción regex le permite tener una expresión regular en el atributo name. Esto puede ser extremadamente útil para configuraciones complejas. Este es un ejemplo de un bloque:

Configuración compleja: ejemplo

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

Puede establecer la definición del bloque con una expresión regular:

Definición de bloque con una expresión regular

<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>

Esto le permitirá traducir “The title” y “The content”, ya que estos son los únicos atributos que no comienzan con un guion bajo (_).

Algunos plugins de bloques guardan datos en una cadena JSON codificada como URL dentro del atributo de un bloque. El atributo encoding le permite decodificar la cadena y registrar sus subclaves para su traducción.

Por ejemplo, el plugin LazyBlocks almacena el contenido del campo repetidor en una cadena JSON codificada:

Ejemplo de bloque de LazyBlocks con cadena JSON codificada como URL

<!-- 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"} /-->

Puede registrar las subclaves firstname y lastname usando la siguiente configuración XML:

Ejemplo de registro de cadenas JSON codificadas como URL dentro del atributo de un bloque

<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>

Traducir enlaces de atributos de bloque

Para permitir que WPML traduzca las URL automáticamente, puede declarar los atributos del bloque de Gutenberg como enlaces.

Este es un ejemplo de un bloque de Gutenberg personalizado con un enlace en el que se puede hacer clic:

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

Para hacer que los atributos label y url sean traducibles, añada lo siguiente a su archivo wpml-config.xml:

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

En esta configuración, especificar type="link" para el atributo url permite que WPML traduzca la URL automáticamente.

Espacio de nombres del bloque

Puede tener una configuración global para el espacio de nombres del bloque.

El nombre del bloque ya no es una parte obligatoria de la definición.

Si la configuración del bloque es la misma para todos los bloques en un espacio de nombres, puede escribirla así:

Bloques en un espacio de nombres

<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 ID automáticamente en bloques

La conversión de ID es versátil e intenta adaptarse a la mayoría de los formatos posibles de ID (ID único, lista de ID, matriz serializada, matriz codificada en JSON).

Considere el siguiente bloque:

Convertir ID automáticamente en bloques: ejemplo de bloque

<!-- 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 -->

Puede declarar, como ID de entradas, los ID de los atributos del bloque y el valor del atributo de la etiqueta HTML foo_form_post_ids de la siguiente manera:

ID de atributos del bloque y valor del atributo de la etiqueta HTML

<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>

El bloque se convertirá con la prioridad más alta en el filtro render_block_data de la siguiente manera:

Bloque convertido por el filtro render_block_data

<!-- 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 -→

Puede usar los siguientes atributos de configuración:

type: puede ser post-ids o taxonomy-ids
sub-type (opcional): puede ser la entidad específica del type si ya se conoce. Por ejemplo, product para el tipo de entrada personalizado Product. Si no se define, se adivinará la entidad específica.

Recursos adicionales

Para obtener más información sobre el archivo wpml-config.xml, visite la guía Archivos de configuración de idiomas.

Para personalizar otros elementos usando el archivo wpml-config.xml, visite nuestras guías adicionales: