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.

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 Translation Editor.

Translating a page with ACF repeater field using WPML Translation Editor
Translating a page with ACF repeater field using WPML 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 (version 3.7.1 or above), including the String Translation and Translation Management 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. 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.

Making the ACF fields translatable

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

You can do this in two ways:

  • Use the Multilingual Content Setup box when editing posts and pages.
  • Go to the WPML -> Settings page and set the options in the Custom Field Translation section.

There are three translation options  for custom fields translation:

  • Don’t translate – the field is ignored and no translation is performed or available for it.
  • Copy (from original to translation) – the value of the field is copied from the one in the original language.
  • Translate – allows you to manually translate the field values.

For simple fields, there is one option per field, as displayed in the following image.

Translation options for simple ACF fields
Translation options for simple ACF fields

The same applies to repeater fields. Set the translation preference for the main repeater field then click the Apply button. This applies the translation preference to all subfields.

Translation preference of the main field is copied to all the sub fields

Note that once you set the translation preference of the main repeater field in any post or a page, the same translation preference will be applied for all the subfields in other pages and posts. Of Course, you can set the translation preferences of subfields individually in different posts and pages.

Translating ACF Fields

WPML offers two ways of translating your contents, using WPML Translation Management or using the standard WordPress editor.

Using WPML Translation Management is highly recommended because it allows you to send content to be translated by other translators and also features WPML’s Translation Editor. It makes translating ACF fields very easy, as displayed in the following image.

Translating a page with ACF repeater field using WPML Translation Editor
Using WPML Translation Editor to translate a page featuring ACF fields

As you can see, Translation Editor displays all contents in the original language, including ACF fields, on the left side of the screen. The right side presents the same but empty fields where the translation is entered.

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

To use the Translation Editor for manually translating the content, go to the WPML -> Settings page. There, check the Use the translation editor option under the How to translate posts and pages section and click Save.

As mentioned, you can also use the standard WordPress editor for manually translating your content and ACF fields.

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.

The following steps should guide you on how to do this.

1. Checking translation options

We need to be sure that the translation options are correct.

Go to the WPML -> Settings page.

Scroll down to the “Posts Types Translation” section and select this option as follows:

  • Field Groups (acf) is selected as Not translatable.
Set the Field Group post type to not translatable

2. Creating Field Groups and Fields

Start by creating the field groups and fields, as you would normally do with ACF.

Adding Field Groups & Groups

3. Translating field groups and fields

Translating field texts

To set the custom field(s) created using ACF to be translatable, navigate to WPML -> Settings and scroll to the Custom Fields Translation section. Locate the custom field(s) that you included in your field group and set them to Translate.

Set the custom fields to translate

Let’s create a post in the default language and translate it including the custom fields values.

    1. Create the post in the default language.
Create a post in the default language
    1. Click on + icon to translate the page. This will take you to the Translation Editor page.
Click on the plus icon to translate the post
    1. Fill in your translated text and tick the Translation is complete checkbox for each field. You will notice that the custom fields values show on the Translation Editor page.
    2. Once you complete the translation, click on the Save & Close button.
Translate the texts and save

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. Activate the WPML manual translation mode by navigation to WPML -> Setting, under the How to translate posts and pages section, choose the Create translations manually option and Save.
Choose the manual translation mode
    1. Scroll to the Post Types Translation section and set the Field Groups (acf-field-group) to Translatable – only show translated items and Save.
Set the field group post type to 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.
Click on the edit link of the field group that you want to translate
    1. In the Language meta-box select the Duplicate checkbox for the different languages and then click the Duplicate button.
Duplicate the field group into the desired secondary language(s)
    1. Click on the pencil icon to edit text in the fields for different languages.
Click on the pencil icon to edit the texts in the different languages
    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.
Add your translated texts to the field group and update
    1. If you navigate to the secondary language post editing page you will see the field labels translated.
Translated field labels in the secondary language post editing page

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.

Do you still need to translate ACF’s interface? Then, go to the WPML -> Theme and plugins localization page.

You will see a list of plugins. Find Advanced Custom Fields 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, click the button to View all the plugin’s texts, which will take you to the String Translation page displaying the ACF’s strings.

Translating AVF admin Strings
Translating AVF admin Strings
Translating ACF Admin Strings
Translating ACF Admin Strings

Translate the strings that you want using WPML’s String Translation interface. When you are done, the field groups, fields and ACF’s user interface will all appear fully localized.

Translated ACF admin strings
Translated ACF admin strings

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 attachments are translated before you start adding them to the ACF form and duplicating.

For example, let’s assume you have added a Gallery field to the form. You are going to add some photos to this gallery under your post.

Before you duplicate your post along with its gallery, make sure every image in the gallery is translated. Even though you want to have the same images in post’s translation, you should go to the WPML -> Media page and duplicate all images. Once images are duplicated, you can go back to the post editing page and duplicate post to other languages (as described above).

Without duplication of 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.

Known Issues

There is currently one known issue you might encounter when translating ACF with WPML:

  • Inability to translate the labels of ACF fields on the WordPress backend, in the user interface.

We are investigating this issue and will fix it in the upcoming releases.

F.A.Q

  • Why are my custom fields not showing on the translated post/page?
    You probably did not translate the fields to the language you are editing in. To fix this, refer to step 3 – Translating field groups and fields.
  • 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.
  • The texts in the field groups are the same for all languages
    To select the desired translation option for a custom field value, be sure to check the “Multilingual Content Setup” box that appears below editor on your Post/Page edit screen. Make sure you select one of the available options for the desired fields.
    The available options are:
    1. Don’t translate – Do not translating value for other languages
    2. Copy – Duplicate the same value from default language
    3. Translate – Translate value for other languages

Getting help

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