Set Translation Options for Custom Fields Using WPML Configuration File

Updated: July 22, 2024

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:

Custom fields with labels 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>

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: