Skip Navigation
Home » WPML Documentation » Developers Information » WPML Language Configuration File » Register Page Builder Content for Translation

Register Page Builder Content for Translation

Tomer Helzer
Updated
October 17, 2024

WPML lets you register custom page builder content for translation by configuring their settings in the wpml-config.xml file. This includes strings, media, page builder widgets, and shortcode IDs.

This guide is for developers. If you use a third-party page builder compatible with WPML read our page about translating content created with page builder.

Need to generate a wpml-config.xml file? Visit our step-by-step guide for automatically generating a configuration file using the Multilingual Tools plugin.

Translate Strings

Let’s consider an example where you have a text separator added to a page using Visual Composer. That separator has a title, and its shortcode looks like this:

[vc_text_separator title="Separator Title"]

In order to translate this text separator’s title, you need to add a few lines to your wpml-config.xml file. This way, WPML will “know” that the title of that separator needs translation.

The following code is an example of what you need to add to the wpml-config.xml file in this case.

Example of adding a page builder shortcode to the wpml-config.xml file 
<wpml-config>
  <shortcodes>
    <shortcode>
        <tag>vc_text_separator</tag>
        <attributes>
            <attribute>title</attribute>
        </attributes>
    </shortcode>
  </shortcodes>
</wpml-config>

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

  • Start with the shortcodes tag. Any shortcodes in your site that need to be translated should be put under this tag.
  • Use the shortcode tag to wrap all the tags belonging to one, single shortcode.
  • Use the tag called tag to define the name of the shortcode. In this case, it is the vc_text_separator. If you prefer, you can add optional custom labels to tags. These labels will display next to the text in both the Advanced Translation Editor and Classic Translation Editor. Exported XLIFF files also include these labels. See the example below for how to add labels to tags and attributes.
  • Shortcodes can have one or more attributes, so you need to wrap them in the attributes (plural) tag and use the attribute (singular) tag to define the title of each attribute.

Page builders (sometimes) include design elements that have link attributes.

You can make internal links automatically point to the translated version of that post using the link option: type=”link”.

You can use the encoding attribute with this one. It handles special encoding that various page builders use. The encoding attribute is usually specific to the page builder you use. It accepts the following values:

  • base64 – Visual Composer raw HTML shortcode. Shortcode stores the HTML as a base64 string.
  • vc_link – Special link formatting for Visual Composer.
  • av_link – Special link formatting for Enfold.
  • allow_html_tags – Usually HTML tags are stripped out of shortcode attributes. Set encoding to allow_html_tags if the shortcode attribute should allow HTML tags. Use this with caution as allowing HTML tags in some situations can mess up the formatting and could be a security issue.
Example of adding shortcode link attribute: type=”link” 
<wpml-config>
  <shortcodes>
    <shortcode>
            <tag>av_button</tag>
            <attributes>
                <attribute>label</attribute>
                <attribute type="link" encoding="av_link">link</attribute>
            </attributes>
    </shortcode>
  </shortcodes>
</wpml-config>

If you are thinking about using urlencoded shortcodes, make sure to read the page about Translating urlencoded shortcodes.

Example of adding tag and attribute labels 
<wpml-config>
    <shortcodes>
        <shortcode>
            <tag label="My shortcode label">my_shortcode</tag>
            <attributes>
                <attribute label="Shortcode title">title</attribute>
            </attributes>
        </shortcode>
    </shortcodes>
</wpml-config>

Adding labels to tags and attributes allows you to display custom labels in the Advanced Translation Editor or Classic Translation Editor. This can help the translator better understand the context of the string.

Shortcode label in the Advanced Translation Editor
Translating custom shortcode labels in the Advanced Translation Editor

Translate Media

You can use WPML Media Translation to use different images for different languages in page builder content. This is done by converting image IDs and image URLs. You must “tell” the page builder that uses shortcodes how to do this conversion. The following code is an example of what you need to add to the wpml-config.xml file in this case.

Example of adding a page builder shortcode to the wpml-config.xml file for image translation 
<wpml-config>
  <shortcodes>
    <shortcode>
        <!-- Convert media IDs in `gallery_ids` attribute, and ignore the shortcode content -->
        <tag ignore-content="1">et_pb_gallery</tag>
        <attributes>
          <attribute type="media-ids">gallery_ids</attribute>
        <attributes>
    </shortcode>
    <shortcode>
        <!-- Convert the media URL in the content, translate some string attributes for `title` and `alt`, convert media URL in `src` attribute -->
        <tag type="media-url">et_pb_image</tag>
        <attributes>
          <attribute>title_text</attribute>
          <attribute>alt</attribute>
          <attribute type="media-url">src</attribute>
        </attributes>
    </shortcode>
  </shortcodes>
</wpml-config>

You can use the following values:

  • ignore-content – You can use it within a tag element. This value is optional and it can be either 0 or 1.  You can use this attribute to achieve backward compatibility for new media shortcodes.  If the value is set to 1 the shortcode content will not be processed.
  • type – You can use it within a tag element. You can also use shortcode content that contains media URL as the optional value within media-url.
  • type – You can also us it within an attribute element. In this case, it can have one of the following optional values:
    • media-ids –  a comma-separated list of media IDs.
    • media-url – URL of media
    • link – points to another page on the site and WPML will automatically convert it to the URL of the translated page

Translate Page Builder Widgets

WPML allows you to register page builder widgets within your language configuration file. For detailed information see our documentation page on how to register page builder widgets for translation.

Automatically Convert Shortcode IDs

As of WPML 4.5.9, you can declare the IDs of posts or taxonomy terms located in shortcode attributes. These IDs can then be converted automatically on your site’s front-end.

For example, consider the following shortcode:

[foo_product_list product_ids="12,34,56"]

You can declare that the product_ids attribute is holding post IDs with the following configuration:

Declaring that the product_ids attribute is holding post IDs 
<shortcode>
    <tag ignore-content="1">foo_product_list</tag>
    <attributes>
        <attribute type="post-ids" sub-type="product">product</attribute>
    </attributes>
</shortcode>

On the front-end, the shortcode automatically converts to:

[foo_product_list product_ids="13,35,57"]

You can use the following configuration attributes:

  • type – either post-ids or taxonomy-ids
  • sub-type (optional) – a specific entity of the type if it’s already known. For instance, product for the Product custom post type coming from WooCommerce. If it’s not defined, the specific entity will be guessed.

The ID conversion is versatile and tries to adapt to most possible formats of IDs (single ID, list of IDs, serialized array, JSON encoded array).

Additional Resources

To learn more about the wpml-config.xml file, visit the Language Configuration Files guide.

For customizing other elements using the wpml-config.xml file, visit our additional guides: