ACF and WPML

This tutorial explains how to translate sites that are built with the Advanced Custom Fields (ACF) plugin and WPML. All you need to do is configure WPML to translate the related custom fields groups. Then, you will be able to translate ACF’s fields, including the repeater fields and flexible fields.

One of the most important features of WPML’s integration with Advanced Custom Fields plugin is the ability to translate the repeater fields. The following image displays how this is easily done using WPML’s Advanced Translation Editor.

Translating a page with ACF repeater field using WPML Advanced Translation Editor

On this page

Requirements and installation

If you are a site owner working with a developer, ask them to check and set up the requirements listed in this section. For you, the Translating the fields section is the most important one.

You need the following plugins installed and activated on your site:

  • The ACF plugin (latest free or pro version)
  • A recent version of WPML, including the String Translation and Translation Management add-ons.
  • The Advanced Custom Fields Multilingual (ACFML) plugin (version 1.1 or higher). ACFML is a bridge plugin that makes WPML and Advanced Custom Fields plugin compatible.

WPML’s Getting Started Guide will help you in setting up WPML in a few minutes. You might want to refer to some of its subtopics later on, such as Theme and Plugin Localization and String Translation pages. We recommend that you keep this guide open while following this tutorial.

The setup of the ACFML plugin is simple. You can download the plugin on the WPML site, from the Download section of your Account page. There is no user interface or any specific settings – the plugin works in the background.

The ACF documentation will provide you with all the information needed to set it up and use it.

For a better translation experience, activate WPML Advanced Translation Editor. You can do this on the WPML -> Settings page, in the How to translate posts and pages section. There, select the Use WPML’s Advanced Translation Editor option for the new content and click Save.

Use WPML’s Advanced Translation Editor

Making the ACF fields translatable

Reviewing the translation preference after updating to ACFML 1.1

Setting the custom fields translation preference from the Field Group screen is introduced in ACFML version 1.1. If you have set the translation preference for your custom field(s) using an older version of ACFML, you will see a red tooltip icon next to that field. It indicates that the translation preference of that fields needs to be reviewed. Otherwise, the default value (Don’t translate) will be set.

Reviewing the translation preference of custom fields

Setting the translation preference for simple fields

Before translating any custom fields using WPML, including the ones created with ACF, you need to select appropriate translation options for them.

You can set the translation preference for each field that you create in the Field Group from the Translation preferences section. There are four translation preferences for custom fields translation

  1. Don’t translate: The field is ignored and no translation is performed or available for it.
  2. Copy: The value of the field is copied from the one in the original language.
  3. Copy once: The value of the custom field is copied to the secondary language in the initial translation process. The custom fields that use the copy-once action will not appear on the Translation Editor screen. However, the user can change the custom field value of the secondary language to be different from the default language using the post editing screen.
  4. Translate: Allows you to translate the field values.
Set the custom filed translation preference when creating the field inside the field group editing screen

You can also set the translation preference from:

  1. The Multilingual Content Setup box when editing post and pages.
Set the custom filed translation preference from the post editing screen
  1. The WPML Settings page, under the Custom Field Translation section.
Setting the custom fields translation preference from the WPML Settings page

Setting the translation preference for repeater fields

Setting the translation preference for repeater fields is similar to setting the translation preference for simple fields. We recommend setting the translation preference of the main repeater field to Copy.

Set the translation preference to Copy

When adding values to any number of subfields on the post/page editing screen, WPML automatically applies the translation preference of the subfield that you have set on the fields group editing page to all the subfields on the page or a post.

Setting the translation preference of the main repeater filed is applied to all subfields

On the post/page editing screen, go to the Multilingual Content Setup box and click Show system fields.

Go to the Multilingual Content Setup box and click Show system fields

Set the fields that correspond to the repeater field name with an underscore at the beginning to Copy.

Set the system field to Copy

Translating ACF Fields

Now that we have set the translation preferences for our custom fields, it is time to translate the custom fields values (texts).

  1. Create a post in the default language and add values to the custom fields.
  2. Publish the post or a page.
Create a new post and add values to the custom fields that you created then publish the post
  1. In the Language section, click the plus icon. You will be taken to the Advanced Translation Editor page. The post content along with the custom field values are available for translation.
Click the + icon to translate the post
  1. Click the Translate automatically button to add the machine translation. Review the translation and make sure that it is accurate.
  2. Click the Finish button then Complete to publish the translation.
Click the Translate automatically button to add the machine translation

To learn how to send the content to be translated by others, visit our page about how to translate your WordPress site.

Translating option pages custom fields

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 it’s fields, follow the steps below:

  1. Create a custom field group for the desired options page.
  2. Create the options page custom field group

  1. Set the custom field(s) translation preference to Translate. Also, set the location to match the options page. Once done, Publish the field group.
  2. Set the custom fields translation preference

  1. Navigate to the options page and add a value to the default language custom field then Update.
  2. Add a value to the custom field

  1. Use the admin bar language switcher to choose the language you want to translate your field text into.
  2. Use the language switcher to choose the language

  1. Fill in the translated text then Update.
  2. Add the translated text and update the page

Translating ACF blocks

The ACF’s 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 the example below, we have created a simple Testimonial block with ACF. Follow the steps below to learn how to set the translation preference of the ACF fields of your block and translate the block’s content using WPML’s translation editor.

  1. Create the block field group by navigating to Custom Fields -> Add new.
  1. Fill in the field group name and add the custom fields.
  1. When creating the custom fields, make sure that you set the appropriate Translation preference.
  1. In the Location box, set the field group to show when the Block is equal to Testimonial. Once done, don’t forget to Publish.
  2. Create the custom filed group of the block

  1. To insert the ACF block that we created into a post, navigate to Posts -> Add New. Fill in the post title. Click the plus icon in the content editor and choose the Testimonial block.
  2. Create a new post and insert the Testimonial block

  1. Fill in the block content and Publish the post.
  2. Fill in the Block’s content

  1. 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.
  2. Click on the plus icon to translate the post

This is how the translated page that includes the Testimonial block looks on the front-end:

Translated block on the front-end

Translating ACF user interface

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.

Translating field groups

It is not necessary to translate Field Groups unless you want to translate the field labels (Field Label, Field Name, Instructions, Default Value, Placeholder Text, etc.)

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.

To translate the Field Group, follow the steps below:

  1. 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.
Set the Field Groups (acf-field-group) post type to be translatable
  1. 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.
Go to the editing page of the field group
  1. In the language box, turn off using the “Use WPML’s Translation Editor” option. Then, choose the “This Field Group” option and click the Apply button.
Disable using the WPML Translation Editor
  1. In the Language meta-box, select the Duplicate checkbox for the different languages you want to translate your field group into and then click the Duplicate button.
Select the duplicate checkbox then click the duplicate button
  1. Click on the pencil icon to edit text in the fields for different languages.
Click the pencil icon to edit the translation
  1. 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 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.
Translate the custom field texts
  1. If you navigate to the secondary language post editing page you will see the field labels translated.
Translated field labels

Translating other parts of the interface

So far, we talked about 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.

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:

  1. Go to the WPML -> Theme and plugins localization page.
  2. 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.
Scan ACF plugin for translatable strings
  1. 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.
  2. To translate a string, click on the translations link, add your translated content, tick the Translation is complete check-box then Save.
Translating ACF strings
  1. When you are done, the ACF’s user interface will all appear fully localized.
Localized ACF interface

How to handle images and other post object fields

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 post/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.

Make sure that the images included in the gallery are translated

Without translating 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.

FAQ – Frequently Asked Questions

  • Untranslated post object and page link fields do not show on the back-end 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.

Getting help

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