Learn how to translate sites that are built with the Advanced Custom Fields (ACF) plugin and WPML.
- Getting Started
- Making the ACF Fields Translatable
- Translating ACF Fields
- Translating Options Page Custom Fields
- Translating ACF Blocks
- Translating ACF User Interface
- Translating Other Parts of the Interface
- How To Handle Images and Other Post Object Fields
- Frequently Asked Questions
- Known Issues With Advanced Custom Fields
- Getting Help
Start by installing and activating 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. ACFML is a bridge plugin that makes WPML and Advanced Custom Fields plugin compatible.
If you’re new to WPML, check out our Getting Started Guide. It quickly walks you through different translation options you can use.
WPML’s Translate Everything feature can translate all of your site’s content instantly, including values stored in your ACF fields. The only thing you need to do is set the correct translation option for your ACF fields.
Go to the WPML → Settings page and scroll to the Custom Fields Translation section. Select the translation options for your ACF fields.
You can also select the fields translation options when editing your custom fields settings in ACF.
You also have the option to set your translation preferences whenever you edit a page or post that uses custom fields. Please note changes you make to translation preferences here apply across your site. To enable this, go to WPML → Settings and check the box to Show “Multilingual Content Setup” on post edit screen.
You can then open a page or post and see the ability to change the translation preferences for your custom fields.
Setting your translation preferences for Repeater and Flexible Content fields is similar to setting the translation preference for other ACF fields. In the example below, we cover the steps for setting the translation preference for Repeater fields which is exactly the same for setting the translation preference for Flexible Content fields.
These field types are only available with the Pro version of Advanced Custom Fields.
- We recommend setting the translation preference to Copy or Copy once for the main Repeater field, or the main Flexible Content field:
- If you want to have the same number of fields and same field values in all languages, set this to Copy.
- If you want to have a different number of fields and/or different field values across different languages, set this to Copy once.
You can also disable the synchronization of the Repeater field across languages. This means you can manually set the order of the fields for each language. To do this, uncheck the Sync repeater sub-fields positions in post translations box that appears under the Repeater field in the post or page.
- You can choose any translation preference for subfields. If you set translation preference for subfield, each subfield you create on post edit screen will have this translation preference applied.
WPML automatically sets ACF system fields to Copy which guarantees to display the secondary language repeater field values on the front-end.
Now that we have set the translation preferences for our custom fields, it is time to translate the custom field values (texts). In the example below, we have set the field group Location Rule to Post type is equal to Post. If you set the location rule to show the fields in a specific custom post type such as properties, books, recipes, you will be able to translate the custom fields in a similar fashion.
- Create a post in the default language and add values to the custom fields.
- Publish the post.
- In the Language section, click the plus icon. You will be taken to the Advanced Translation Editor page. The post content along with the values of the custom field that are set to Translate are available for translation.
- Click the Translate automatically button to add the machine translations. Review the translations and make sure they’re accurate.
- Click Complete to publish the translations.
To learn how to send the content to be translated by others, visit our page about translating your WordPress site.
For the choice fields such as the Select and Radio Button fields, please note that if you navigate to the secondary language editing page you will see the choices untranslated showing the default language texts although you have translated them. This is not a bug and it doesn’t affect the functionality as the translated texts are stored correctly in the database. Accordingly, the correct values will be displayed on the front-end.
ACF allows you to create Select fields that provide options for users to choose from. There are two ways to translate the values of such Select field options and display them correctly on the front-end.
In the WordPress admin, go to the WPML → Settings page and scroll down to the Custom post types section. There, set the Field Groups (acf-field-group) post type to be translatable.
Translate every field group you have already created on your site. Make sure to translate all options for your Select field.
Sometimes, you might already have created too many field groups to start translating them all now just to translate a few labels. In this case, you can translate labels that display in your theme files.
For this to work, make sure that the Field Groups post type is not translatable. In your theme files, edit the place where you want to display the selected option and add the following code:
$chosen_color = get_field( 'color-variants' ); $avail_colors = [ 'red' => __( 'Red', 'domain'), 'blue' => __( 'Blue', 'domain'), ]; echo esc_html( $avail_colors[$chosen_color] );
In the above snippet, we used an example of a Select field for choosing a color. Of course, adjust this snippet to fit your settings: use your own field slug and options ( instead of “red” and “blue”) with the correct field values defined for this Select field.
Then, go to WPML → Theme and plugins localization, select your theme, and click to scan it for strings. Finally, go to WPML → String Translation, find your Select field values, and translate them.
You can also translate ACF custom fields added to taxonomies. When adding ACF custom fields to a taxonomy, make sure to set their translation preferences to Translate. To set translation preferences for existing fields, go to WPML → Settings and scroll down to the Custom Fields Translation section. You will then be able to translate them alongside your taxonomies. To learn how to translate taxonomies, visit our page about translating post categories or custom taxonomies.
The ACF Options Pages provide a set of functions to add extra admin pages to edit ACF fields. Check out ACF’s documentation on creating Options Pages.
To create an Options Page custom field group and translate its fields, follow the steps below:
- Create a custom field group for the desired Options Page.
- Set the custom field(s) translation preference to Translate. Also, set the location to match the Options Page. Once done, Publish the field group.
- Navigate to the Options Page and add a value to the default language custom field then click the Update button.
- Use the admin bar language switcher to choose the language you want to translate your field text into.
- Fill in the translated text then click the Update button.
If you set the translation preferences of the custom fields on your Options page to Copy, you will need to manually save this setting on your secondary language page(s). This is expected behavior.
To do this:
- From your dashboard, go to Options and use the language switcher in the top admin bar to switch to a secondary language.
- Click on the Update button in the Publish tab.
Repeat the steps above for your remaining secondary languages.
The ACF block content can be translated as any other default WordPress Gutenberg block. For more information on how to create and use ACF Blocks, check out this post.
In our example, we have created a simple Testimonial block with ACF. Let’s see how to set the block’s ACF field translation preference and translate the block’s content using WPML’s Translation Editor.
- Create the block field group by navigating to Custom Fields → Add New.
- Fill in the field group name and add the custom fields.
- When creating the custom fields, make sure that you set the appropriate Translation preferences.
- In the Location box, set the field group to show when the Block is equal to Testimonial. Once done, don’t forget to Publish.
- Let’s insert the ACF block that we created into a post. Navigate to Posts → Add New and fill in the post title. Click the plus icon in the content editor and choose the Testimonial block.
- Fill in the block content and Publish the post.
- In the Language box, click the plus icon corresponding to the language you want to translate your post into. You will be taken to the WPML Translation Editor. There, fill in the translated content and publish the translation.
This is how the translated page that includes the Testimonial block looks on the front-end:
Besides being able to translate the values of ACF fields that are shown on the front-end, WPML allows you to also translate the ACF user interface. This means that when translators are translating posts and pages that feature ACF fields, the labels and options for those fields will appear in that specific language. This can help to make the translator’s work easier and more convenient.
If you only need to translate field values and display them on the front-end, you don’t need to perform the following steps. You should only need to translate Field Groups in certain cases. For example, if on the front-end, you want to display different field labels for different languages.
Setting Field Groups as translatable may result in some unexpected issues if you have a fairly complex site.
To translate the Field Group, follow the steps below:
- Set the Field Groups (acf-field-group) post type to be translatable by navigating to WPML → Settings and scroll to the Post Types Translation section.
- To translate the Field Group, navigate to Custom Fields → Field Groups and click on the Edit link of the field group you want to translate.
- In the Language meta-box, make sure that the Use WPML’s Translation Editor option is turned off. Then, select the Duplicate checkbox for the different languages you want to translate your field group into and click the Duplicate button.
- Click on the pencil icon to edit the text in the fields for different languages.
- Now, you can edit the text in this group, for the other language(s). To keep your field groups consistent for all the languages of the site, you should only edit the label and descriptions of the fields and not add new fields or change their Field Name values. If you do make any changes like this to the fields, you should do so for all your site’s languages. Once you complete adding the translated texts to the field group, click the Update button to save the changes.
- If you navigate to the secondary language post editing page you will see the field labels translated.
So far, we’ve covered translating the field groups and fields. Like any other WordPress plugin, ACF has its own user interface which includes text. To have a fully localized WordPress admin, you can also translate the ACF’s interface.
Also like many other WordPress plugins, ACF comes with its own translations. Before you translate ACF’s interface, check with the author to see if the translation in your language is already available.
To translate ACF’s interface, follow the steps below:
- Go to the WPML → Theme and plugins localization page.
- Under the Strings in the plugins section, you will see a list of plugins installed on your website. Select the Advanced Custom Fields plugin and click the Scan the selected plugins for strings button. WPML will scan ACF’s code and locate all translatable strings.
- After the scan is complete, navigate to WPML → String Translation page and choose the “acf” text domain from the “Select strings within domain:” drop-down menu then click the Search button. This loads all the ACF strings that are available for translation.
- To translate a string, click on the translations link, add your translated content, tick the Translation is complete check-box, then Save.
- When you are done, the ACF’s user interface will appear fully localized.
If you constructed a Field Group with a field pointing to an existing post or custom post type (including images and other kinds of attachments), make sure that the post or post attachments are translated before you start adding them to the ACF field group.
For example, let’s assume you have added a Gallery field to the field group. You are going to add some photos to this gallery under your post.
Before translating your post along with its gallery field, make sure every image in the gallery is translated. Even though you want to have the same images in the translated post, you should go to the WPML → Media page and make sure that all the images included in the gallery are translated.
Without translating post objects such as images, posts and other kinds of post types, you will experience some minor problems, though your site will be working. Translated posts will be associated with objects in the original language, which is allowed. On the front-end, posts will display correct relations, however, on the post edit screen, you will see these fields as empty.
- Untranslated post object and page link fields do not show on the backend of the duplicated post despite the fact that the post is associated with the correct value for the post object and page link custom fields in the database.
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, ACFML 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.
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:
You can also search all known issues including previously resolved issues for this plugin.
If you need help using WPML with Advanced Custom Fields, please head over to our technical forum.