Registrar widgets personalizados del maquetador visual para su traducción

Para registrar widgets personalizados de maquetadores visuales para su traducción, necesita usar el archivo wpml-config.xml. Siga este tutorial para aprender a usarlo.

Esta guía es para desarrolladores que crean temas y plugins o añaden código personalizado de maquetadores visuales a su sitio.

Si usa un maquetador visual de terceros y no puede traducir los widgets personalizados de su sitio web, contacte con el soporte de WPML.

Maquetadores visuales como Elementor, Beaver Builder, SiteOrigin y Cornerstone incluyen un conjunto de widgets propios. Estos widgets predeterminados funcionan perfectamente con WPML.

A veces, puede crear widgets personalizados diseñados para usarse con estos u otros maquetadores visuales.

Un widget personalizado es cualquier widget adicional y único que no viene incluido con un maquetador visual. Pueden ser creados por su equipo de desarrollo, desarrolladores externos o provenir de otros plugins y temas.

Un widget personalizado también es cualquier widget que provenga de complementos desarrollados específicamente para un maquetador visual, como Elementor, por desarrolladores externos.

¿Cuándo necesito registrar widgets personalizados para su traducción?

Necesita registrar su widget personalizado para su traducción:

Si es un widget que no fue proporcionado originalmente por un maquetador visual
Si lo creó y añadió a través de otro plugin o tema
Si fue desarrollado para sus sitios web de WordPress o un maquetador visual específico por su equipo o por terceros

En el pasado, la forma más común de registrar widgets personalizados para su traducción era usando código PHP personalizado. Ahora, puede registrar fácilmente el widget para su traducción usando wpml-config.xml, el archivo de configuración de WPML.

Registrar widgets personalizados de Elementor para su traducción en WPML 4.9 y superior

En WPML 4.9 y versiones posteriores, WPML reconoce automáticamente los widgets personalizados de Elementor y los hace traducibles. Sin embargo, es posible que registre cadenas que usted no quiera traducir.

Por eso, le recomendamos encarecidamente que siga configurando manualmente el archivo wpml-config.xml como se describe en esta página. Esto le da control sobre qué campos son traducibles.

Cómo registrar widgets personalizados de Elementor y bloques de Gutenberg para su traducción usando el plugin Herramientas multilingües

Nuestro plugin Herramientas multilingües incluye un WPML - Config Generator para Elementor y bloques de Gutenberg. Esta característica le permite añadir a una página cualquier widget personalizado de Elementor o bloque de Gutenberg que quiera registrar para su traducción. A continuación, genera automáticamente la primera versión del código XML que necesita.

Aprenda cómo registrar widgets personalizados de Elementor para su traducción y cómo hacer traducibles los bloques de Gutenberg.

Para poder registrar un widget personalizado dentro del archivo wpml-config.xml, primero necesita encontrar cierta información básica sobre él.

Puede obtener esta información fácilmente usando un plugin como JSM Show Post Metadata. Este plugin muestra los metadatos de la entrada y sus valores no serializados en una caja de metadatos (metabox) en la parte inferior de las páginas de edición de entradas.

Alternativamente, puede seguir los siguientes pasos para obtener esta información:

Vaya a la página WPML → Configuración, desplácese hasta la sección Traducción de campos personalizados y haga clic en el enlace Mostrar campos del sistema.
Establezca el campo personalizado _elementor_data en Traducir.
Cree una nueva página y añada solo el widget de Elementor que desea registrar. Guarde la página.
Vaya a WPML → Configuración y en la sección Editor de traducción active temporalmente la opción Editor de traducción clásico.
Intente traducir la página que creó en el paso 3 usando el Editor de traducción clásico y notará un array serializado, como este:

Copiar los datos del widget en el Editor clásico — Array serializado del widget de Elementor expuesto en el Editor de traducción clásico de WPML

Copie el contenido del array serializado.
Use su herramienta de deserialización preferida para ver mejor cómo el widget está generando su contenido. En nuestro caso, usamos el sitio Unserialize.

A continuación, se explica el contenido del array que verá:

[widgetType] contiene el nombre insertado en el atributo name de la etiqueta del widget.
Los campos reales estarán dentro de un array y puede encontrarlos buscando [0], lo que traerá el contenido del primer elemento del array.
El valor del campo será el nombre dentro de los corchetes que contendrá el nombre del campo. Por ejemplo: [title] => this is a field title. En este caso, “title” es el texto que necesita.
“Items of” obtendrá su valor del elemento que crea el array. Por ejemplo: [contents]=> array. En este caso, “contents” es el texto que necesita.

Una vez que tenga esta información, puede proceder a registrar el widget para su traducción.

Registrar widgets simples

El siguiente vídeo le muestra un ejemplo de cómo registrar un widget simple de Elementor:

El siguiente ejemplo ilustra cómo registrar un widget simple. Aquí, un widget simple significa que el widget no tiene 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>

Repasemos la estructura del ejemplo dado:

