Torne os blocos personalizados do Gutenberg traduzíveis

Aprenda a especificar quais blocos personalizados do Gutenberg que você desenvolveu devem ser traduzíveis. Você pode fazer isso configurando o arquivo wpml-config.xml com a ajuda do plugin de teste Multilingual Tools.

Este guia é para desenvolvedores que criam seus próprios blocos personalizados para o Gutenberg. Se você não é um autor de plugin, veja como traduzir o conteúdo criado com o editor Gutenberg.

Primeiros passos

Para começar, instale e ative:

1. Plugin principal do WPML
2. WPML Tradução de Strings
3. Multilingual Tools

O plugin Multilingual Tools não deve ser usado em sites ativos ou de produção. Use-o apenas para testes.

Geração e teste de código XML para registrar blocos do Gutenberg para tradução

1. Crie um novo post ou página e adicione os blocos do Gutenberg que você quer registrar. Certifique-se de adicionar conteúdo de teste em cada campo que você quer tornar traduzível e, em seguida, publique.

Role para baixo até a seção WPML: Gutenberg Blocks e copie o código XML gerado.

2. Vá para WPML → Configurações e cole o XML gerado na aba Configuração XML personalizada.

Certifique-se de revisar o código gerado automaticamente com atenção. Talvez você precise remover alguns campos que não devem ser traduzidos, como campos de configuração com valores específicos.

Salve quando estiver pronto.

3. Volte para a página que você publicou e faça pequenas atualizações, como editar o texto de um botão ou um cabeçalho.

Clique no ícone de mais na seção Idioma para abrir o Editor de tradução avançado. Os campos dos blocos do Gutenberg aparecem no editor e ficam disponíveis para tradução.

Depois de registrar os blocos do Gutenberg que você quer tornar traduzíveis, você pode criar o seu arquivo de configuração de idiomas. Se você já tiver um, basta editá-lo para adicionar o seu código XML finalizado.

Exemplos de registro de blocos do Gutenberg como traduzíveis

Tradução de imagens

Digamos que você tenha uma imagem que é mostrada usando o seguinte código:

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

Você quer traduzir os valores dos atributos figcaption e alt dessa imagem.

Para conseguir isso, você precisa inserir o seguinte código no 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>

Tenha em mente que o type é core/image e não wp:image, pois esse é o valor retornado pela API de blocos.

Tradução de links

Você pode especificar quais campos dos blocos do Gutenberg são links. O WPML então substituirá quaisquer links por suas traduções, se estiverem disponíveis.

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

Tradução de atributos de bloco

Aqui está um exemplo de um formato para a definição de um bloco do 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>

Você pode usar o elemento key da mesma forma que ele é usado com a configuração de Textos de administração / wp_options. Isso também significa que você pode ter elementos key dentro de elementos key pais.

Você pode usar o atributo label para adicionar rótulos personalizados opcionais que são exibidos no Editor de tradução avançado ao lado dos elementos do bloco. Quando o atributo label faz parte da tag gutenberg-block, ele será usado como um rótulo de fallback para elementos do bloco que não têm um rótulo específico definido.

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

O atributo search-method pode ter um de dois valores:

• wildcards (padrão)
• regex.

Você pode usar wildcards da mesma forma que para textos de administração. Isso significa que um asterisco (*) pode ser usado no atributo name. Aqui está um exemplo de um bloco:

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

Você pode definir o bloco usando um wildcard:

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

Isso permitirá que você traduza “The title” e “The content”, já que esses são os únicos atributos que começam com myp.

O regex permite que você tenha uma expressão regular no atributo name. Isso pode ser extremamente útil para configurações complexas. Aqui está um exemplo de um bloco:

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

Você pode definir o bloco com uma expressão 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>

Isso permitirá que você traduza “The title” e “The content”, já que esses são os únicos atributos que não começam com sublinhado (_).

Alguns plugins de blocos salvam dados em uma string JSON codificada em URL dentro do atributo de um bloco. O atributo encoding permite que você decodifique a string e registre suas subchaves para tradução.

Por exemplo, o plugin LazyBlocks armazena o conteúdo do campo repetidor em uma string JSON codificada:

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

Você pode registrar as subchaves firstname e lastname usando a seguinte configuração XML:

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

Tradução de links de atributos de bloco

Para permitir que o WPML traduza URLs automaticamente, você pode declarar os atributos de bloco do Gutenberg como links.

Aqui está um exemplo de um bloco personalizado do Gutenberg com um link clicável:

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

Para tornar os atributos label e url traduzíveis, adicione o seguinte ao seu arquivo wpml-config.xml:

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

Nessa configuração, especificar type="link" para o atributo url permite que o WPML traduza a URL automaticamente.

Namespace de bloco

Você pode ter uma configuração global para o namespace de bloco.

O nome do bloco não é mais uma parte obrigatória da definição.

Se a configuração do bloco for a mesma para todos os blocos em um namespace, você pode escrevê-la assim:

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

Conversão automática de IDs em blocos

A conversão de ID é versátil e tenta se adaptar à maioria dos formatos possíveis de IDs (ID único, lista de IDs, array serializado, array codificado em JSON).

Considere o seguinte bloco:

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

Você pode declarar, como IDs de post, os IDs de atributo de bloco e o valor do atributo da tag HTML foo_form_post_ids como abaixo:

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

O bloco será convertido com a prioridade mais alta no filtro render_block_data como abaixo:

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

Você pode usar os seguintes atributos de configuração:

• type – pode ser post-ids ou taxonomy-ids
• sub-type (opcional): pode ser a entidade específica do type se já for conhecida. Por exemplo, product para o tipo de post personalizado Product. Se não for definido, a entidade específica será adivinhada.

Recursos adicionais

Para saber mais sobre o arquivo wpml-config.xml, visite o guia Arquivos de configuração de idiomas.

Para personalizar outros elementos usando o arquivo wpml-config.xml, visite nossos guias adicionais:

• Traduza shortcodes personalizados com o WPML
• Registre o conteúdo do construtor de páginas para tradução
• Registre widgets personalizados de construtor de páginas para tradução
• Defina as opções de tradução para campos personalizados usando o arquivo de configuração do WPML
• Registre termos, tipos e taxonomias personalizados como traduzíveis
• Traduza textos que o tema e os plugins salvam em wp_options
• Personalize o seletor de idiomas do WPML usando o arquivo de configuração do WPML