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:
- The ACF plugin (latest PRO version required for Repeater fields and other additional features)
- WPML core plugin and WPML String Translation add-on
- The Advanced Custom Fields Multilingual (ACFML) plugin
- The WPML Media Translation add-on (If you want to use different files and/or images in your default and secondary languages)
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
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
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:
- 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.
- 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.
- 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:
- Edit the post or page with the custom fields assigned to it.
- 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.
- You’ll be taken to a completely blank page. Add the title of the page in your secondary language and click Publish.
- 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.
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.
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.
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.
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 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.
Then, go to WPML → Translation Management:
- Use the first dropdown menu to select ACF Field Group as the type of item you want to translate.
- Look for the Field Group Labels package with the post ID you noted earlier and select it.
- Choose the languages you want to translate the field group labels into.
- Select how you want to translate and send the field group labels to translation.
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:
- Edit the post or page with the assigned custom fields and translate the text content using the Advanced Translation Editor.
- 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.
- 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.
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
- 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. - 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.
- 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 theACFML_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 );
Known Issues
WPML works fine with this plugin, but sometimes there could be minor issues we're working on. This is expected as both plugins provide frequent updates.
Current unresolved issues:
- Advanced Custom Fields – Uncaught TypeError: md5(): Argument #1 ($string) must be of type string, array given in…
- Advanced Custom Fields – Block Clone Field Value Lost When Same Block Added Twice in a Post
- Advanced Custom Fields (ACF) 6.1 – Labels for custom post types and custom taxonomies not translatable yet
- Advanced Custom Fields Multilingual – Reordering Repeater fields unsynchronizes the translations
You can also search all known issues including previously resolved issues for this plugin.
Getting Help
If you need help using WPML with Advanced Custom Fields, please head over to our technical forum.