WPML can read a configuration file that tells it what needs translation in themes and plugins. The file is named wpml-config.xml and it’s placed in the root folder of the plugin or theme.

Purpose

As part of achieving compatibility with WPML, you should also create a configuration file that will help you maintaining compatibility in your future releases. WPML can translate anything in your WordPress site, but you need to tell it what needs translation. This file does that.

Starting with WPML 2.0, you’ll find a Multilingual content setup admin page:

Multilingual content setup screen

This page tells WPML everything it needs to know, including which custom fields to translate or synchronize, which custom post and taxonomies should be multilingual and even which admin texts to translate.

The language configuration file includes this information, so that each and every user doesn’t need to manually enter it in the admin page.

Generating the wpml-config.xml file automatically

If you are not familiar with creating XML files, our team has created the Multilingual Tools plugin that makes this task easier. Although it was initially conceived as a tool for helping theme and plugin authors to make their products multilingual-ready, it can easily be used to generate your own wpml-config.xml file.

To learn more about generating your wpml-config.xml file, visit the Multilingual Tools plugin’s page. Specifically, look under the How do I generate language configuration files using Multilingual Tools? section.

Once you have the configuration file, add it to the root of your theme’s folder. If you already have one, do not overwrite it. Instead, edit your original XML file and add the code generated with the Multilingual Tools plugin.

Please note that this plugin is not intended to be used on the live, production sites.

Example

To read this tutorial and build language configuration files for your themes and plugins, you can start with this example one – wpml-config.zip.

You’ll need to edit it, but you can use the sections and structure of this file.

Structure and Syntax

The content of the wpml-config.xml file has to be wrapped into these tags

<wpml-config>

and

</wpml-config>

Currently, four types of data and two WPML configuration setting can be configured to be translated in this configuration file:

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

1. Page builder content

– since version 3.6.0, WPML allows you to use the wpml-config.xml file to define shortcodes that need to be added to content translation.

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

[vc_text_separator title="Separator Title"]

In order to translate this text separator’s title, we need to add a few lines to our wpml-config.xml file. This way, WPML will “know” that the title of that separator needs translation. This actually follows the very same logic as the one used for the custom post types, custom fields, and others.

The following code is an example what we 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
<shortcodes>
        <shortcode>
            <tag>vc_text_separator</tag>
            <attributes>
                <attribute>title</attribute>
            </attributes>
        </shortcode>
</shortcodes>
  • 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.
  • Then use the shortcode tag to wrap all the tags belonging to one, single shortcode.
  • The tag called tag is used to define the name of the shortcode. In this case it is the vc_text_separator.
  • Shortcodes can have one or more attributes, so we wrap them in the attributes (plural) tag and use the attribute (singular) tag to define the title of each attribute.

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

From WPML version 3.7 you can make internal links automatically point to the translated version of that post using the wpml-config.xml file new shortcode link attribute: type=”link”.

Example of adding shortcode link attribute: type=”link”
<shortcode>
            <tag>av_button</tag>
            <attributes>
                <attribute>label</attribute>
                <attribute type="link" encoding="av_link">link</attribute>
            </attributes>
</shortcode>

2. Custom fields

– the custom field name needs to be provided and also the action that WPML is expected to take: translate, copy, copy-once, ignore.

e.g.

<custom-fields>
 <custom-field action="copy">quantity</custom-field>
 <custom-field action="translate">custom-title</custom-field>
 <custom-field action="copy">weight</custom-field>
 <custom-field action="copy-once">bg-color</custom-field>
 <custom-field action="translate">custom-description</custom-field>
 <custom-field action="ignore">date-added</custom-field>
</custom-fields>

This block will have to be nested under the <wpml-config> tag.

