Configure WPML Compatibility With WordPress Themes and Plugins – Settings and Custom wpml-config.xml

This page exists for the rest: less-popular themes and plugins, very recent releases where the author shipped before WPML’s compatibility caught up, and a small number of generic helpers for sites that hit specific symptoms. Most clients never come here. When you do, it’s usually because WPML Support has pointed you at a specific toggle or to a wpml-config.xml to paste.

Two Settings sub-pages cover compatibility, and this page covers both. Settings > Compatibility holds the toggles for common symptoms. Settings > Custom XML Configuration is where you write your own wpml-config.xml – described in the second half of this page. The UI for the most-common defaults (per-post-type, per-taxonomy, per-field translation preferences) lives on a separate Settings page covered in What gets translated – and what doesn’t; most clients use that UI and only come here when it doesn’t reach what they need.

Compatibility Toggles

Open WPML > Settings > Compatibility. The page has four cards. Each card targets a specific class of compatibility problem.

Localization Options – For Themes and Plugins Whose Translations Don’t Load

When a theme or plugin already includes its own UI translations (.mo files in a /languages/ folder) but those translations don’t show up on your site, the Localization options card has three toggles that help WPML find and apply them.

• Automatically load the theme’s .mo file using load_textdomain. Forces WPML to call load_textdomain() for the theme’s text domain. Use when the theme’s translations are sitting on disk but not appearing.
• Enter textdomain. Override the auto-detected text domain. Some themes register their text domain in non-standard ways; this field lets you specify it explicitly.
• Use theme or plugin text domains when gettext calls do not use a string literal. A compatibility flag for themes/plugins that use __() calls with variable arguments instead of literal strings. WPML can’t auto-detect these, and this toggle helps it apply translations anyway.

If WPML Support directs you here, they’ll tell you which toggle and which textdomain to set.

Make Themes Work Multilingual

Adjust IDs for multilingual functionality. A compatibility layer for themes that hard-code single-language assumptions (e.g., a theme that stores a “featured image ID” once and uses the same image across every language).

Most modern WPML-compatible themes don’t need this. Older or less-WPML-aware themes sometimes do. Turn it on if you see content references (images, menus, featured items) leaking across languages incorrectly.

Language Filtering for AJAX Operations

Store a language cookie to support language filtering for AJAX. Some plugins use AJAX to fetch content: filtered product listings, AJAX-paginated post lists, search-as-you-type results. Without a language cookie, the AJAX endpoint doesn’t know which language to respond in and returns wrong-language results.

Turn the cookie on if you see this symptom: visitors on the French page get English results from AJAX-loaded sections. It’s a one-checkbox fix for an entire class of bugs.

Login and Registration Pages

Allow translating the login and registration pages. WordPress’s built-in /wp-login.php and the registration screen aren’t part of the regular content WPML translates. They live outside the theme’s template chain. This toggle adds them to WPML’s set of translatable pages.

If your site runs on nginx, the toggle also requires a server-config tweak. The page links to WPML’s nginx guide with the exact configuration block.

Theme and Plugin Texts – Settings Here, Scanner Elsewhere

Two kinds of theme/plugin string work split across two screens:

• The settings on this page. They handle compatibility for translations the theme/plugin already includes: load_textdomain, textdomain override, non-literal gettext.
• The scanner is its own screen. When you need to find theme and plugin strings that aren’t yet registered for translation, use the Admin Texts Translation screen. It’s reached from the Strings tab in Translations under the “not seeing strings you are looking for?” section.

For the full string-scanning workflow, see Translating strings.

Custom wpml-config.xml

WPML-compatible themes and plugins ship a wpml-config.xml file that tells WPML exactly which of their fields, post types, taxonomies, shortcodes, and meta keys should be translatable. WPML reads it on activation. For every major and popular theme and plugin, this means translation works correctly out of the box. You don’t need to do anything.

When the wpml-config.xml that ships with a theme or plugin isn’t enough for your site, you write your own. WPML applies it on top of whatever the theme or plugin ships.

When You’d Write Your Own wpml-config.xml

Three scenarios.

• A field you need translated isn’t in the shipped wpml-config.xml. The author of the theme or plugin didn’t declare a custom field as translatable, but you need it translated on your site.
• A field has the wrong default. The shipped wpml-config.xml marks something as Copy and you want Translate, or vice versa.
• You’re building a custom theme or plugin and you want to declare its translation behavior from WPML’s Settings page instead of bundling a wpml-config.xml file with your code.

In every case, WPML Support may direct you here with the exact wpml-config.xml to paste. Mostly it’s a Support-driven action, occasionally a developer-driven one.

Why Edit wpml-config.xml in WPML’s Admin Instead of in the Theme File

You could edit the theme or plugin’s own wpml-config.xml directly. But that change gets lost the next time the theme or plugin updates. WPML’s in-admin editor at WPML > Settings > Custom XML Configuration layers your wpml-config.xml on top of whatever the theme or plugin ships, and survives updates. It’s the right place for site-specific tweaks.

The Shape of a wpml-config.xml

The page is an XML editor. Paste a <wpml-config>...</wpml-config> block, save, and WPML applies your wpml-config.xml.

A minimal wpml-config.xml declaring a shortcode as translatable:

<wpml-config>
  <shortcodes>
    <shortcode>
      <tag>add_to_cart_link</tag>
    </shortcode>
  </shortcodes>
</wpml-config>

The element types you’d typically declare:

• <custom-fields>. Mark a custom field as translate, copy, copy-once, or nothing.
• <custom-types>. Declare a custom post type as translatable.
• <taxonomies>. Declare a custom taxonomy as translatable.
• <shortcodes>. List shortcodes whose content WPML should translate.
• <custom-term-fields>. For term metadata.

Each element has its own attributes (e.g., action="translate" on a custom field). For the complete wpml-config.xml reference (every element, every attribute, every allowed value), see the WPML Developer Information.

A Practical Workflow

If WPML Support gives you a wpml-config.xml block to paste:

1. Open WPML > Settings > Custom XML Configuration.
2. Paste their XML inside the existing <wpml-config> block (or replace the contents if they’ve given you the full block).
3. Save.
4. WPML applies your wpml-config.xml immediately. If it declares a new translatable post type or field, the entry appears in Settings > Post Types Translation / Custom Fields Translation right away.

If you’re building a custom theme or plugin and want to ship its WPML configuration with the code, you’d put the same <wpml-config> block into a wpml-config.xml file at the root of your theme or plugin instead. WPML reads it on activation. The in-admin editor is for site-specific tweaks; the bundled file is for the theme/plugin’s own defaults.