Home » Documentation » Developers Information » Language Configuration Files

Language Configuration Files

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.

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 one WPML configuration setting can be configured to be translated in this configuration file:

1. Custom fields – the custom field name needs to be provided and also the action that WPML is expected to take: translate, copy, 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="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.

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

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

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

5. 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).

e.g.

<language-switcher-settings>
 <key name="icl_lang_sel_config">
  <key name="font-current-normal">#444444</key>
  <key name="font-current-hover">#000000</key>
  <key name="background-current-normal">#ffffff</key>
  <key name="background-current-hover">#eeeeee</key>
  <key name="font-other-normal">#444444</key>
  <key name="font-other-hover">#000000</key>
  <key name="background-other-normal">#ffffff</key>
  <key name="background-other-hover">#eeeeee</key>
  <key name="border">#cdcdcd</key>
 </key>
 <key name="icl_lang_sel_footer_config">
  <key name="font-current-normal">#444444</key>
  <key name="font-current-hover">#000000</key>
  <key name="background-current-normal">#ffffff</key>
  <key name="background-current-hover">#eeeeee</key>
  <key name="font-other-normal">#444444</key>
  <key name="font-other-hover">#000000</key>
  <key name="background-other-normal">#ffffff</key>
  <key name="background-other-hover">#eeeeee</key>
  <key name="border">#cdcdcd</key>
 </key>
 <key name="icl_language_switcher_sidebar">0</key>
 <key name="icl_widget_title_show">0</key>
 <key name="icl_lang_sel_type">dropdown</key>
 <key name="icl_lso_link_empty">0</key>
 <key name="icl_lso_flags">0</key>
 <key name="icl_lso_native_lang">1</key>
 <key name="icl_lso_display_lang">1</key>
 <key name="icl_lang_sel_footer">0</key>
 <key name="icl_post_availability">0</key>
 <key name="icl_post_availability_position">below</key>
 <key name="icl_post_availability_text">This post is also available in: %s</key>
</language-switcher-settings>

As of version 2.9 it’s possible to use the * as a wildcard character for key names.
e.g. <key name=”some_option_*”>

This will match some_option_1, some_option_2, some_option_abc etc.


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.

queries in 0.391 seconds.