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.

Los maquetadores visuales como Elementor (se abre en una pestaña nueva), Beaver Builder (se abre en una pestaña nueva), SiteOrigin (se abre en una pestaña nueva) y Cornerstone (se abre en una pestaña nueva) incluyen un conjunto de widgets propios. Estos widgets predeterminados funcionan a la perfección con WPML.

En ocasiones, es posible que cree widgets personalizados diseñados para usarse con estos u otros maquetadores visuales.

Un widget personalizado es cualquier widget único y adicional que no viene incluido con un maquetador visual. Estos 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 proporciona originalmente un maquetador visual
Si lo creó y añadió a través de otro plugin o tema
Si está desarrollado para sus sitios web de WordPress o un maquetador visual específico por su equipo o 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 mediante wpml-config.xml, el archivo de configuración de WPML.

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

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 quiere 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 mediante el plugin Herramientas multilingües

Nuestro plugin Herramientas multilingües incluye un generador de configuración (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 a registrar widgets personalizados de Elementor para su traducción y a hacer traducibles los bloques de Gutenberg.

Para poder registrar un widget personalizado en el archivo wpml-config.xml , primero necesita encontrar cierta información básica sobre él: el nombre del tipo de widget y los nombres de los campos que quiere traducir.

Añada el widget por sí solo a una página nueva y guarde la página. Elementor almacena los widgets de la página en el campo meta de la entrada _elementor_data, y un plugin como JSM Show Post Metadata (se abre en una pestaña nueva) muestra ese campo en una caja meta en la parte inferior del editor de la página, para que pueda leer los datos del widget allí.

En esos datos:

widgetType es el nombre que debe usar en el atributo name del widget.
Las claves bajo settings son los campos del widget. Una clave que contenga un texto que quiera traducir, como title, es el nombre de un campo a registrar.
Un campo repetidor contiene una matriz (array) de filas. La clave que contiene esa matriz, como contents, es el nombre de “items of” (elementos de).

Copiar los datos del widget en el Editor clásico — Matriz serializada del widget de Elementor expuesta en el Editor de traducción clásico de WPML

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

Para comprobar su trabajo, abra una página que use el widget en el editor de traducción. Los campos que registró se muestran allí por nombre, con los textos del widget a su lado. Un widget que no está registrado no aporta nada al trabajo, por lo que, si no aparece ninguno de sus textos, significa que el registro no ha surtido efecto.

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

Comience con la etiqueta <elementor-widgets>. Esto le indica a WPML qué widgets de maquetadores visuales va a registrar. Puede ser uno de los siguientes:
- <elementor-widgets>: debe usarse si está utilizando Elementor, Elementor PRO o cualquier otro complemento de Elementor.
- <beaver-builder-widgets>: debe usarse si está utilizando Beaver Builder Lite, Beaver Builder premium o cualquier otro complemento de Beaver Builder.
- <siteorigin-widgets>: debe usarse si está utilizando el maquetador visual SiteOrigin.
- <cornerstone-widgets>: y este debe usarse para el maquetador visual Cornerstone que se incluye con el tema X o el tema PRO.
Añada sus widgets:
- <widget name="widget_name"> donde widget_name es el nombre utilizado para registrar el widget en el maquetador visual.
- <conditions> (opcional): bajo conditions, 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. Es el mismo id que se usa al añadir un control mediante la función Control_stack::add_control.
- type (opcional): El tipo de campo. Es el texto que se muestra en el Editor de traducción avanzado o el Editor de traducción clásico de WPML para ayudar al traductor a saber qué campo se está traduciendo.
- editor_type (opcional): 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 se omite, su valor predeterminado es LINE.
- key_of (opcional): Solo se usa para las etiquetas <field> que tienen una matriz (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 los campos que contienen ID de entradas
type="term-ids": para los 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 la taxonomía exacta que se está 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 (se abre en una pestaña nueva) 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:

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). Eche un vistazo a 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 como ejemplo la siguiente estructura de datos del widget Table (tabla) de Ultimate Addons for Elementor:

La estructura de datos de un widget Table 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: fields y fields-in-item. Eche un vistazo a 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 el prefijo Hotspot:. Este prefijo también aparece en el Editor de traducción avanzado: los campos del widget se encuentran en un cuadro Hotspot y cada uno lleva su propia etiqueta, lo que facilita la identificación y traducción de cada campo:

Campos 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 el contenido de los maquetadores visuales en su archivo de configuración de idiomas para obtener más información sobre el registro de cadenas, shortcodes y mucho más.

Recursos adicionales

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

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

Registrar widgets personalizados de maquetadores visuales para su traducción