Skip Navigation
Home » Documentation » Related Projects » Translate Sites Built with Advanced Custom Fields (ACF)

Translate Sites Built with Advanced Custom Fields (ACF)

Dario
Updated
September 7, 2022

Learn how to translate sites that are built with the Advanced Custom Fields (ACF) plugin and WPML.

On This Page

Getting Started

Start by installing and activating the following plugins:

If you’re new to WPML, check out our Getting Started Guide. It quickly walks you through different translation options you can use.

How ACF Works with WordPress Templates

ACF requires you to edit your site’s PHP files. If you are using the ACF custom fields with Elementor, which eliminates the need to work with PHP, see the page about Using the Advanced Custom Fields Plugin with Elementor.

The WordPress theme you are using controls the display of metadata like custom fields. To customize how metadata is displayed you need to edit your site’s PHP files.

ACF’s field builder allows you to create custom fields and attach them to posts, pages, or custom post types. However, after you hit Publish on the post or page using the ACF custom fields, the information from your custom fields is only stored in the database. It isn’t added to the front-end.

To display ACF fields and values added to your post or page on the front-end, you need to add PHP code directly into your child theme’s template files. This ensures that your custom fields display automatically. As an example, let’s say you assign a Field Group to Posts. In this case, you should create a child theme and edit the single.php template.

You’ll find that ACF’s functions are similar to the functions used when developing WordPress templates. For example, to use ACF fields in your templates, you can use the functions below:

  • get_field checks for, and retrieves field data
  • the_field checks for the data and displays it

You can learn more by reading ACF’s documentation about displaying values in your theme. 

How WPML Works with ACF

When you use WPML to translate a post from your default language, it creates a new post in your secondary language. You don’t have to connect the post in the secondary language to the one in your default language – WPML takes care of this for you. You only need to add the above-mentioned functions to your theme in your site’s default language.

Setting the Translation Preferences for Post Types

By default, standard WordPress Posts and Pages are translatable. So, if you are using your ACF custom fields in a post or page, you only need to set the translation preferences for your ACF custom fields. 

However, if you are using your ACF custom fields in custom post types, start by making sure your custom post types are set as translatable. You can then move on to setting the correct translation preferences for ACF fields.

Setting the Translation Preferences for ACF Fields

To learn which translation preference to use for each custom field type, see the page about recommended translation settings for ACF custom fields.

You can set the translation preferences for ACF custom fields in the Custom Fields Translation section of the WPML → Settings page.

Setting the translation preferences for custom fields

WPML allows you to choose from four different translation options. Below, we explain each of the translation preferences in more detail:

  • Translate – This option makes your custom field values available for translation. It is recommended for text fields (e.g. Text, Text Area, WYSIWYG, Message).
  • Copy –  This option copies the field value from the default language into the secondary language(s), which keeps your custom field value in sync across all languages. It is recommended for fields like Number, Range, True/False, and similar. Please note that when you use this option, the value of the field will not be available in WPML’s Advanced Translation Editor.
  • Copy Once – This option copies the value of the field from the default language, but the value of the field can be changed later in the WordPress native editor. After the first copy, it will not be kept in synchronization with the default language. Please note that when you use this option, the value of the field will not be available in WPML’s Advanced Translation Editor.
  • Don’t translate – The field is not available for translation. You should avoid using this option. For any custom fields you don’t want to translate, choose the Copy option. 

Please note: If you make a change in the translation preferences for your ACF fields, you should make a small change to the post in the original language using the fields and Save your changes. This has to be done in order for you to be able to update the translation.

Translating ACF Fields

Once you set the translation preferences for the custom fields, you can translate the custom field values. 

In the example below, we have set the field group Location Rule to Post type is equal to Post. You can set the location rule to show the fields in a specific custom post type such as Properties, Books, or Recipes. No matter the post type, the translation process is the same.

Start by creating and publishing a post with custom fields in the default language. Then:

  1. In the right sidebar, locate the Language box and click the plus icon next to the language you want to translate the post into. 
Clicking the plus icon to translate a post with custom fields
  1. You will be taken to the Advanced Translation Editor. You can translate the post content along with the values of the custom field that are set to Translate. If you have translation credits, you can click the Translate automatically button to add the machine translations. If not, enter the translations for each line manually. When you’re done, click Complete to publish the translations.
Translating a post with custom fields in the Advanced Translation Editor

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

Translating Choices for Select, Checkbox, and Radio Button Fields

The ACF plugin allows you to create Choices for the Select, Checkbox, and Radio button field types. 

To learn how to translate the labels of the Choices added to these field types, see the page about Translating ACF Field Labels and Labels for Choices with WPML.

Translating Field Groups

On the WPML Settings page, by default, the Field Groups post type is set to Not translatable. We don’t recommend changing the translation preferences of the Field Groups post type.
If you want to translate Field Labels, please keep the translation preference of the Field Groups post type as Not translatable and see the page about Translating ACF Field Labels and Labels for Choices with WPML.

Translating ACF Custom Fields Added to Taxonomies

You can also translate ACF custom fields added to taxonomies. 

When you add ACF custom fields to a taxonomy, make sure to set their translation preferences to Translate. 

In case you need to set translation preferences for existing fields, go to WPML → Settings and scroll down to the Custom Fields Translation section. Once you set the translation preferences of the ACF custom fields assigned to a taxonomy to Translate, you will be able to translate them alongside your taxonomies. 

To learn how to translate taxonomies, visit our page about translating post categories or custom taxonomies.

Using Different Files and Images Across Different Languages

To use different files and images across languages, install and activate the WPML Media Translation add-on on your site. 

Before you begin, make sure the translation preferences for your File and/or Image custom field types are set to Copy. Then:

  1. Edit the post or page with the assigned custom fields and click the plus icon to translate the text content using the Advanced Translation Editor.
  2. Once you are done translating the content, go to WPML → Media Translation and click the pencil icon next to the image or file you want to change in your secondary language.
Clicking the plus icon next to the file you want to change
  1. Upload the image or file in your secondary language and click the Save media translation button.
Uploading and saving the file in the secondary language

To learn more about using Media Translation, see the page about translating images with the WPML Media Translation plugin.

How to Handle the Translation of Posts and Images Added to the Post Object Field

The ACF Post Object field allows you to create an interactive drop-down menu that lists and links to existing posts, pages, or custom post types on your site. 

Before setting up the Post Object field, you need to translate any posts, pages, and media you want the Post Object field to display.

For example, let’s say you want your Post Object field to display a particular post on your website. Apart from text, this post contains a gallery of images. You need to translate the content and make sure the images appear on the translated version of the post.

To do this, edit your post and locate the Language box in the right sidebar and make sure that Duplicate uploaded media to translations is selected. This copies the images from the post in the original language to the post in your secondary language(s). You can then click the plus icon to translate the post as usual.

Selecting the Duplicate uploaded media to translations option

If you don’t translate your existing posts, post types, and pages before displaying them in the Post Object field, you may experience some discrepancies. On the backend, the Post Object field in your secondary language will be empty. However if you view the translated post or page with the assigned Post Object field on the front-end, you’ll see the Post Object field displaying posts in the default language.

Frequently Asked Questions

  1. Why aren’t the untranslated post object and page link fields showing on the backend of the duplicated post?
    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.
  2. 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.

Known Issues

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.

Learn More About Using ACF with WPML

Once you get acquainted with the information on this page, check out the other more advanced documentation pages about using ACF with WPML:

Getting Help

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