Skip Navigation
Home » WPML Documentation » Developers Information » Maintaining WPBakery Page Builder Compatibility with WPML

Maintaining WPBakery Page Builder Compatibility with WPML

Dario
Updated
October 17, 2024

The compatibility of the WPBakery Page Builder with WPML is assured through the language configuration file. Learn how to use this file to maintain compatibility.

This page is intended for the WPBakery development team, developers who offer a customized version of the page builder, authors who develop WPBakery addons, and web developers using WPBakery Page builder.

If you are a client looking to translate a site built with WPBakery, please see our detailed documentation to learn more about building multilingual sites with WPBakery Page Builder and WPML.

How the Integration of the WPBakery Page Builder Works With WPML

To understand how the WPBakery Page Builder works with WPML, let us start by creating a simple page using the WPBakery Page Builder. We will include a few modules, such as a Text Block, a Message Box, and a Hover Box.

A simple page created using WPBakery page builder

To translate the page we created, click on the plus icon found in the Language meta box in the right sidebar.

Click the plus icon to translate the page

This will take you to the Advanced Translation Editor screen, where you can translate your page. Fill in the translations for each sentence and confirm them by clicking the green check mark. Once you’re satisfied with all your translations, click Complete.

Translating WPBakery in the Advanced Translation Editor
Translating WPBakery in the Advanced Translation Editor

Updating the Language Configuration File

You might need to update the page builder shortcodes in the language configuration file for different reasons:

  1. Adding a new shortcode to the page builder
  2. Adding a new attribute to an existing shortcode
  3. Removing an obsolete shortcode

You can download the language configuration file from our repository. Add the shortcodes or attributes to the existing shortcodes within the language configuration file.

For authors who are bundling a customized version of WPBakery Page Builder in their theme, please take into consideration that you will need to update the language configuration file of the customized version of the plugin.

Page Builder Shortcode Structure in the Language Configuration File

To extract strings from pages built using the WPBakery Page Builder and load them on the Translation Editor screen, we need to configure WPML to identify the shortcodes and attributes containing the strings that require translation. This is done by adding a file, called wpml-config.xml, which is typically placed in the root folder of your theme. For WPBakery Page Builder, we are hosting the language configuration file on our servers. It is set to override the local configuration file placed in WPBakery’s Page Builder root folder, ensuring that the configuration file is always up to date.

The wpml-config.xml file is also used to configure the following elements:

  1. Custom fields
  2. Custom taxonomies
  3. Admin texts / wp_options
  4. Language switcher configuration
  5. Page builder shortcodes

See our detailed documentation to learn more about the language configuration file structure and syntax.

As an example, let us see how we added the Tabs shortcode to the wpml-config.xml file.

Example of the WPBakery page builder shortcodes in the language configuration file 
<shortcode>
         <tag>vc_tta_tabs</tag>
         <attributes>
            <attribute encoding="allow_html_tags">title</attribute>
         </attributes>
</shortcode>

The structure of the above example can be broken down as follows:

  • All the shortcodes are wrapped with the main shortcodes (plural) tag.
  • The shortcode tag wraps all the tags belonging to one, single shortcode.
  • The tag tag defines the name of the shortcode, which in this case, is the vc_tta_tabs.
  • Shortcodes can have one or more attributes; hence, we wrap them in the attributes (plural) tag and use the attribute (singular) tag to define the title of each attribute. In this case, we have the title attribute.

For shortcodes that include link attributes, you can make internal links automatically point to the translated version of that post by using the type option for the attribute. Here is an example:

Example of WPBakery page builder shortcodes that include link attributes 
<shortcode>
         <tag>vc_button</tag>
         <attributes>
            <attribute encoding="allow_html_tags">title</attribute>
            <attribute encoding="vc_link" type="link">href</attribute>
         </attributes>
</shortcode>

Testing the Language Configuration File

To test the updated language configuration file, follow these steps:

  1. Set up an installation having both WPBakery Page Builder and WPML activated. Download and activate the String Translation and Media Translation add-ons.
  2. You will need to override the remote language configuration file with the updated one. To do this, navigate to WPML → Settings page and click the Custom XML Configuration tab. Copy the content of your updated language configuration file to the editor, then click Save.
Overriding the remote language configuration file with the updated one
  1. Create a new page and add the new module(s) to it. In case you updated some attributes for existing modules, add these to the page as well. In this example, we will assume that the Call To Action module was newly added to the WPBakery Page Builder. Add it to the page and Publish.
Add the new module to the page as part of testing the language configuration file
  1. Click on the plus icon to translate the page. This will take you to the Advanced Translation Editor screen.
  2. Make sure that the module textual elements are displayed in the Advanced Translation Editor.
  3. Fill in your translations and confirm them with the green check mark. Once you’re done, click on the Complete button.
Translating textual elements as part of testing the updated language file configuration
  1. Check the translated page on the front-end.
Call to Action translation on the front-end from an updated language configuration file

The translated page shows all the translated strings, implying that the updated language configuration file is working properly.

Please note that the CSS styles for the page elements from the original language are copied to the translation language. This ensures everything will look correct between languages. If you would like to disable this feature, please see this article for instructions.

If you encounter any issues, please contact our compatibility development team. They will be happy to check issues related to the language configuration file.

Once done with the tests, please submit a merge request to our repository. Our compatibility developers will receive your request and review it.

Please note that the language configuration file hosted on our repository is for the default version of WPBakery Page Builder. In case you are updating the language configuration file of a customized version of WPBakery Page Builder, apply the changes to the configuration file inside your plugin’s root folder.

Known Issues

There are no unresolved compatibility issues between this plugin and WPML. Search all known issues.