Registre widgets personalizados de construtor de páginas para tradução

Para registrar widgets personalizados de construtores de páginas para tradução, você precisa usar o arquivo wpml-config.xml. Siga este tutorial para aprender como usá-lo.

Este guia é para desenvolvedores que criam temas e plugins ou adicionam código personalizado de construtores de páginas ao seu site.

Se você usa um construtor de páginas de terceiros e não consegue traduzir os widgets personalizados no seu site, entre em contato com o suporte do WPML.

Construtores de páginas como Elementor, Beaver Builder, SiteOrigin e Cornerstone vêm com um conjunto de seus próprios widgets. Esses widgets padrão funcionam perfeitamente com o WPML.

Às vezes, você pode criar widgets personalizados destinados ao uso com esses ou outros construtores de páginas.

Um widget personalizado é qualquer widget único e adicional que não vem incluído em um construtor de páginas. Eles podem ser criados pela sua equipe de desenvolvimento, desenvolvedores de terceiros ou vir de outros plugins e temas.

Um widget personalizado também é qualquer widget proveniente de plugins complementares desenvolvidos especificamente para um construtor de páginas, como o Elementor, por desenvolvedores externos.

Quando preciso registrar widgets personalizados para tradução?

Você precisa registrar seu widget personalizado para tradução:

Se for um widget não fornecido originalmente por um construtor de páginas
Se você o criou e adicionou por meio de outro plugin ou tema
Se for desenvolvido para seus sites WordPress ou para um construtor de páginas específico pela sua equipe ou por terceiros

No passado, a maneira mais comum de registrar widgets personalizados para tradução era usando código PHP personalizado. Agora, você pode registrar facilmente o widget para tradução usando o wpml-config.xml, o arquivo de configuração do WPML.

Registro de widgets personalizados do Elementor para tradução no WPML 4.9+

No WPML 4.9 e em versões mais recentes, o WPML reconhece automaticamente os widgets personalizados do Elementor e os torna traduzíveis. No entanto, ele pode registrar strings que você não quer que sejam traduzidas.

É por isso que recomendamos fortemente que você ainda configure manualmente o arquivo wpml-config.xml conforme descrito nesta página. Isso dá a você controle sobre quais campos são traduzíveis.

Como registrar widgets personalizados do Elementor e blocos do Gutenberg para tradução usando o plugin Multilingual Tools

Nosso plugin Multilingual Tools inclui um WPML – Config Generator para o Elementor e blocos do Gutenberg. Esse recurso permite que você adicione a uma página quaisquer widgets personalizados do Elementor ou blocos do Gutenberg que você quer registrar para tradução. Em seguida, ele gera automaticamente a primeira versão do código XML que você precisa.

Aprenda a registrar widgets personalizados do Elementor para tradução e a tornar os blocos do Gutenberg traduzíveis.

Para conseguir registrar um widget personalizado dentro do arquivo wpml-config.xml, primeiro você precisa encontrar algumas informações básicas sobre ele.

Você pode obter essas informações facilmente usando um plugin como o JSM Show Post Metadata. Esse plugin mostra os metadados do post e seus valores desserializados em uma caixa de meta na parte inferior das páginas de edição de posts.

Como alternativa, você pode usar as seguintes etapas para obter essas informações:

Vá para a página WPML → Configurações, role até a seção Tradução de campos personalizados e clique no link Mostrar campos de sistema.
Defina o campo personalizado _elementor_data como Traduzir.
Crie uma nova página e adicione apenas o widget do Elementor que você quer registrar. Salve a página.
Vá para WPML → Configurações e, na seção Editor de tradução, ative temporariamente a opção Editor de tradução clássico.
Tente traduzir a página que você criou na Etapa 3 usando o Editor de tradução clássico e você notará um array serializado, como este:

Copiando os dados do widget no editor clássico — Array serializado do widget do Elementor exposto no Editor de tradução clássico do WPML

