WPML

WPML traduz os atributos de um bloco personalizado somente até onde um arquivo de configuração de idioma os declara. Blockstudio armazena cada valor de campo no comentário do bloco em blockstudio.attributes, então cada bloco precisa de uma entrada que aponte WPML para seus campos de texto e IDs de anexos. O comando wp bs wpml config grava essas entradas para cada bloco registrado.

Por que os blocos precisam de uma configuração

WPML lê a configuração de um arquivo chamado wpml-config.xml na pasta raiz do tema ativo e de cada plugin ativo. Para um plugin obrigatório de arquivo único, a pasta tem o nome do arquivo sem .php. Consulte Arquivos de configuração de idioma e Torne os blocos Gutenberg personalizados traduzíveis.

Um bloco sem uma entrada fica sujeito à detecção automática de strings de WPML, que disponibiliza para tradução todos os atributos de string do bloco. Em um bloco Blockstudio que inclui valores de seleção, referências a arquivos, URLs e classes CSS. Os tradutores veem esses valores técnicos ao lado do texto real, e um valor de seleção ou uma classe traduzidos podem quebrar o bloco.

Gerar a configuração

Exiba a configuração e salve-a na pasta raiz do tema ou plugin que inclui os blocos:

wp bs wpml config > wp-content/themes/my-theme/wpml-config.xml

Ou deixe o comando gravar o arquivo:

wp bs wpml config --file=wp-content/themes/my-theme/wpml-config.xml

Um bloco com um campo de texto, uma imagem, um link e um repetidor:

{
  "name": "my-theme/cards",
  "title": "Cards",
  "blockstudio": {
    "attributes": [
      { "id": "heading", "type": "text", "label": "Heading" },
      { "id": "gallery", "type": "files", "label": "Gallery", "multiple": true },
      {
        "id": "style",
        "type": "select",
        "label": "Style",
        "options": [
          { "value": "light", "label": "Light" },
          { "value": "dark", "label": "Dark" }
        ]
      },
      {
        "id": "cards",
        "type": "repeater",
        "label": "Cards",
        "attributes": [
          { "id": "title", "type": "text", "label": "Title" },
          { "id": "image", "type": "files", "label": "Image" },
          { "id": "link", "type": "link", "label": "Button" }
        ]
      }
    ]
  }
}

se torna:

<wpml-config>
	<gutenberg-blocks>
		<!-- blockstudio:start -->
		<!-- Generated by wp bs wpml config. Run it again after changing block fields; edits between the markers are replaced. -->
		<gutenberg-block type="my-theme/cards" translate="1" label="Cards">
			<key name="blockstudio">
				<key name="attributes">
					<key name="heading" label="Heading" />
					<key name="gallery">
						<key name="*" type="post-ids" sub-type="attachment" />
					</key>
					<key name="cards">
						<key name="*">
							<key name="title" label="Cards: Title" />
							<key name="image" type="post-ids" sub-type="attachment" />
							<key name="link">
								<key name="title" label="Cards: Button: Link text" />
								<key name="url" type="link" label="Cards: Button: URL" />
							</key>
						</key>
					</key>
				</key>
			</key>
		</gutenberg-block>
		<!-- blockstudio:end -->
	</gutenberg-blocks>
</wpml-config>

O valor style não está declarado, então WPML o copia para a tradução sem alterações. Os IDs gallery e image também são copiados, e WPML substitui cada um pelo anexo correspondente ao idioma da página quando o bloco é renderizado, para que uma imagem traduzida possa ter seu próprio texto alternativo. Consulte “Conversão automática de IDs em blocos” em Torne os blocos Gutenberg personalizados traduzíveis. Quando um anexo não tem tradução, WPML mantém o ID original.

O que é declarado

O comando lê os blocos registrados depois que os campos de custom/ e os campos do bloco são expandidos e as substituições e os filtros de atributos são aplicados. Os campos que as extensões adicionam a um bloco Blockstudio são incluídos. Os campos que as extensões adicionam a blocos principais ou a blocos de outros plugins não são incluídos, porque esses blocos obtêm sua configuração de WPML ou de seu próprio plugin.

Um bloco sem um campo de texto declarado recebe translate="0". WPML então copia todos os seus valores e não disponibiliza nenhum deles para tradução. Seus campos files ainda são declarados na entrada, porque WPML converte IDs de anexos independentemente do que translate determina. Os blocos internos são traduzidos normalmente.

Não declarado:

• Campos com hidden, porque seus valores não são gravados por editores.
• Campos com "translate": false, veja abaixo.
• Campos de tipos de campo personalizados que não são registrados com translate definido como true. O comando exibe um aviso para cada um, porque somente o tipo de campo sabe se o valor contém texto. Um "translate": false explícito em um campo também suprime esse aviso para esse campo. Veja abaixo.
• Atributos que um bloco declara em seu attributes nativo, em vez de como campos Blockstudio.
• Chaves de armazenamento cujos campos têm tipos diferentes, veja abaixo.

Todo campo de texto é declarado, inclusive um que contenha um valor técnico, como uma classe CSS, a menos que defina "translate": false.

Excluir um campo

Um campo de texto pode conter um valor que precisa ser igual em todos os idiomas: um nome de usuário, um endereço de e-mail, uma âncora, uma classe CSS. WPML o disponibiliza para tradução como qualquer outro texto, e um valor traduzido pode quebrar o bloco. Defina translate como false para excluir o campo da configuração, assim WPML copia seu valor para a tradução sem alterações:

{
  "id": "account",
  "type": "text",
  "label": "Account handle",
  "translate": false
}

Em um group, tabs ou repeater, "translate": false se aplica a todos os campos internos, inclusive aos contêineres aninhados. Um filho não pode substituir a exclusão de um contêiner com "translate": true. Em um campo files, false também exclui os IDs dos anexos, para que a tradução mantenha os anexos originais.

Omitir translate ou defini-lo como true preserva o comportamento existente: o tipo de campo decide. Isso não torna campos ocultos nem tipos de valor como select traduzíveis. A opção se aplica a campos de blocos e extensões, não oculta nem desativa os controles do editor e não altera os valores armazenados. Execute wp bs wpml config novamente depois de alterar a configuração e atualize seu wpml-config.xml com a configuração gerada.

O label de cada chave é o rótulo do campo, precedido pelos rótulos dos repetidores e grupos envolventes que têm um ID. WPML o exibe como nome do campo no editor de tradução. As duas chaves de um campo link acrescentam Link text e URL ao rótulo. Esses sufixos são traduzidos para o idioma do site, então execute o comando com a localidade usada pelos tradutores.

Tipos de campo personalizados

Um tipo de campo que armazena uma string de texto simples informa isso ao ser registrado. Defina translate como true na definição, o que exige que attribute seja string:

bs_register_field_type('acme/headline', [
  'attribute' => 'string',
  'translate' => true,
]);

O comando declara então cada campo desse tipo como texto traduzível. Um campo ainda pode definir "translate": false para se excluir. Sem essa opção, os campos desse tipo são excluídos e informados, como antes.

Alterar os rótulos

Os rótulos dos campos são escritos para o editor de blocos e podem conter indicações como “Imagem (opcional)” que não fazem sentido no editor de tradução. O filtro blockstudio/wpml/config/label recebe cada rótulo antes de ser escrito, com o contexto da chave:

