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 a 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 seu próprio conjunto de 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 empacotado com um construtor de páginas. Eles podem ser criados pela sua equipe de desenvolvimento, por desenvolvedores terceirizados ou vir de outros plugins e temas.

Um widget personalizado também é qualquer widget que vem de plugins de complemento 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 foi desenvolvido para seus sites WordPress ou 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 o widget para tradução facilmente usando o wpml-config.xml, o arquivo de configuração do WPML.

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

No WPML 4.9 e 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 o arquivo wpml-config.xml manualmente, 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 para blocos do Gutenberg. Esse recurso permite que você adicione a uma página quaisquer widgets personalizados do Elementor ou blocos do Gutenberg que você queira 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 poder registrar um widget personalizado dentro do arquivo wpml-config.xml, primeiro você precisa encontrar algumas informações básicas sobre ele: o nome do tipo do widget e os nomes dos campos que você quer traduzir.

Adicione o widget sozinho a uma nova página e salve a página. O Elementor armazena os widgets da página no campo meta de post _elementor_data, e um plugin como o JSM Show Post Metadata mostra esse campo em uma caixa de meta na parte inferior do editor de páginas, para que você possa ler os dados do widget lá.

Nesses dados:

widgetType é o nome a ser usado no atributo name do widget.
As chaves em settings são os campos do widget. Uma chave que contém um texto que você quer traduzir, como title, é um nome de campo a ser registrado.
Um campo repetidor contém um array de linhas. A chave que contém esse array, como contents, é o nome “items of”.

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

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

Para verificar seu trabalho, abra uma página que usa o widget no editor de tradução. Os campos que você registrou aparecem lá pelo nome, com os textos do widget ao lado deles. Um widget que não está registrado não contribui em nada para o trabalho de tradução, então se nenhum de seus textos aparecer, o registro não teve efeito.

Registrar widgets simples

O vídeo a seguir mostra um exemplo de como registrar 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 do construtor de páginas você vai registrar. Pode ser uma destas:
- <elementor-widgets>: deve ser usada se você estiver usando o Elementor, Elementor PRO ou qualquer outro complemento do Elementor.
- <beaver-builder-widgets>: deve ser usada se você estiver usando o Beaver Builder Lite, Beaver Builder premium ou qualquer outro complemento do Beaver Builder.
- <siteorigin-widgets>: deve ser usada 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 usada quando o nome do widget é diferente da chave do widget nos dados, mas geralmente não é necessária.

Adicione os campos dos widgets, envolvendo-os em uma tag <fields>:
- field: O id do campo. Este é 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 no 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.

Registrar campos com IDs de post ou de taxonomia

Na seção acima, você aprendeu que o atributo type é normalmente usado para exibir um 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 que contêm IDs de post
type="term-ids" – para campos que contêm 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írgulas 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 a taxonomia que está 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, consulte o arquivo de configuração do Elementor e pesquise por post-ids.

Registrar widgets com campos repetidores

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

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>

Registrar widgets com campos simples e repetidores

Note que os widgets podem ter ambos os tipos: campos 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>

Agrupar campos para uma melhor organização

Para melhorar a clareza e a organização da sua configuração XML, você pode adicionar um prefixo aos 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: os campos do widget ficam em uma caixa Hotspot e cada um carrega seu próprio rótulo, facilitando a identificação e a tradução de cada campo:

Campos de um widget de hotspot no Editor de tradução avançado

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

Consulte nossa documentação sobre como registrar conteúdo de construtores de páginas no seu arquivo de configuração de idiomas para saber mais sobre como registrar strings, shortcodes e muito mais.

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:

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