Copie o conteúdo do array serializado.
Use sua ferramenta de desserialização preferida para ver melhor como o widget está exibindo seu conteúdo. No nosso caso, usamos o site Unserialize.

Aqui está a explicação do conteúdo do array que você verá:

[widgetType] contém o nome inserido no atributo name da tag do widget.
Os campos reais estarão dentro de um Array e você pode encontrá-los pesquisando por [0], o que trará o conteúdo do primeiro elemento do array.
O valor do campo será o nome dentro dos colchetes que conterá o nome do campo. Por exemplo: [title] => this is a field title. Neste caso, “title” é o texto que você precisa.
“Items of” obterá seu valor do elemento que cria o array. Por exemplo: [contents]=> array. Neste caso, “contents” é o texto que você precisa.

Assim que você tiver essas informações, poderá prosseguir com o registro real do widget para tradução.

Registro de widgets simples

O vídeo a seguir mostra um exemplo de registro de um widget simples do Elementor:

O exemplo a seguir ilustra como registrar um widget simples. Um widget simples aqui significa que o widget não tem campos repetidores.

<wpml-config>
	<elementor-widgets>
		<widget name="heading">
			<conditions>
				<condition key="widgetType">heading</condition>
			</conditions>
			<fields>
				<field type="Heading" editor_type="LINE">title</field>
				<field type="Heading: Link URL" editor_type="LINK">link>url</field>
			</fields>
		</widget>
	</elementor-widgets>
</wpml-config>

Vamos analisar a estrutura do exemplo fornecido:

Comece com a tag <elementor-widgets>. Isso diz ao WPML quais widgets de construtores de páginas você vai registrar. Pode ser uma destas:
- <elementor-widgets>: isso deve ser usado se você estiver usando o Elementor, Elementor PRO ou qualquer outro complemento do Elementor.
- <beaver-builder-widgets>: isso deve ser usado se você estiver usando o Beaver Builder Lite, o Beaver Builder premium ou qualquer outro complemento do Beaver Builder.
- <siteorigin-widgets>: isso deve ser usado se você estiver usando o construtor de páginas SiteOrigin.
- <cornerstone-widgets>: e esta deve ser usada para o construtor de páginas Cornerstone que vem com o tema X ou o tema PRO.
Adicione seus widgets:
- <widget name="widget_name"> onde widget_name é o nome usado para registrar o widget no construtor de páginas.
- <conditions> (opcional): em condições, você adiciona uma condição com uma chave igual ao nome do widget. Pode ser usado quando o nome do widget é diferente da chave do widget nos dados, mas geralmente não é necessário.

Adicione os campos dos widgets, envolvendo-os em uma tag <fields>:
- field: O id do campo. É o mesmo id usado ao adicionar um controle por meio da função Control_stack::add_control.
- type (opcional): O tipo de campo. Este é o texto exibido no Editor de tradução avançado ou Editor de tradução clássico do WPML para ajudar o tradutor a saber qual campo está sendo traduzido.
- editor_type (opcional): Este é o tipo de campo de texto usado no Editor de tradução clássico do WPML. Os valores válidos são LINE, AREA, LINK e VISUAL. O padrão é LINE se estiver ausente.
- key_of (opcional): Isso é usado apenas para tags <field> que têm um array dentro de uma tag <fields-in-item>.

Você pode usar esses elementos para registrar um widget simples com qualquer número de campos.

Registro de campos com IDs de post ou taxonomia

Na seção acima, você aprendeu que o atributo type é normalmente usado para exibir texto descritivo no Editor de tradução.

No entanto, quando os campos do seu widget armazenam IDs de post ou IDs de taxonomia (como imagens selecionadas, posts relacionados ou categorias escolhidas), você usa valores especiais que acionam a conversão automática:

type="post-ids" – para campos contendo IDs de post
type="term-ids" – para campos contendo IDs de taxonomia/termo

Quando você usa esses valores de types:

O campo não aparecerá no editor de tradução
O WPML converte automaticamente os IDs para apontar para o conteúdo traduzido correspondente
Tanto IDs únicos quanto listas de IDs separadas por vírgula são suportados

Exemplo:

<wpml-config>
    <elementor-widgets>
        <widget name="the-widget-name">
            <fields>
                <field type="post-ids" sub-type="attachment">image_id</field>
                <field type="post-ids" sub-type="post">selected_posts</field>
                <field type="term-ids" sub-type="category">category_filter</field>
            </fields>
        </widget>
    </elementor-widgets>
</wpml-config>

Neste exemplo, o atributo opcional sub-type especifica o tipo de post exato ou taxonomia sendo convertida:

Para type="post-ids": use sub-type="attachment", sub-type="post", sub-type="page" ou o slug do seu tipo de post personalizado
Para type="term-ids": use sub-type="category", sub-type="post_tag" ou o slug da sua taxonomia personalizada

Adicionar sub-type melhora o desempenho ao evitar consultas extras ao banco de dados para determinar o tipo de conteúdo.

Para mais exemplos, veja o arquivo de configuração do Elementor e pesquise por post-ids.

Registro de widgets com campos repetidores

O vídeo a seguir mostra um exemplo de registro de um widget avançado do Elementor com campos repetidores:

A hotspot widget's fields in the Advanced Translation Editor

Para os widgets que têm campos repetidores, você precisa envolver os campos na tag <fields-in-item items_of="tabs"> (onde tabs é o nome do widget com campos repetidos). Confira este exemplo:

<widget name="accordion">
	<fields-in-item items_of="tabs">
		<field type="Accordion: Title" editor_type="LINE">tab_title</field>
		<field type="Accordion: Content" editor_type="VISUAL">tab_content</field>
	</fields-in-item>
</widget>

Em alguns casos, o widget pode ter vários campos repetidores. Considere a seguinte estrutura de dados do widget Table do Ultimate Addons for Elementor como exemplo:

A estrutura de dados de um widget Table do Ultimate Addons for Elementor

Para registrar este widget, veja o exemplo a seguir:

<widget name="uael-table">
	<fields-in-item items_of="table_content">
		<field type="The Cell text" editor_type="LINE">cell_text</field>
	</fields-in-item>
	<fields-in-item items_of="table_headings">
		<field type="The Heading text" editor_type="LINE">heading_text</field>
	</fields-in-item>
</widget>

Registro de widgets com campos simples e repetidores

Observe que os widgets podem ter ambos os tipos: fields e fields-in-item. Confira este exemplo de um widget que usa ambos:

<widget name="price-table">
	<fields>
		<field type="Price Table: Heading" editor_type="LINE">heading</field>
		<!-- ... -->
	</fields>
	<fields-in-item items_of="features_list">
		<field type="Price table: text" editor_type="LINE">item_text</field>
	</fields-in-item>
</widget>

Agrupamento de campos para melhor organização

Para melhorar a clareza e a organização da sua configuração XML, você pode prefixar os rótulos dos campos com o nome do grupo. Considere este exemplo de um widget de hotspot:

<widget name="hotspot">
    <fields-in-item items_of="hotspot">
        <field type="Hotspot: Label">hotspot_label</field>
        <field type="Hotspot: URL" key_of="hotspot_link">url</field>
        <field type="Hotspot: Content" editor_type="VISUAL">hotspot_tooltip_content</field>
    </fields-in-item>
</widget>

Aqui, cada campo dentro do widget de hotspot é prefixado com o rótulo Hotspot:. Esse prefixo também aparece no Editor de tradução avançado, tornando mais fácil identificar e traduzir cada campo:

Traduzindo o widget de hotspot no Editor de tradução avançado

Registro de outros tipos de conteúdo de construtores de páginas

Veja nossa documentação sobre como registrar conteúdo de construtores de páginas no seu arquivo de configuração de idioma para mais informações sobre como registrar strings, shortcodes e muito mais.

Recursos adicionais

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

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

Registrar widgets personalizados de construtores de páginas para tradução