Translating content stored in Advanced Custom Fields requires more than translating the visible text of a post or page. A multilingual WordPress website may also contain field groups, repeater rows, Flexible Content layouts, selectable values, editor labels, and global settings stored in ACF Options Pages. Each of these can require a different treatment in WPML.
WPML documents ACFML as the integration layer for translating ACF and ACF Pro content. The practical workflow is to define how each field should behave across languages and then send the relevant content through WPML’s translation workflow. The right setting depends on whether a field contains language-dependent text, synchronized structure, initially shared content that will later diverge, or information that should be excluded from translation. Exact controls can vary with installed WPML, ACF, ACF Pro, and ACFML versions, as well as with the way fields are registered.
What ACFML Changes in the WPML Translation Workflow
The ACFML and WPML relationship
ACFML is the documented integration used for translating ACF-powered websites with WPML. It connects ACF content with the multilingual translation workflow, but not every ACF-related element is handled in exactly the same way. Values entered into posts and pages, field labels, choice values, and Options Pages are separate content categories that require separate checks.
Before starting, verify that the site has the ACF or ACF Pro, WPML, WPML String Translation, and ACFML components applicable to its configuration. This article describes documented workflow behavior, not a guarantee that every theme, page builder, custom integration, or plugin version will behave identically.
The basic translation path
Begin by reviewing the field group and deciding which fields need individual translation, synchronization, initial copying, or exclusion. For ordinary custom-field settings, WPML documents the path WPML → Settings → Custom Fields Translation. ACF-specific field groups and structures follow the ACFML workflow described for ACF content.
After configuring the preferences, send the posts or pages containing those fields through WPML’s translation workflow. Translation preferences alone do not replace the translation step. Test the result on a staging site or a representative duplicate page before applying broad changes to production, particularly when fields contain repeated rows or global values.
Before Translating: Audit Your ACF Field Groups
Classify fields by content role
A short field audit makes the later configuration more predictable. Read the purpose of every field rather than assigning one setting to an entire group automatically. A text field containing a headline, description, or call to action generally has language-dependent content. A field controlling a shared structural value may need to remain synchronized instead.
Separate the fields into practical categories:
- Language-dependent content: values that should have a separate version in each language.
- Synchronized values: information that should remain identical across languages.
- Initially shared content: values that can be copied first but may need language-specific editing later.
- Excluded content: fields that should stay outside the translation process.
Also decide whether the field group should use the same fields across languages, different fields across languages, or Expert Mode. Expert Mode is useful when one group contains both translatable text and structural or synchronized fields.
Admin-managed versus code-managed fields
Determine how each field group is managed. Fields configured through the WordPress administration screens should still be reviewed through the current ACFML and WPML controls. Fields registered through PHP or managed with Local JSON require additional validation because ordinary admin-screen preferences do not automatically cover every code-managed configuration.
For PHP-registered or Local JSON fields, define or synchronize translation preferences through the documented ACFML process and then verify the result on the actual installation. Do not assume that a setting visible for one field group applies to every code-managed field. Conditional logic, custom integrations, themes, and builders should be treated as installation-specific validation cases.
Translate, Copy, Copy Once, or Don’t Translate?
A field-by-field decision framework
WPML provides four translation preferences for custom fields. The choice should follow the role of the value, not simply its field type. A text field may need Translate in one use case, while a field with a similar technical format may need Copy or Copy Once in another.
| Preference | Use it when |
|---|---|
| Translate | The value contains language-dependent content that should be translated separately. |
| Copy | The value should remain identical and synchronized across languages. |
| Copy Once | The source value should seed translations, but later language-specific edits should be allowed. |
| Don’t translate | The field should be left out of the translation process. |
Use Translate for human-readable values that need a distinct version in each language. Use Copy when synchronization is intentional. A later change to the source value can update the copied value, so this setting is not appropriate when translators must freely maintain different versions.
Copy Once is suitable when the initial source value should be reused but the translated versions may diverge afterward. Don’t translate excludes the field from the translation process. Before changing many preferences, back up the site and database, especially if existing translations already contain language-specific edits.
Mixed field groups and Expert Mode
Some field groups contain several content roles at once. For example, one group may include translatable text, a value that must stay synchronized, and a field that should be copied only at the beginning. Applying one universal setting would not represent those different requirements.
WPML and ACFML document group-level choices such as Same fields across languages and Different fields across languages, as well as Expert Mode. Expert Mode allows preferences to be mixed within one field group. Configure each field according to its intended behavior, then review the resulting translation workflow rather than assuming that the group-level choice explains every nested value.
Translating Repeater and Flexible Content Fields
When to use Copy
For Repeater and Flexible Content fields, Copy keeps the same layout and number of rows across languages. This is appropriate when every language must preserve the same structural arrangement. The nested text fields can still have their own translation preferences, so synchronized structure does not mean that every value inside the structure must remain identical.
Think of this as two decisions. First, decide whether rows and layouts must match. Second, decide whether the content inside those rows is language-dependent. A repeated heading may be translated, while the structure containing that heading remains synchronized.
Check the translated result before production use. Confirm that the expected rows exist, that the layout is preserved, and that nested values are available to the translation workflow. A staging site or representative duplicate page is particularly useful for this test.
When to use Copy Once
Choose Copy Once when the initial Repeater or Flexible Content structure should be copied but language versions may later need different layouts or different numbers of rows. This allows the translated version to start from the source arrangement while permitting later language-specific changes.
Copy Once is therefore different from continuous structural synchronization. It should be considered when editorial requirements vary by language, such as when one version needs fewer rows or a different content arrangement. Back up the site and database before changing this behavior, and review existing translations because synchronization choices can affect later edits.
Translating ACF Field Labels and Choice Values
Field labels versus field values
ACF field labels are separate from the values entered into posts and pages. Translating a post does not necessarily translate the labels that editors see in the field group. WPML handles these labels through the relevant ACF Field Group items in the Translations dashboard.
Review the editor-facing result as well as the translated content. A field value can be correctly translated while its label remains in the original language. Conversely, translating a label does not translate values already stored in posts. Treat these as separate tasks and verify the controls available in the installed ACFML and WPML versions.
Choice labels
Choice values for Select, Checkbox, Radio Button, and Button Group fields are also handled separately from ordinary post-content translation. Locate the relevant ACF Field Group item in WPML’s Translations dashboard and review the available labels or choices there.
After translation, check both sides of the experience: the editor should display the intended choice labels, and the front end should display the expected translated output. Do not assume that translating the post automatically translates selectable options. The exact behavior should be validated with the field configuration used on the site.
Translating ACF Options Pages and Validating the Result
Options Pages as global multilingual objects
ACF Options Pages are handled as a separate object type in WPML’s Translations dashboard, rather than as ordinary post content. This distinction matters because an Options Page may contain values used throughout the website. Each language’s values are then used in that language’s context.
Review global settings such as header, footer, contact information, and other site-wide values in every active language. A change to an Options Page can affect more than one page, so check every location where those values appear before publication. Do not treat a translated page as proof that global settings have also been translated.
Options Pages should be tested with the actual theme, builder, and custom integration used by the site. The documented workflow does not establish identical behavior for every third-party implementation. Human review is also required; workflow availability does not guarantee translation quality for a particular language pair.
A safe validation checklist
After configuration, review the complete path from field definition to front-end output. A practical checklist includes:
- Confirm that each ordinary ACF field has the intended preference: Translate, Copy, Copy Once, or Don’t translate.
- Check whether the field group uses the appropriate arrangement, including Same fields across languages, Different fields across languages, or Expert Mode.
- Review Repeater and Flexible Content rows, layouts, and nested text values in every active language.
- Verify field labels and choice values separately from post and page content.
- Open the ACF Options Pages translation items and confirm the values used in each language context.
- Test PHP-registered and Local JSON fields through the documented ACFML configuration and synchronization process.
- Inspect the front end and relevant editor screens using the actual theme, builder, and custom integrations.
If a value is missing, unexpectedly synchronized, or absent from the translation workflow, return to the field’s role and registration method. Check whether it was intentionally excluded, configured as Copy, or managed outside the ordinary administration interface. Test planned changes on staging or a representative duplicate page, and back up the site and database before bulk translation or synchronization changes.
The central rule is to match the preference to the content: use Translate for language-dependent values, Copy for information that must stay synchronized, Copy Once for content that starts shared but may later diverge, and Don’t translate for excluded fields. Repeater and Flexible Content structures need a separate decision about rows and layouts. Field labels, choice values, Options Pages, PHP-registered fields, and Local JSON configurations also require their own checks. Verify the current interface and test the complete result before changing production content. Explore our WordPress plugins, WooCommerce extensions, themes and membership plans to find the right tools for your website.