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 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

  • Translating ACF fields
  • Translating option pages custom fields
  • Translating ACF blocks
  • Translating ACF user interface
  • Translating other parts of the interface
  • How to handle images and other post object fields
  • F.A.Q.
  • Getting help
  • 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, Translation Management, and Media Translation add-ons.
    • The Advanced Custom Fields Multilingual (ACFML) plugin. 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.

    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

    Setting the translation preferences for ACF fields

    Before translating any custom fields using WPML, including the ones created with ACF, you need to set the appropriate translation preferences 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.
    Setting the custom field translation preference when creating the field
    Setting the custom field translation preference when creating the field

    You can also set the translation preference using the following steps:

    1. Look at the Multilingual Content Setup box when editing posts and pages.
    Setting the custom field 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 preferences for Repeater and Flexible fields

    Setting the translation preference for repeater and flexible 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 are exactly the same for setting the translation preference for flexible fields.

    1. We recommend setting the translation preference of the main repeater field, or the main flexible field, to Copy.
    2. Setting the translation preference to Copy

    1. When you edit a page and add values to subfields, WPML automatically applies the translation preference of the subfield you set when editing a field group to all the subfields.
    2. Setting the translation preference of the main repeater filed is applied to all subfields

    It is worth mentioning that WPML automatically sets ACF system fields to “Copy” which guarantees displaying the secondary language repeater field values on the front-end.

    Setting 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 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.

    1. Create a post in the default language and add values to the custom fields.
    2. Publish the post or a page.
    Creating a new post and adding values to the custom fields that you created
    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 values of the custom field that are set to Translate are available for translation.
    Clicking the plus icon to start translating the post
    1. Click the Translate automatically button to add the machine translation. Review the translation and make sure it’s accurate.
    2. Click the Finish button and then Complete to publish the translation.
    Translating the content automatically

    To learn how to send the content to be translated by others, visit our page about translating 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.
    Creating 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.
    Setting the custom fields translation preference
    1. Navigate to the options page and add a value to the default language custom field then click the Update button.
    Adding 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.
    Use the language switcher to choose the language
    1. Fill in the translated text then click the Update button.
    Adding the translated text and updating 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 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.

    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.
    Creating the block’s custom field group
    1. 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.
    Creating a new post and inserting the Testimonial block
    1. Fill in the block content and Publish the post.
    Filling 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.
    Starting the post translation

    This is how the translated page that includes the Testimonial block looks like 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.
    Setting 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.
    Editing the page of the field group
    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.
    Duplicating the field group
    1. Click on the pencil icon to edit the text in the fields for different languages.
    Editing the field group 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.
    Translating 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.
    Scanning the 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 version of the 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 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.

    Making sure that 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.

    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.