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

Translating ACF Blocks With WPML

Kathy Banach
Updated
March 13, 2023

The ACF Blocks feature allows you to create custom block types. Here, we’ll show you how to translate them using WPML.

If you want to learn how to translate ACF fields in general, see the Translate Sites Built with ACF page.

Before getting started, make sure to install and activate the Advanced Custom Fields, WPML core, WPML String Translation, and Advanced Custom Fields Multilingual plugins.

With WPML, you can translate ACF block content just like any other WordPress Gutenberg block. For more information on how to create and use ACF Blocks, check out the post introducing ACF Blocks.

On This Page

Making ACF Fields Registered Programmatically Translation-Ready

This section is only intended for developers registering ACF fields programmatically.

 ACF lets you create the field group associated with a block in two ways:

  • From the Custom Fields menu item on your WordPress site’s backend
  • Programmatically using the acf_add_local_field_group function 

If you created the field group from the Custom Fields menu item, you can skip this section.

For field groups built programmatically, you need to make the fields translatable. You can do this by setting the wpml_cf_preferences for each field in your code.

There are four numerical values you can use for wpml_cf_preferences:

  • Ignore: 0
  • Copy: 1
  • Translate: 2
  • Copy once: 3

Below you can find an example of the wpml_cf_preferences key added to a programmatically registered field group.

Using the wpml_cf_preferences key added to a programmatically registered ACF field group 
acf_add_local_field_group( [
	'key'                   => 'group_1',
	'title'                 => 'My Group',
	'fields'                => [
		[
			'key'                 => 'field_1',
			'label'               => 'Sub Title',
			'name'                => 'sub_title',
			'type'                => 'text',
			'prefix'              => '',
			'instructions'        => '',
			'required'            => 0,
			'conditional_logic'   => 0,
			'wrapper'             => [
				'width' => '',
				'class' => '',
				'id'    => '',
			],
			'default_value'       => '',
			'placeholder'         => '',
			'prepend'             => '',
			'append'              => '',
			'maxlength'           => '',
			'readonly'            => 0,
			'disabled'            => 0,
			'wpml_cf_preferences' => 2, // This field ("Sub Title") will be translated.
		],
	],
	'location'              => [
		[
			[
				'param'    => 'post_type',
				'operator' => '==',
				'value'    => 'post',
			],
		],
	],
	'menu_order'            => 0,
	'position'              => 'normal',
	'style'                 => 'default',
	'label_placement'       => 'top',
	'instruction_placement' => 'label',
	'hide_on_screen'        => '',
] );

Translating ACF Blocks Using the “Same fields across languages” Option

Please note that if you create different field groups for your blocks, you need to make sure each custom field across your different field groups has a unique Field Name. If you assign the same Field Name to more than one custom field, you may not see all your field values available for translation in the Translation Editor.

If you select Same fields across languages for your block’s field group, you can translate the block content using:

As an example, we created a simple Testimonial block with ACF. We set the field group associated with the block to the Same fields across languages translation option.

Setting the field group to the Same fields across languages translation option

Now, we’ll show you how to translate the block’s content by yourself:

  1. Edit the post or page into which you inserted the ACF block. From the Language box, click the plus icon next to the language you want to translate the post and block content into.
Clicking the plus icon to translate the post with the block content
  1. You will be taken to the Advanced Translation Editor. If you have translation credits, you can translate the content automatically. If not, add the translations for each line and click Complete when you’re done.
Translating the block content in the Advanced Translation Editor

Translating ACF Blocks Using the “Different fields across languages” Option

You can select the Different fields across languages option for the field group you create for your block. This is useful if you have Repeater or Flexible Content fields within your block. It allows you to have a different number of fields across your site’s languages. 

However, this option requires you to manually input the block content in each language. You then need to translate the field labels and labels for Choices of Select field types in String Translation.

To demonstrate this, we have created an Agents block with ACF. The field group assigned to the block has a main Repeater field and 4 subfields. The field group is set to the Different fields across languages translation option.

To translate the block content:

  1. Edit the page into which you have inserted your ACF block. In the Language box, select to translate your page with the WordPress Editor. In the popup that appears, select the This Page option.
Selecting to translate the block content with the WordPress Editor
  1. Click the plus icon next to the language you want to translate the post into.
Clicking the plus icon to translate the post
  1. You will be taken to a blank page. Enter the title of the post, the post content, and insert your ACF Block.
  2. Within your block, add as many instances of repeating subfields as you want. Input the field values in your site’s secondary language.
Inputting the block content in the secondary language
  1. When you’re done, Publish the post.

To translate the labels and labels for Choices for Select field types:

  1. Go to WPML → String Translation and use the In domain dropdown menu to select your ACF field group.
  2. Click the plus icon next to the field labels and labels for Choices you want to translate.
Translating field labels and labels for Choices in the Advanced Translation Editor

Translating ACF Blocks Using the Expert Option

How you translate your ACF block content in the Expert translation option depends on the translation preferences you choose for your fields.

You can learn more on the page about using the Expert translation option.