How to use the wpml-config.xml file with Polylang

🎯 Objective: Learn how to create a wpml-config.xml file easily for Polylang and make your content translatable.

Context

• WPML was created before Polylang, and many plugins or themes rely on the wpml-config.xml
• Polylang supports existing wpml-config.xml files, allowing the reuse of an existing WPML configuration.
• In practice, developers make their themes and plugins compatible with WPML through this file, which allows this existing configuration to be reused directly by Polylang. As a result, making a plugin or theme compatible with WPML also makes it compatible with Polylang.
• It is also possible to create a wpml-config.xml file specifically for Polylang to make certain options or custom fields translatable and exportable for XLIFF or DeepL.

What is wpml-config.xml

Definition

An XML file used to declare what content is translatable and how translation should behave.

Important: The wpml-config.xml file may already exist in your theme or plugin. You can create it if it does not exist, or extend the existing file.

Why do you need it

The wpml-config file provides fine control over multilingual behavior and tells Polylang how to treat content and strings in your themes and plugins.

File location and setup

Where to place the config file (and loading priority)

Once created, the wpml-config.xml file can be placed in the following locations. Polylang loads them in this exact order:

1. Plugin root directory
2. Theme root directory
3. mu-plugins
4. Global folder /wp-content/polylang or PLL_LOCAL_DIR

If multiple files define the same data, the last loaded definition is applied.

Overview

The file can be placed in different locations depending on the use case. When included in a plugin or theme, it is intended for developers who want to provide multilingual support directly within their extension. 

For end users, these locations are not recommended because files may be overwritten during updates. To prevent losing a custom configuration, the /wp-content/polylang folder should always be used.

Audience	Recommended location	Why
Theme/plugin developers	Plugin Theme mu-plugins	Integrated into distributed code
End users	/wp-content/polylang	Prevents file loss during updates

Good to know

Important: The folder name is case sensitive. The folder name must be exactly polylang. Not “Polylang” or “POLYLANG”.

Technical requirements

Polylang relies on PHP’s XML parsing capabilities to read the configuration file. The PHP SimpleXML extension is required; without it, the XML file will not be read.

Important rules

The wpml-config.xml file must strictly follow XML syntax rules. Any mistake in the structure can prevent Polylang from loading the configuration.

• The file must be valid XML
• All tags must be properly closed
• Names are case-sensitive
• A single XML error can break the entire configuration

Structure and syntax of the file

The file is organized into sections that define how different types of content should behave in translations, including custom fields, post types, taxonomies, and options.

Global structure

<wpml-config>

    <custom-fields>

        <custom-field action="copy">quantity</custom-field>

        <custom-field action="translate">custom-title</custom-field>

    </custom-fields>

    <custom-types>

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

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

    </custom-types>

    <taxonomies>

        <taxonomy translate="1">genre</taxonomy>

    </taxonomies>

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

        <key name="simple_string_option" />

    </admin-texts>

</wpml-config>

Custom fields translation

This section defines how each field behaves across translations, whether it should be ignored, translated independently, or kept synchronized.

Available actions

• “ignore” → no action from Polylang
• “translate” → copied from the source post but can be modified per language
• “copy” → copied and synchronized across translations

Important: In Polylang Pro, text meta declared as translate can be exported via XLIFF and translated using services like DeepL.

Example:

<custom-fields>

    <custom-field action="translate">subtitle</custom-field>

    <custom-field action="copy">price</custom-field>

</custom-fields>

Encoding attribute

The encoding attribute has been supported since Polylang 3.8 and is used when custom fields store structured or encoded data, such as JSON. It helps Polylang correctly parse the content and extract translatable strings.

Example:

<custom-fields>

    <custom-field action="translate" encoding="json">my_builder_data</custom-field>

</custom-fields>

Wildcards

Wildcards allow targeting multiple custom fields dynamically without listing each one individually. This is especially useful when working with page builders or plugins that generate dynamic meta keys.

Example:

<custom-fields>

    <custom-field action="translate">_builder_*</custom-field>

</custom-fields>

Registering custom post types and taxonomies

Custom post types and taxonomies define custom content structures in WordPress. This section allows Polylang to manage its translations directly through the configuration file.

Registering custom post types

<custom-types>

    <custom-type translate="1">product</custom-type>

</custom-types>

Values

• 1 → managed by Polylang
• 0 → not managed

This behavior cannot be changed in Polylang settings.

Registering taxonomies

<taxonomies>

    <taxonomy translate="1">product_cat</taxonomy>

</taxonomies>

• Same behavior as custom post types
• Fully controlled by the configuration file

Registering Gutenberg blocks

This section allows you to declare which attributes within Gutenberg blocks should be translatable. Only the fields defined in the configuration file will be available for translation and export through XLIFF or DeepL.

Example

<gutenberg-blocks>

    <gutenberg-block type="my-plugin/hero">

        <key name="title" />

        <key name="description" />

    </gutenberg-block>

</gutenberg-blocks>

Important: Only the fields declared in wpml-config.xml will be translatable and exportable. Not all WPML block features are supported, depending on how blocks are registered

Additional resource

📖 Check how to make a custom Gutenberg block multilingual.

Translating plugin and theme options via admin-texts

This section allows translating texts stored in the WordPress wp_options table by themes and plugins. These values are typically global settings such as a CTA label, footer message, or email sender name. 

How it works

Polylang reads the admin-texts section and registers the specified options as translatable. This applies to both single-value options and serialized arrays containing multiple values.

Syntax

Example of a simple option

<admin-texts>

    <key name="simple_string_option" />

</admin-texts>

Example nested option

<admin-texts>

    <key name="my_plugins_options">

        <key name="option_name_1" />

    </key>

</admin-texts>

Behavior

• A single option is defined as a simple key
• Serialized array defined using nested keys

Important: After saving the plugin or theme settings again, Polylang registers the option values and makes them available for translation.

What happens in practice

• Polylang detects the values as translatable
• They appear in Polylang’s Translations screen
• You can translate them into each language
• Each language displays its own version

Additional resource

📖 Check how to translate options with a WPML config XML file. 

Best practices

• Validate your XML file before using it
• Avoid duplicate definitions across multiple files
• Keep configuration clean and focused
• Test changes in a staging environment