Learn how to define translation settings for custom fields using the wpml-config.xml file. Set translation options like translate and copy, and insert additional attributes.
Setting Translation Options for Custom Fields
WPML provides four translation options for custom fields:
| Action | Description | Visible in ATE? |
| Translate | Enables the custom field value for translation | Yes |
| Copy | Copies the custom field value from the default to secondary language while keeping both in sync | No |
| Copy once | Copies the custom field value from the default to secondary language without keeping both in sync | No |
| Ignore | Avoids copying the custom field value to secondary language | No |
Example of adding custom fields to the language configuration file
<wpml-config>
<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>
</wpml-config>
Adding Attributes for Custom Fields
Label and Group Attributes
WPML lets you add attributes that appear in the Advanced Translation Editor. This includes:
- style – display single line (line), text area (textarea), or WYSIWYG (visual)
- label – displays label next to the field
- group – specifies what group the custom field belongs to. When a field is in a group:
- The field is removed from the custom field section
- The field is added to the related group’s section
Example of custom fields attributes
<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>
Here’s what these attributes will look like in the Advanced Translation Editor:
Encode Attribute
You can also add optional encode attributes to change the encoding from the default value (no encoding). Encoding attribute accepts the following values:
- json
- base64
- urlencode
If you want to use multiple encodings, separate the values with a comma:
Example of adding custom fields to the language configuration file to change the encoding
<wpml-config>
<custom-fields>
<custom-field action="translate" encoding="json,base64">keywords</custom-field>
</custom-fields>
</wpml-config>
Translate Link Attribute
If your custom field contains a link, you can use the translate_link_target attribute to force WPML to check and adjust links in the custom field.
Example of forcing WPML to adjust links in a custom field
<wpml-config>
<custom-fields>
<custom-field action="translate" translate_link_target="1">name_of_the_acf_field</custom-field>
</custom-fields>
</wpml-config>
WPML translates all sub-keys in custom fields by default. To bypass this, specify which sub-keys should be translated.
Example of code for translation of sub-keys in custom fields
<wpml-config>
<custom-fields>
<custom-field action="translate">with_attributes</custom-field>
<custom-field action="translate">with_deep_attributes</custom-field>
<custom-field action="translate">no_attributes</custom-field>
</custom-fields>
<custom-fields-texts>
<key name="with_attributes">
<key name="attribute1" />
<key name="attribute2" />
</key>
<key name="with_deep_attributes">
<key name="attribute1" />
<key name="attribute2">
<key name="level1">
<key name="level2">
</key>
</key>
</key>
</key>
</custom-fields-texts>
</wpml-config>
Wildcards
You can also use wildcards the same way as they’re used for Admin texts:
- Match all subfields starting with title- using code:
<key name="title-*" /> - Match all subfields and is generally used to match an array index using code:
<key name="*" /> - To get
[{"title":"First title"},{"title":"Second title"}]use code
Example of configuration file with wildcards
<wpml-config>
<custom-fields-texts>
<key name="key-name">
<key name="*">
<key name="title" />
</key>
</key>
</custom-fields-texts>
</wpml-config>
Automatically Converting IDs in Post Custom Fields
As of WPML 4.8, you can declare IDs located in post custom fields. WPML replaces the IDs with their translated versions on the frontend.
You can only do this when the translation option is Copy (that is, when using <custom-field action="copy">).
In custom-fields of your wpml-config.xml file, use:
- type to state what object is reference, i.e. post-ids
- sub-type (optional) when you want to declare the slug of a post type
WPML can detect and convert IDs in these formats:
- A single ID (e.g. 123)
- A comma-separated list of IDs (e.g. “123,456,789”)
- An array (and encoded array) of IDs (e.g. [123,456,789])
Example of declaring IDs in custom fields
<custom-fields> <custom-field action="copy" type="post-ids" sub-type="product">custom_field_with_id</custom-field> </custom-fields>
When IDs are nested in the custom-fields-texts section on a sub-level, WPML will detect and convert them regardless of the field translation setting (copy, translate, etc).
Example of declaring IDs in nested custom fields
<wpml-config>
<custom-fields-texts>
<key name="custom_field_with_nested_ids">
<key name="custom_field_nested_key_with_ids" type="post-ids" sub-type="product" />
<key name="custom_field_nested_key_with_ids_with_wildcard_*" type="post-ids" sub-type="product" />
<key name="custom_field_nested_key_with_subkey">
<key name="custom_field_nested_key_with_subkey_with_ids" type="post-ids" sub-type="product" />
</key>
</key>
</custom-fields-texts>
</wpml-config>
Using the same type and sub-type syntax, you can declare IDs in admin texts (wp_options table).
Setting Translation Options for Custom Taxonomy Term Fields
To translate custom fields of taxonomy terms, you need to specify the field name and the action WPML should take: translate, copy, copy-once, ignore.
Nest this markup under the wpml-config tag.
You can set the following translation options for custom term fields:
- translate: allows your user to translate the value of the custom term. These terms appear on the Translation Editor screen and can be translated manually or automatically or sent to other translators.
- copy: copies the custom term value of the default language to the secondary languages. This means that updating the custom term value of the default language will always be copied to the secondary language. The custom terms set to copy do not show on the Translation Editor screen.
- copy-once: copies the value of the custom term to the secondary language in the initial translation process. The custom terms that use the copy-once action will not appear on the Translation Editor screen. However, the user can change the custom term value of the secondary language to be different from the default language using the post editing screen.
- ignore: eliminates the custom term from being copied to the secondary language.
Example of adding custom terms to the language configuration file
<wpml-config>
<custom-term-fields>
<custom-term-field action="copy">term_meta_A</custom-term-field>
<custom-term-field action="translate">term_meta_B</custom-term-field>
<custom-term-field action="ignore">term_meta_C</custom-term-field>
<custom-term-field action="copy-once">term_meta_D</custom-term-field>
</custom-term-fields>
</wpml-config>
Automatically Converting IDs Stored in Taxonomy Terms Custom Fields
You can do this only when the field is set to Copy (that is, when using <custom-term-field action="copy">).
Just like with custom post fields, you can declare object IDs held in taxonomy custom fields. WPML then automatically converts them to their translated versions.
In the custom-term-fields section, use:
- type to state what object is reference, i.e. post-ids or taxonomy-ids
- sub-type (optional) when you want to declare the specific entity
Example of declaring IDs in custom term fields
<wpml-config>
<custom-term-fields>
<custom-term-field action="copy" type="post-ids" sub-type="product">custom_term_field_with_id</custom-term-field>
</custom-term-fields>
</wpml-config>
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:
- Translate Custom Shortcodes with WPML
- Register Page Builder Content for Translation
- Register Custom Page Builder Widgets for Translation
- Register Custom Terms, Types & Taxonomies as Translatable
- Make Custom Gutenberg Blocks Translatable
- Translate Texts that Theme and Plugins Save in wp_options
- Customize WPML Language Switcher Using WPML Configuration File