You can set the following translation options for custom fields:

  • translate: allows your user to translate the value of the custom field. These fields are displayed on the Translation Editor screen and can be sent to any of the professional translation services.
  • copy: this action copies the custom field value of the default language to the secondary languages. This means that updating the custom field value of the default language will always be copied to the secondary language. The custom fields set to copy do not show on the Translation Editor screen.
  • copy-once: The value of the custom field is copied to the secondary language in the initial translation process. The custom fields that use the copy-once action will not appear on the Translation Editor screen. However, the user can change the custom field value of the secondary language to be different from the default language using the post editing screen.It is preferred to set the custom fields that hold settings like background color, font color, font size, and others, to copy-once. This allows the user to have different settings for translated content than the ones set for the posts and pages in the default language. For example, the user wants to set the background color of the same element to be yellow in the default language and blue in the secondary language.

    Please note that editing a field set to copy-once will not mark the field as needs update. This is because the field will not be copied to an existing translation, it is only copied when the translation is created.

  • ignore: this action eliminates the custom field from being copied to the secondary language.

Since WPML 3.4.0, we have added new attributes to <custom-field> tags. These attributes customize the instruction texts in WPML Translation Management Editor.

  • style can be line, textarea or visual, for displaying single line, text area, or WYSIWYG respectively.
  • label is displayed next to the field.
  • group specifies if the custom field belongs to a group and what the label of the group should be. When a field is in a group:

* the field is removed from the custom field section

* the field is added to a the related group’s section

Let’s take a look at the following example.

<wpml-config>
 <custom-fields>
 <custom-field action="translate" style="line" label="Title">custom-title</custom-field>
 <custom-field action="translate" style="textarea" label="Description">custom-description</custom-field>
 <custom-field action="translate" style="visual" label="Some content" group="Custom group">custom-wysiwyg</custom-field>
 </custom-fields>
</wpml-config>    

When this wpml-config.xml content is used, these custom fields are displayed in WPML Translation Management Editor, as shown in the following image.

custom-field-attributes

3. Custom types

– the custom post types that WPML should translate.

e.g.

<custom-types>
 <custom-type translate="1">book</custom-type>
 <custom-type translate="1">DVD</custom-type>
</custom-types>

4. Custom taxonomies

– the custom taxonomies that your plugin might be using and that are already registered with WP.

e.g.

<taxonomies>
 <taxonomy translate="1">genre</taxonomy>
 <taxonomy translate="1">type</taxonomy>
 <taxonomy translate="0">publisher</taxonomy>
</taxonomies>

Note: the taxonomies that don’t need translation can simple be omitted from this list.

5. Admin texts / wp_options

strings that are part of the options that the plugins or themes save in the wp_options table.

When themes and plugins use get_option, they read values from the wp_options table. WPML can filter these calls and provide translation to the values of these options.

This works if the wp_option record is a simple string but also when it’s a serialized array.

To translate a single option, add a key entry under admin-texts. To translate a serialized array, add several keys under a key, like you can see in my_plugin_options in the example below.

e.g.

<admin-texts>
 <key name="my_plugins_options">
  <key name="option_name_1" />
  <key name="option_name_2" />
  <key name="options_group_1">
   <key name="sub_option_name_11" />
   <key name="sub_option_name_12" />
  </key>
  <key name="options_group_2">
   <key name="sub_option_name_21" />
   <key name="sub_option_name_22" />
  </key>
 </key>
 <key name="simple_string_option"/>
</admin-texts>

It’s possible to use the wildcard * in sub-keys like the following case.

<admin-texts>
  <key name="testing_option">
    <key name="*"/>
  </key>
</admin_texts>

It’s equal to this code:

<admin-texts>
  <key name="testing_option">
    <key name="sub_key_1"/>
    <key name="sub_key_2">
      <key name="sub_sub_21">
        <key name="sub_sub_211"/> 
      </key> 
      <key name="sub_sub_21"/>
    </key>
    <key name="more_sub_keys"/>
  </key>
</admin_texts>

Please note that the wildcard * does NOT work in parent keys like this:

<admin-texts>
  <key name="some_option_*" />
  <key name="*"/>
</admin_texts>

6. Language switcher configuration

– enables a specific configuration for the WPML built-in language switcher. It can also be used for resetting the language switcher configuration if it was changed from the backend (from its initial values).

To see new changes, make sure to click the Restore default button on the bottom of the WPML -> Languages page.

