Skip Navigation

Home » WPML Documentation » Related Projects » ACFML – Build Advanced Multilingual WordPress Sites with ACF and WPML

ACFML – Build Advanced Multilingual WordPress Sites with ACF and WPML

ACFML lets you build multilingual sites using Advanced Custom Fields (ACF) and easily translate field content and labels. It covers both ACF and ACF Pro. Over 70,000 developers from around the world rely on ACFML to build their advanced multilingual WordPress sites.

ACFML in action

Key Features

Lets you translate custom field values, labels, titles, and labels for Choices

Comes with the Multilingual CMS and Multilingual Agency packages

No-code approach to translating field labels, titles, and choices

Simple and intuitive translation options for everything you create with ACF

Allows you to automatically translate your ACF-powered website

Flexibility to customize the translation workflow for complex field setups

Send content with ACF fields to your translation team or a professional service

Lets you translate custom fields dynamically inserted with the Elementor PRO and ACF integration

Compatible with ACF and ACF PRO fields and features

Required Plugins

ACFML comes with the Multilingual CMS and Multilingual Agency account types. 

To build a multilingual and ACF-charged website, you need to install and activate the following plugins:

New to WPML?

Check out our Getting Started Guide to quickly learn about the different translation options you can use. 

Ready to get started with ACF Multilingual? Read on!

Using the ACF Multilingual Setup

ACF Multilingual features a setup wizard to help you choose a translation option for your custom field groups. 

After you install the Advanced Custom Fields Multilingual (ACFML) add-on, you are prompted to edit each ACF field group to set a translation option for the fields inside it. To begin, you can click on the Set translation options button from your site’s dashboard. Or, you can head over to ACF → Field Groups.

You need to set the translation options for each field group. This requires you to Edit each field group. If you do not set a translation option for a field group, you will not be able to translate the fields belonging to it.

Selecting a Translation Option for Each Field Group

The ACF Multilingual Setup lets you choose from three translation options: 

  • Same fields across languages
  • Different fields across languages
  • Expert

The first two options automatically set the translation preferences for the custom fields inside the field group. Here’s when you can use them:

Same fields across languages

See the pre-set translation preferences

Same values for Choice, Radio Button, and Select fields in all languages

Same number of instances of Repeater, Flexible, Clone fields in all languages

Same order of subfields within Repeater, Flexible, and Clone fields in all languages

Same values for URL field type in all languages

Translate the post type and the field values using WPML’s Translation Editors

Different fields across languages

See the pre-set translation preferences

Different values for Choice, Radio Button, and Select fields across languages

Different number of instances of Repeater, Flexible, Clone fields across languages

Different order of subfields within Repeater, Flexible, and Clone fields across languages

Different values for URL field types across languages

Translate the post type and the field values using the native WordPress editor

The Expert translation option lets you manually set individual translation preferences for each custom field in your field group. 

On existing sites with ACF and WPML, your existing field groups are automatically set to use the Expert mode. 

We don’t recommend changing this option for your existing field groups, but you can choose any option you’d like for any new field groups you create.

If you decide to use the Expert translation option on a new site, see the recommended translation preferences for custom fields.

Translation Preferences for the Field Group Post Type 

By default, the translation preference of the Field Group post type is locked and set to Not translatable. You should not unlock and change this setting. 

If you have an existing site with a Field Group set to Translatable, see how to change the translation preferences of the field group. 

Translating ACF Fields Using the “Same fields across languages” Option

Before you start translating, make sure each of the custom fields across your different field groups have a unique Field Name. If you use the same Field Name with more than one custom field, you may not see all your field values available for translation in the Translation Editor.

Once you select the Same fields across languages translation option, you can translate the custom field values using either one of WPML’s translation modes:

  • Translate Everything Automatically translates your site’s content as you add or edit it. You can then review the translations before publishing them to ensure they’re correct.
  • Translate What You Choose lets you decide what content to translate, and who will translate it. Choose between translating the content yourself, assigning it to an individual translator, or hiring a professional translation agency.

Here, we’ll show you how to translate a post and the field values by yourself:

  1. Edit your post and locate the Language box in the right sidebar. Click the plus icon next to the language you want to translate the post into.
Clicking the plus icon to translate a post
  1. You will be taken to the Advanced Translation Editor. If you have translation credits, you’ll see the automatic translations filled in for you. You can review and accept them, or click the Undo translation button to remove the pre-filled automatic translations and input your own. If you don’t have credits, add the translations for each line by yourself.
Translating the post and field values in the Advanced Translation Editor
  1. When you’re done reviewing the translated content, click Complete to publish the translations.

Translating ACF Fields Using the “Different fields across languages” Option

The Different fields across languages option lets you achieve different custom field structures across languages. This means that in each language, you can have:

  • A different number of repeating field instances
  • Different field values
  • A different field order

For example, let’s say your website has an Our Team page. The field group used with this page has a Repeater field with some subfields. You want to list 4 employees on a page in your site’s default language, but only 2 employees in the secondary language.

An “Our Team” page with 4 repeating subfields in the default language

An “Our Team” page with 2 repeating subfields in the secondary language

To achieve this, you need to select the Different fields across languages option for your field group. Then, you can translate the post content and field values manually using the native WordPress editor:

  1. Edit the post or page with the custom fields assigned to it.
  2. In the Language box, the WordPress Editor is chosen by default for you. Click the plus icon next to the secondary language you want to translate your page into.
Clicking the plus icon to create the page in the secondary language
  1. You’ll be taken to a completely blank page. Add the title of the page in your secondary language and click Publish.
Adding the secondary language post title and publishing the page
  1. Refresh the page you just published in the secondary language. Add, edit, remove, and reorder layouts and custom fields in your secondary language according to your needs. Once you’re done manually translating the field values, click Update.