• block: o nome do bloco.
• path: o caminho de armazenamento do campo abaixo de blockstudio.attributes, com um nível * para as linhas de cada repetidor, por exemplo cards/*/link.
• field: a definição do campo.
• parents: os rótulos dos repetidores e grupos envolventes que têm um ID.
• part: text para um campo de texto, title ou url para as duas chaves de um campo de link.

add_filter('blockstudio/wpml/config/label', function ($label, $context) {
  return str_replace(' (optional)', '', $label);
}, 10, 2);

Retorne uma string vazia para excluir o rótulo de uma chave, para que WPML mostre o rótulo do bloco. Um valor retornado que não seja uma string mantém o rótulo original. Execute o comando novamente depois de alterar o filtro.

Campos com a mesma chave de armazenamento

Dois campos podem acabar com a mesma chave de armazenamento, por exemplo, um campo de bloco e um campo de extensão com o mesmo id, ou o campo text em um grupo com o ID cta e um campo com o ID cta_text. O comando declara essa chave apenas quando está claro o que é armazenado nela:

• Entre os campos de um bloco, fora das linhas de repetidores, Blockstudio registra um atributo por chave de armazenamento, então um campo posterior substitui um anterior, independentemente do tipo. Os campos das extensões de um bloco funcionam da mesma forma: um campo posterior, ou o campo de uma extensão registrada posteriormente, substitui um anterior.
• Um campo de bloco e um campo de extensão com a mesma chave permanecem ativos. O modelo do bloco recebe o valor conforme definido pelo campo do bloco, enquanto a extensão é aplicada com seu próprio campo. A chave é declarada uma vez quando ambos os campos precisam da mesma declaração: ambos são campos de texto (text, textarea, richtext ou wysiwyg), ambos são links, ambos são campos files (com multiple em qualquer um deles, a chave recebe o nível *), ou nenhum dos dois é declarado, como um select e um number. Dois repetidores são comparados campo a campo em suas linhas. O rótulo vem do campo do bloco.
• Dois campos com o mesmo id nas linhas de um repetidor também permanecem ativos e são comparados da mesma forma.

Quando os tipos diferem, por exemplo, um campo text no bloco e um select em uma extensão, o valor armazenado é texto ou uma opção de seleção, dependendo do controle que o gravou. O comando não declara a chave e exibe um aviso:

Warning: Not declared, the fields that store this key have different types: my-theme/cards: tone (text in the block, select in an extension)

Renomeie um dos campos ou atribua o mesmo tipo a ambos para que a chave seja declarada.

Manter a configuração atualizada

Execute o comando novamente depois de adicionar, remover ou renomear campos e distribua o arquivo atualizado com o tema ou plugin. Regenere as configurações criadas antes de 7.7.5 para incluir declarações de IDs de anexos. Conteúdos existentes passam a mostrar novos campos para tradução quando o original é atualizado, conforme descrito no guia WPML acima.

Com --file, o comando cria um arquivo inexistente. Em um arquivo existente, ele substitui apenas o texto entre <!-- blockstudio:start --> e <!-- blockstudio:end -->, mantendo as outras seções e entradas de outros blocos como estão:

<wpml-config>
	<custom-types>
		<custom-type translate="1">book</custom-type>
	</custom-types>
	<gutenberg-blocks>
		<gutenberg-block type="my-plugin/map" translate="1">
			<key name="caption" />
		</gutenberg-block>
		<!-- blockstudio:start -->
		<!-- blockstudio:end -->
	</gutenberg-blocks>
</wpml-config>

Para usar um arquivo existente que ainda não tenha marcadores, adicione uma vez as duas linhas de marcador dentro do elemento gutenberg-blocks ou adicione um elemento gutenberg-blocks com os marcadores, caso o arquivo não tenha nenhum. Sem os marcadores, ou quando o resultado não for uma configuração válida, o comando mantém o arquivo inalterado e é encerrado com um erro.

As entradas de blocos Blockstudio escritas manualmente, como entradas translate="0" que ocultam valores técnicos, deixam de ser necessárias quando a seção gerada abrange o bloco. O comando avisa sobre cada bloco declarado mais de uma vez, para que essas entradas possam ser removidas.

Textos de imagem em tarefas de tradução

WPML inclui os textos das imagens usadas por uma página na tarefa de tradução dessa página: título, texto alternativo, legenda e descrição. Quando a tarefa é concluída, WPML grava os textos traduzidos no anexo do idioma de destino e cria esse anexo caso ainda não exista. Consulte Como traduzir mídia. WPML encontra as imagens em tags <img> no conteúdo, em galerias, na imagem destacada e nos blocos que reconhece. Um bloco Blockstudio armazena IDs de anexos no comentário do bloco, então WPML não encontra nenhum deles.

Quando WPML está ativo, Blockstudio adiciona às imagens encontradas WPML os anexos armazenados pelos campos nos blocos de uma página:

• Campos files, inclusive os ocultos, e campos attributes com media, os mesmos campos que o editor de blocos carrega como mídia.
• Campos em grupos, abas, linhas de repetidores e blocos internos.
• Campos de extensões, também em blocos principais e blocos de outros plugins, porque seus valores são armazenados nos atributos do bloco estendido.

Valores que não sejam IDs de anexos são excluídos. Não é necessário configurar nada, e wpml-config.xml não é envolvido. Sem WPML, nada é analisado para tarefas de tradução e a classe de integração de mídia não é carregada.

Isso é independente da conversão de IDs de anexos: o XML gerado informa a WPML qual anexo traduzido renderizar, enquanto essa integração informa quais textos de anexos incluir em uma tarefa de tradução. Referências de strings e IDs de publicações que não sejam anexos não são adicionados às tarefas de mídia. Valores de campos aninhados salvos têm precedência sobre valores de nível superior em blocos Blockstudio, assim como na renderização.

Os textos só fazem parte da tarefa quando uma das opções de texto de imagem em WPML > Configurações > Tradução de mídia está ativada: “Detectar automaticamente as melhores opções para traduzir textos de imagem” ou “Traduzir textos da Biblioteca de mídia ao traduzir conteúdo”, como acontece com imagens em blocos principais.

Blockstudio informa as imagens pelo filtro wpml_ids_of_media_used_in_post, que WPML se aplica à mídia de uma publicação em PostWithMediaFiles. Para excluir uma imagem das tarefas, remova seu ID em um callback no mesmo filtro com prioridade acima de 10:

add_filter(
	'wpml_ids_of_media_used_in_post',
	function ( $ids ) {
		return array_values( array_diff( $ids, array( 42 ) ) );
	},
	20
);