Example of adding custom configuration for the built-in WPML language swithcer
<language-switcher-settings>
    <key name="additional_css">{inline CSS styles}</key>
    <key name="link_empty">{0 or 1}</key>
    <key name="copy_parameters">{parameter1, parameter2}</key>
    <key name="sidebars">
        <key name="{sidebar slug}">
            <key name="display_flags">{0 or 1}</key>
            <key name="display_names_in_current_lang">{0 or 1}</key>
            <key name="display_names_in_native_lang">{0 or 1}</key>
            <key name="display_link_for_current_lang">{0 or 1}</key>
            <key name="widget_title">{widget title}</key>
            <key name="template">{template slug}</key>
            <!-- color picker keys -->
            <key name="background_normal">#{hex color}</key>
            <key name="border_normal">#{hex color}</key>
            <key name="font_current_normal">#{hex color}</key>
            <key name="font_current_hover">#{hex color}</key>
            <key name="background_current_normal">#{hex color}</key>
            <key name="background_current_hover">#{hex color}</key>
            <key name="font_other_normal">#{hex color}</key>
            <key name="font_other_hover">#{hex color}</key>
            <key name="background_other_normal">#{hex color}</key>
            <key name="background_other_hover">#{hex color}</key>
        </key>
    </key>
    <key name="statics">
        <key name="footer">
            <key name="show">{0 or 1}</key>
            <key name="display_flags">{0 or 1}</key>
            <key name="display_names_in_current_lang">{0 or 1}</key>
            <key name="display_names_in_native_lang">{0 or 1}</key>
            <key name="display_link_for_current_lang">{0 or 1}</key>
            <key name="template">{template slug}</key>
            <!-- color picker keys -->
            <key name="background_normal">#{hex color}</key>
            <key name="border_normal">#{hex color}</key>
            <key name="font_current_normal">#{hex color}</key>
            <key name="font_current_hover">#{hex color}</key>
            <key name="background_current_normal">#{hex color}</key>
            <key name="background_current_hover">#{hex color}</key>
            <key name="font_other_normal">#{hex color}</key>
            <key name="font_other_hover">#{hex color}</key>
            <key name="background_other_normal">#{hex color}</key>
            <key name="background_other_hover">#{hex color}</key>
        </key>
        <key name="post_translations">
            <key name="show">{0 or 1}</key>
            <key name="display_flags">{0 or 1}</key>
            <key name="display_names_in_current_lang">{0 or 1}</key>
            <key name="display_names_in_native_lang">{0 or 1}</key>
            <key name="display_link_for_current_lang">{0 or 1}</key>
            <key name="display_before_content">{0 or 1}</key>
            <key name="display_after_content">{0 or 1}</key>
            <key name="template">{template slug}</key>
            <key name="availability_text">{string like "See post translations: %s"}</key>
        </key>
        <key name="shortcode_actions">
            <key name="display_flags">{0 or 1}</key>
            <key name="display_names_in_current_lang">{0 or 1}</key>
            <key name="display_names_in_native_lang">{0 or 1}</key>
            <key name="display_link_for_current_lang">{0 or 1}</key>
            <key name="template">{template slug}</key>
            <!-- color picker keys -->
            <key name="background_normal">#{hex color}</key>
            <key name="border_normal">#{hex color}</key>
            <key name="font_current_normal">#{hex color}</key>
            <key name="font_current_hover">#{hex color}</key>
            <key name="background_current_normal">#{hex color}</key>
            <key name="background_current_hover">#{hex color}</key>
            <key name="font_other_normal">#{hex color}</key>
            <key name="font_other_hover">#{hex color}</key>
            <key name="background_other_normal">#{hex color}</key>
            <key name="background_other_hover">#{hex color}</key>
        </key>
    </key>
</language-switcher-settings>

 


Not all of these 5 sections have to be present in the configuration file but just the ones that apply to your plugin or theme.

Note* – When using a parent child theme the wpml-config.xml file of the parent theme will need to be renamed or deleted and the wpml-config.xml file of the child’s theme will be taken into affect.