WPML lets you define and set translation settings for custom fields coming from your custom theme or plugin, using the wpml-config.xml file. This includes defining translation options (translate, copy, ignore, e.g.), inserting additional attributes, and adjusting links.
This guide is for developers who create their own themes and plugins. If you’re using a third-party plugin or theme, read our page about translating custom fields.
Need to generate a wpml-config.xml file? Visit our step-by-step guide for automatically generating a configuration file using the Multilingual Tools plugin.
Setting Options for Custom Fields
You need to provide the custom field names and the action that WPML should take: translate, copy, copy-once, ignore. You also need to nest this markup under the wpml-config tag as shown in the following example.
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>
You can set the following translation options for custom fields:
- translate: allows your user to translate the value of the custom field. Such fields will be displayed on the Translation Editor screen and can be translated automatically or sent to other translators.
- copy: copies the custom field value from 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: copies the value of the custom field 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. For example, you’d usually want 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. 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: eliminates the custom field from being copied to the secondary language.
You can add attributes to the custom-field tags. These attributes customize the instruction texts in the Advanced Translation Editor or Classic Translation 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 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>
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
This attribute allows you to use multiple encodings. In that case, you must separate the values with a comma, e.g. encoding="json,base64".
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>
The following image displays how custom fields look in the Advanced Translation Editor or Classic Translation Editor after using code similar to the ones above.
Advanced Translation Editor
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. It is possible to bypass such behavior by specifying 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>
It is also possible to use wildcards the same way as they are 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>
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