Skip Navigation
Home » WPML Documentation » Developers Information » WPML Language Configuration File » Set Translation Options for Custom Fields Using WPML Configuration File

Set Translation Options for Custom Fields Using WPML Configuration File

Tomer Helzer
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:

ActionDescriptionVisible in ATE?
TranslateEnables the custom field value for translationYes
Copy Copies the custom field value from the default to secondary language while keeping both in syncNo
Copy onceCopies the custom field value from the default to secondary language without keeping both in syncNo
IgnoreAvoids copying the custom field value to secondary languageNo

Example of adding custom fields to the language configuration file
?
1
2
3
4
5
6
7
8
9
10
<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
?
1
2
3
4
5
6
7
<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
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
?
1
2
3
4
5
<wpml-config>
  <custom-fields>
    <custom-field action="translate" encoding="json,base64">keywords</custom-field>
  </custom-fields>
</wpml-config>

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
?
1
2
3
4
5
<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
?
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
<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
?
1
2
3
4
5
6
7
8
9
<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: