Skip Navigation
June 26, 2019

This document is intended for developers that want to translate their shortcode-based page builders using WPML. We use Visual Composer as an example, but you may use the same technique stated below to add support for any page builder that uses shortcodes.

How to obtain the WPML plugin?

First, you will need to have an account on If you do not have one yet and you are a theme or plugin developer, contact our Go Global program and receive your complimentary account and assistance.

Received your account? Next, install WPML, Translation Management, and String Translation.

WPML Downloads Page
WPML Downloads Page

* Support for translating page builders is new in WPML version 3.6.0. If you are using an older version of WPML, please update first.

How it works?

Let us create an example page using the page builder. We use Visual Composer for this example. You may use your own shortcode-based page builder.

Create a new WordPress page and design it using the builder. Include elements that have text that needs a translation. Most builders have ‘text’ elements. Other elements include text attributes, like ‘title’.

The following is an example page that we have created using Visual Composer. It uses a text cell and other different types of cells with textual attributes.

Front-end example of a page built with your page builder
Front-end example of a page built with your page builder

When we look at the source of the page (in the HTML mode), we can see the shortcodes that make up the page design and texts.

Example of the page's HTML code
Example of the page’s HTML code

Our objective is to configure WPML to find these texts in the page source.

Creating a language configuration file for your page builder

Fortunately, WPML can extract texts for translation from pages that you design with page builders (which use shortcodes). We only need to configure WPML to identify which shortcodes and attributes contain texts that require translation. We do this using a file called wpml-config.xml, which needs to be placed in the root folder of your theme or plugin.

Creating the language configuration file for your page builder
Creating the language configuration file for your page builder

This language configuration file can also be used to guide WPML on other things about your theme or plugin.

As an example, see the Visual composer language configuration file that we have created:


There is an entry for every shortcode that you want WPML to identify. Therein, there is an entry for attributes that contain text.

An important note about mixed content

You can use these settings for non-page builders purpose, but the post must have no mixed content.

For instance, if in a post you have the following:

[my-short-code attr="value1"]
Some normal text
[my-other-short-code attr="value1"]

You can’t configure the first nor the second shortcode in wpml-config.xml, because “Some normal text” creates a case of “mixed content”.

But if you have in a post something like the configuration below, then, this shortcode can be configured:

[my-short-code attr="value1"]
Some normal text

In the example above, WPML extracts texts from shortcodes such as:

[vc_column_text]Some text for translation[/vc_column_text]

[vc_text_separator title=”some text for translation”]

After you create or update the wpml-config.xml file for your theme or plugin, you need to force WPML to load it. Disable the theme/plugin and enable it. WPML loads the config files when the themes and plugins are activated or updated.

Translating pages created with the page builders

Once you have created the wpml-config.xml file, you should test the translation of content created with your page builder.

Watch the following video for an overview of the translation process with the Visual Composer example.


First, you need to configure WPML to use the Translation Editor (which offers support for page builders). After you have installed the required plugin (WPML, Translation Management, String Translation) and fully configured WPML you are ready to translate.

  1. Create a WordPress page and design it with your builder. Save the page.
  2. When editing the page, click on the + icon under the language box (this creates a new translation).
Translating the example page
Starting the translation of the example page
  1. Now, you can see the translation editor screen. You should see fields for each of the texts in the page that you created. There will always be a ‘title’ field and there should be fields for each of the text elements in the page-builder design.
  2. Add your translated texts to the fields and choose the Translation is complete option.
  3. Click on the Save & Close button.
Translating your page's texts
Translating your page’s texts

In the page editor, the + icon should change to a ‘pencil’ icon, indicating that the translation is complete (and you can now edit it).

You can see the translated page by visiting the page on the front-end and switching the page’s language.

Front-end example of the translated page
Front-end example of the translated page

Let us edit the page to see how the translation works. In the admin bar, click on ‘Edit page’. Then, go to the HTML mode to see the page source.

Example of HTML code of the translated page
Example of HTML code of the translated page

Distributing your page builder with WPML support

If your page builder uses shortcodes, the only thing that you need to add to it is the wpml-config.xml file. This file does nothing if WPML is not active. It tells WPML how to translate pages created using your builder.

Need help?

You are welcome to receive help from the WPML compatibility team (use the contact you received from the Go Global program). You are free to use our general support forum as well.

We are also working on adding compatibility with page builders that do not use shortcodes. Please contact us for more details and availability of development versions.