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.
- Requirements and installation
- Making the ACF fields translatable
- Translating the fields
- Translating ACF user interface
- Translating other parts of the interface
- How to handle images and other post object fields
- Known Issues
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.
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 -> Translation Management page, click the Multilingual Content Setup 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.
For the repeater fields, you need to set the translation option for each instance of the field inside the repeater, as displayed in the following image.
For the example displayed in the above image, we have a repeater field with three fields: “Title”, “Speaker”, and “Description”. Because we have three rows of the repeater fields in our page, this means we have to set translation options for three instances of each field – nine options altogether.
Please note that once you set the translation options for instances of a given repeater field, they will be used across other posts and pages (if they use this repeater field).
If you add another extra row to the repeater – you need to set the translation options for its instances, as displayed in the following image.
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.
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 Translation Management.
To use the Translation Editor for manually translating the content, go to the WPML -> Translation Management page and click the Multilingual Content Setup tab. There, select the Use the translation editor option under the How to translate posts and pages section.
As mentioned, you can also use the standard WordPress editor for manually translating your content and ACF fields.
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.
We need to be sure that the translation options are correct.
Go to: WPML -> Translation Management -> Multilingual Content Setup
Scroll down to the “Custom Posts” section and select the options in the following:
- Field Groups is selected as Translate.
- Fields is selected as Do nothing (this is an addition in Advanced Custom Fields Pro).
Start by creating the field groups and fields, as you would normally do with ACF. Notice the new Language box at the top-right. You are creating the field groups and fields in this language. When you are done, you can translate the groups and fields into other languages.
It is not neccessary to translate Field Groups. Created group will be used on the post edit screens in both languages.
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. In this case, create a Field Group translation by duplicating the group to other languages. To do this, in the Language box select the Duplicate checkbox and then click the Duplicate button.
After duplicating, we have the exact same field groups and fields for all the site’s languages.
Click on the pencil icon to edit text in the fields for different languages.
Now, we 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 are done with your edits, remember to click Update to save your changes.
The field group editing page includes several options that don’t require translation. They are normally synchronized with the field group in the default language, but you can change them in the translations if you want.
Now we can go and create a new post and see what we have achieved…
You can translate the original post by clicking the Duplicate button or (since ACFML 0.7 version) by creating the translation from scratch and clicking the “plus” icon next to the Duplicate option.
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.
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.
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.
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.
- 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
If you need help using WPML with Advanced Custom Fields, please head over to our technical forum.