How to Translate ACF Custom Fields in WordPress – Field Groups, Repeaters, Options Pages

Before You Start

Install and activate these plugins:

• Advanced Custom Fields or ACF Pro.
• WPML and WPML String Translation.
• ACFML (the add-on this page covers).

Your Field Groups should already be configured in ACF. You can change the per-field translation preferences after the fact, so the order of operations doesn’t matter. Set up the Field Groups, then come back to ACFML.

Pick a Translation Mode for Each Field Group

ACF Field Groups don’t all behave the same way under translation. ACFML offers three modes per Field Group, set inside ACF > Field Groups under the Multilingual Setup section:

Same Fields Across Languages

The typical setting for most ACF sites. Translate the field values into each language while the structure stays the same. The Our Team page is the canonical example. Your team is the same in every language, so each team member’s name and bio translate per language while the field structure stays intact. You enter the team in the source language, then send the post for translation through WPML > Translations > Dashboard; the translated values come back attached to the same fields.

Different Fields Across Languages

Use when each language shows fundamentally different content in the same Field Group. The classic case is a company running localized events. The English Events page shows English-audience events, the French page shows French-audience events. Set the Field Group to Different fields across languages, then open the post you want to localize > in the right-hand Languages box, click the plus icon for the target language > a blank draft opens with empty custom fields > fill in the language-specific values and publish.

Expert Mode

Use when you need a mix: some fields translate per language, others stay the same, others copy once and then diverge. Pick Expert Mode in the Field Group setup and set the preference per field. The Events example with mixed behavior: title and description set to Translate; price, date, and address set to Copy.

Translation Preferences for Each ACF Field Type

Every field in a Field Group has one of four translation preferences:

• Translate. The field’s value translates per language.
• Copy. The field’s value stays in sync across languages; edit it once and it propagates.
• Copy Once. The field’s value seeds the translation, then each language version can be edited independently.
• Don’t translate. The field is ignored by the translation pass.

When you pick Same fields across languages or Different fields across languages, each field gets a sensible default preference based on its field type. The tables below show those defaults. Use Expert Mode to override them per field, or use the acfml_field_group_mode_field_translation_preference filter to override the default for a field type site-wide (see Developer hooks for edge cases below).

Repeater and Flexible Content – Copy or Copy Once

For Repeater and Flexible Content fields, you choose between two row-level behaviors before the sub-field preferences kick in:

• Copy. Same layout and number of rows in every language. Translators see the same rows; sub-fields translate per their own preferences.
• Copy Once. Each language can have a different layout and a different number of rows after the initial seed.

Pick Copy when the structure is the same across languages (most cases). Pick Copy Once when the language versions diverge structurally (e.g., a different event list per language).

Basic Fields

Content Fields

Choice Fields

jQuery Fields

Layout Fields

Relational Fields

Setting Preferences for Fields Registered in PHP or JSON

ACF Field Groups registered in PHP (via acf_add_local_field_group()) or through ACF’s Local JSON feature don’t pick up translation preferences from the admin UI, because the admin doesn’t manage them. Set the preferences in the same place you register the fields.

For each field in the field-group definition, add a wpml_cf_preferences key. The value is an integer that maps to the four translation preferences: 0 for Don’t translate (WPML ignores the field), 1 for Copy (the value stays in sync across languages), 2 for Translate (the value goes through translation), and 3 for Copy once (the value copies to new translations, then each language can be edited independently).

A minimal example:

acf_add_local_field_group( [
    'key'    => 'group_1',
    'title'  => 'My Group',
    'fields' => [
        [
            'key'                 => 'field_1',
            'label'               => 'Sub Title',
            'name'                => 'sub_title',
            'type'                => 'text',
            'wpml_cf_preferences' => 2, // Translate.
        ],
    ],
    // ...rest of the field-group config
] );

After you define the fields in code, sync the preferences into WPML so the admin recognizes them:

1. Go to ACF > Tools.
2. Scroll to Translate ACF Local JSON and PHP-Registered Fields.
3. In Sync Translation Preferences for Local Fields, pick Sync once now and click Apply.

WPML reads the preferences from your PHP definitions and stores them. The sync runs once when you trigger it, not on every page load.

If you use ACF’s Local JSON feature to share field groups between sites, ACFML writes the translation preferences into the JSON files automatically. Export a JSON file from one site, import it on another, and the destination site picks up the preferences once ACFML is active on both ends.

Translate ACF Field Labels

ACF field labels are the names that identify each custom field in the WordPress editor and on the front-end (e.g., Phone number, Address). They translate separately from the field values, and they live in WPML String Translation, not in the post’s translation job.

To send field labels for translation:

1. Open WPML > Translations > Dashboard.
2. Expand the ACF Field Group section.
3. Select the Field Group Labels item for the Field Group you want to translate.
4. Pick a translation method (PTC, your translator, or Translate myself) and send.

The translated labels appear on the front-end automatically once the translation completes.

Translate ACF Field Choices

Choice fields (Select, Checkbox, Radio Button, Button Group) carry their own option labels (e.g., Small / Medium / Large). These also live alongside the field labels rather than inside the post translation. Send them the same way:

1. Open WPML > Translations > Dashboard.
2. Expand the ACF Field Group section.
3. Select the Field Group whose choice values you want to translate.
4. Pick a translation method and send.

Translate ACF Options Pages

ACF Options Pages (global settings screens like Contact details, Header settings, Footer links) translate as their own object type, separately from posts:

1. Open WPML > Translations > Dashboard.
2. Expand the ACF Options section.
3. Select the Options Page you want to translate.
4. Pick a translation method and send.

Each language’s Options Page values appear automatically when ACF reads the option in that language’s context.

Common Pitfalls

• Field labels look untranslated. They live in String Translation, not the post translation. Send the Field Group’s Field Group Labels item from the Dashboard (see Translate ACF field labels above).
• Choice values look untranslated. Same shape. Send the Field Group from the Dashboard’s ACF Field Group section so the option values get included.
• Repeater rows fall out of sync. The field is probably set to Copy Once when Copy would keep rows aligned. Open the Field Group > switch the Repeater field’s behavior to Copy.
• Conditional logic behaves unexpectedly. When the controlling field is set to Copy or Don’t translate, the conditional behavior follows the source-language value across all translations. Set the controlling field to Translate if its value should differ per language.
• Local fields (PHP-registered) ignore translation preferences set in the admin. Set the wpml_cf_preferences key in the field-group definition itself and sync from ACF > Tools. The procedure is in Setting Preferences for Fields Registered in PHP or JSON above. ACFML 2.2.0 (Feb 2026) added full Local Fields support; older versions had limitations here.

Developer Hooks for Edge Cases

For programmatic control (opt specific fields out of translation, override the default preference for a field type site-wide, hide annotations from translators, or exclude field group strings from post translation jobs), ACFML exposes two filters and four constants. The full reference with code examples lives at ACFML hooks and constants reference.