Adding the secondary language repeating field values

If your default and secondary language posts are using a different field order, you now need to disable the synchronization of the field order across languages. 

You can do this by editing the post in your default language. In the ACFML Synchronise Translations section at the top of the page, uncheck the option to keep repeater and flexible sub-fields in the same order. Then, Update the page.

Disabling the option to keep the field order in sync across languages

Both language versions are now fully independent from one other, with different layout structures and different custom field values. 

Translating Field Labels and Labels for Choices

How you can translate labels depends on the translation option you select for your field group:

Same Fields Across Languages

You can translate labels using automatic translation or in the Advanced Translation Editor. 

All the field labels and labels for Choices belonging to a field group are sent for translation once, together with the first translation job.

Translating field labels and labels for Choices in the Advanced Translation Editor

You can make changes or edits to the translations of specific labels from WPML → String Translation.

Or, you can update the translations for all the field labels, titles, and labels for Choices by sending your acf-field-group domain for translation from WPML → Translation Management. You can select between translating the field group package automatically, by yourself, or assigning it to a translator.

Different Fields Across Languages

You can translate field labels and labels for Choices in String Translation. Or, you can send all the field titles, labels and labels for Choices belonging to a field group for translation at once from the Translation Management Dashboard.

Translating Field Labels in String Translation

Start by going to WPML → String Translation.

Use the In domain drop down menu at the top of the page to search for the acf-field-group domain. If you have multiple field groups, you will see multiple acf-field-group domains. Each ends in a different number. The number corresponds to the post ID of your field group. You can easily find this post ID by looking at the URL when you’re editing your field group.

Searching for strings in the ACF field group domain

A list of strings in the selected domain appears in the String Translation table. Click the plus icon under the flag of the language you would like to translate the labels into.

Translating field labels in String Translation

Translating Field Labels in Translation Management

To send all the labels and titles from a field group to translation at once, go to ACF → Custom Fields and Edit your field group. Make a note of the post ID you see in the URL.

Making a note of the field group’s post ID

Then, go to WPML → Translation Management:

  1. Use the first dropdown menu to select ACF Field Group as the type of item you want to translate.
  2. Look for the Field Group Labels package with the post ID you noted earlier and select it.
  3. Choose the languages you want to translate the field group labels into.
  4. Select how you want to translate and send the field group labels to translation.
Sending field group labels to translation from Translation Management

If you assigned the translation job to a translator, you need to go to the Translation Basket tab to select your translator and send the field group labels for translation.

If you are translating by yourself or sent the field group labels for automatic translation, you can go to WPML → Translations to take and review the translation jobs.

Translating ACF Custom Fields Added to Taxonomies

You can translate ACF custom fields added to taxonomies. How you translate them depend on the translation option you select:

Same Fields Across Languages

You can translate the taxonomies by going to WPML → Taxonomy translation.

Note that you can only translate field types that are pre-set to the Translate translation preference.

Different Fields Across Languages

You can translate the taxonomies using the native taxonomy edit screen.

Using Different Files and Images Across Different Languages

To use different files and images across languages, install and activate the WPML Media Translation add-on on your site.

To use different files or images in different languages:

  1. Edit the post or page with the assigned custom fields and translate the text content using the Advanced Translation Editor. 
  2. Once you are done translating the content, go to WPML → Media Translation and click the pencil icon next to the image or file you want to change in your secondary language.
  3. Upload the image or file in your secondary language and click the Save media translation button.

Learn more on the page about translating images with the WPML Media Translation plugin.

How to Handle the Translation of Posts and Images Added to the Post Object Field

The ACF Post Object field allows you to create an interactive drop-down menu that lists and links to existing posts, pages, or custom post types on your site. 

Before setting up the Post Object field, you need to translate any posts, pages, and media you want the Post Object field to display.

For example, let’s say you want your Post Object field to display a particular post on your website. Apart from text, this post contains images. You need to translate the content and make sure the images appear on the translated version of the post.

To do this, edit your post and locate the Language box in the right sidebar and make sure that Duplicate uploaded media to translations is selected. This copies the images from the post in the original language to the post in your secondary language(s). You can then click the plus icon to translate the post as usual.

Duplicating uploaded media to the translations

If you don’t translate your existing posts, post types, and pages before displaying them in the Post Object field, you may experience some discrepancies. 

On the backend, the Post Object field in your secondary language will be empty. However if you view the translated post or page with the assigned Post Object field on the front-end, you’ll see the Post Object field displaying posts in the default language.

Frequently Asked Questions

  1. Why aren’t the untranslated post object and page link fields showing on the backend of the duplicated post?
    Please note that this is not a bug and it does not affect the functionality. Read more about this scenario on our dedicated FAQ page.
  2. Is it possible to hide ACFML field annotations?
    Yes. To each translated field, ACF Multilingual adds information about the value in the original language. If you want to remove that information you can add the following line to your site’s wp-config.php file:
define( 'ACFML_HIDE_FIELD_ANNOTATIONS', true );

This feature is supported in ACFML since the 1.1 version.

  1. How do I stop field labels from showing up in the Advanced Translation Editor?
    You can exclude field labels and field titles from appearing in the Advanced Translation Editor using the ACFML_EXCLUDE_FIELD_GROUP_STRINGS_IN_POST_JOBS constant. You can still translate them if you choose to later from the String Translation page. Simply add the following to your wp-config.php file:
define( 'ACFML_EXCLUDE_FIELD_GROUP_STRINGS_IN_POST_JOBS', true );

Getting Help

If you need help using WPML with Advanced Custom Fields, please head over to our technical forum.

ACFML – Build Advanced Multilingual WordPress Sites with ACF and WPML
Dario
Updated
November 27, 2023