How to register page builder widgets for translation

Ahmed Mohammed

Originally written

October 15, 2020

Updated

October 19, 2020

Starting from WPML 4.4.4, you can use the wpml-config.xml file to define the widgets for Elementor, Beaver Builder, and Cornerstone page builders.

If you have a custom Elementor, Beaver Builder, or Cornerstone widget, instead of using PHP integration (check here for Elementor example), you can register the widget for translation using the wpml-config.xml file.

Throughout this tutorial, we’ll demonstrate how to register Elementor widgets within the wpml-config.xml file. This applies to new Elementor widgets, new Elementor PRO widgets, and any other Elementor addon.

Registering simple widgets

The following example illustrates how to register a simple widget. By a simple widget, it means that the widget has no repeater fields.

<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" key_of="link">url</field>
			</fields>
		</widget>
	</elementor-widgets>
</wpml-config>

Let’s go through the structure of the given example:

1. Start with the <elementor-widgets> tag. This tells WPML which page builder widgets you are going to register. It can be one of these:
   • <elementor-widgets>: this must be used if you’re using Elementor, Elementor PRO or any other Elementor addon.
   • <beaver-builder-widgets>: this must be used if you’re using Beaver Builder Lite, premium Beaver Builder or any other Beaver Builder addon.
   • <cornerstone-widgets>: and this one must be used for Cornerstone page builder that comes with X theme or PRO theme.
2. Add your widgets:
   • <widget name="widget_name"> where widget_name is the name used to register the widget in the page builder.
   • <conditions> (optional): under conditions, you add a condition with a key equal to the widget name. It can be used when the widget name is different from the widget key in the data, but it’s usually not needed.

3. Add the fields of the widgets, wrapping them in a <fields> tag:
   • field: The id of the field. This is the same as the id used when adding a control via the Control_stack::add_control function.
   • type (optional): The type of field. This is the text displayed in the WPML Advanced Translation Editor or Classic Translation Editor to help the translator know what field is being translated.
   • editor_type (optional): This is the type of text field used in the WPML Classic Translation Editor. Valid values are LINE, TEXTAREA, LINK and VISUAL. It defaults to LINE if missing.
   • key_of (optional): This is only used with links and holds the array name that includes that link. 

You can use these elements to register a simple widget with any number of fields. 

Registering widgets with repeater fields

For the widgets that have repeater fields, you need to wrap the fields in <fields-in-item items_of="tabs"> tag (where tabs is the name of the widget with repeated fields). Check out this example:

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

Registering widgets with both simple and repeater fields

Note, widgets can have both types: fields and fields-in-item. Check out this example for a widget that uses both:

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

Registering other types of page builder content

See our documentation on registering page builder content in your language configuration file for more on registering strings, shortcodes, and more.