Comience con la etiqueta <elementor-widgets>. Esto le indica a WPML qué widgets del maquetador visual va a registrar. Puede ser uno de estos:
- <elementor-widgets>: debe usarse si está usando Elementor, Elementor PRO o cualquier otro complemento de Elementor.
- <beaver-builder-widgets>: debe usarse si está usando Beaver Builder Lite, Beaver Builder premium o cualquier otro complemento de Beaver Builder.
- <siteorigin-widgets>: debe usarse si está usando el maquetador visual SiteOrigin.
- <cornerstone-widgets>: y este debe usarse para el maquetador visual Cornerstone que viene con el tema X o el tema PRO.
Añada sus widgets:
- <widget name="widget_name"> donde widget_name es el nombre usado para registrar el widget en el maquetador visual.
- <conditions> (opcional): bajo condiciones, añade una condición con una clave igual al nombre del widget. Puede usarse cuando el nombre del widget es diferente de la clave del widget en los datos, pero por lo general no es necesario.

Añada los campos de los widgets, envolviéndolos en una etiqueta <fields>:
- field: El ID del campo. Este es el mismo ID que se usa al añadir un control a través de la función Control_stack::add_control.
- type (opcional): El tipo de campo. Este es el texto que se muestra en el Editor de traducción avanzado o en el Editor de traducción clásico de WPML para ayudar al traductor a saber qué campo se está traduciendo.
- editor_type (opcional): Este es el tipo de campo de texto que se usa en el Editor de traducción clásico de WPML. Los valores válidos son LINE, AREA, LINK y VISUAL. Si falta, el valor predeterminado es LINE.
- key_of (opcional): Esto solo se usa para las etiquetas <field> que tienen un array dentro de una etiqueta <fields-in-item>.

Puede usar estos elementos para registrar un widget simple con cualquier número de campos.

Registrar campos con ID de entradas o taxonomías

En la sección anterior, aprendió que el atributo type se usa normalmente para mostrar texto descriptivo en el Editor de traducción.

Sin embargo, cuando los campos de su widget almacenan ID de entradas o ID de taxonomías (como imágenes seleccionadas, entradas relacionadas o categorías elegidas), se usan valores especiales que activan la conversión automática:

type="post-ids" – para campos que contienen ID de entradas
type="term-ids" – para campos que contienen ID de taxonomías o términos

Cuando usa estos valores de types:

El campo no aparecerá en el editor de traducción
WPML convierte automáticamente los ID para que apunten al contenido traducido correspondiente
Se admiten tanto ID individuales como listas de ID separadas por comas

Ejemplo:

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

En este ejemplo, el atributo opcional sub-type especifica el tipo de contenido o taxonomía exactos que se están convirtiendo:

Para type="post-ids": use sub-type="attachment", sub-type="post", sub-type="page" o el slug de su tipo de contenido personalizado
Para type="term-ids": use sub-type="category", sub-type="post_tag" o el slug de su taxonomía personalizada

Añadir sub-type mejora el rendimiento al evitar consultas adicionales a la base de datos para determinar el tipo de contenido.

Para ver más ejemplos, consulte el archivo de configuración de Elementor y busque post-ids.

Registrar widgets con campos repetidores

El siguiente vídeo le muestra un ejemplo de cómo registrar un widget avanzado de Elementor con campos repetidores:

A hotspot widget's fields in the Advanced Translation Editor

Para los widgets que tienen campos repetidores, necesita envolver los campos en la etiqueta <fields-in-item items_of="tabs"> (donde tabs es el nombre del widget con campos repetidos). Vea este ejemplo:

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

En algunos casos, el widget puede tener múltiples campos repetidores. Considere la siguiente estructura de datos del widget de tabla (Table) de Ultimate Addons for Elementor como ejemplo:

Estructura de datos de un widget de tabla de Ultimate Addons for Elementor

Para registrar este widget, consulte el siguiente ejemplo:

<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 con campos simples y repetidores

Tenga en cuenta que los widgets pueden tener ambos tipos: campos y campos dentro de elementos (fields-in-item). Vea este ejemplo de un 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 una mejor organización

Para mejorar la claridad y organización de su configuración XML, puede añadir el nombre del grupo como prefijo a las etiquetas de los campos. Considere este ejemplo de un widget de punto de acceso (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>

Aquí, cada campo dentro del widget de punto de acceso tiene como prefijo la etiqueta Hotspot:. Este prefijo también aparece en el Editor de traducción avanzado, lo que facilita la identificación y traducción de cada campo:

Traducción de un widget de punto de acceso en el Editor de traducción avanzado

Registrar otros tipos de contenido de maquetadores visuales

Consulte nuestra documentación sobre cómo registrar contenido de maquetadores visuales en su archivo de configuración de idiomas para obtener más información sobre el registro de cadenas, shortcodes y más.

Recursos adicionales

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

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

Registrar widgets personalizados de maquetadores visuales para su traducción