ACF Multilingual (ACFML) Constants and Hooks Reference

Kathy

Updated

March 26, 2026

Discover the complete list of ACF Multilingual (ACFML) constants and hooks, with examples for using them in your code.

ACF Multilingual (ACFML) Hooks

acfml_should_translate_acf_entity

This hook allows you to determine whether ACF fields or field groups should be translated. By using this filter, you can skip translating specific fields or groups based on your custom logic.

Type: Filter

Availability: ACFML 2.1.4

Parameters:

$shouldTranslate
(bool) (Required) Whether the field or field group should be translated. Defaults to true.

$entity
(array) (Required) The entity being translated, which is either a field array or a group array.

$entityType
(string) (Optional) The type of the entity being translated. It can be either ‘field’ or ‘group’.

Hook Example Usage:

add_filter( 'acfml_should_translate_acf_entity', function( $shouldTranslate, $entity, $entityType ) {
	if ( 'field' === $entityType ) {
		return false;
	}

	return $shouldTranslate;
} );

acfml_field_group_mode_field_translation_preference

This filter allows you to override the default translation preference for ACF fields when a field group uses Same fields or Different fields mode.

Note: This filter changes only the default translation preference, not the saved preference of individual fields. If you modify the default, you need to re-save the affected field groups for the new default to apply.

Type: Filter

Availability: ACFML 2.0.0

Parameters:

$fieldTranslationPreference (int) (Required) The default translation preference for the field. Possible values:

• 0 — Don’t translate. WPML ignores the field entirely.
• 1 — Copy. The field value is copied to all languages and stays in sync.
• 2 — Translate. The field value is made available for translation.
• 3 — Copy once. The field value is copied to all languages once, after which it can be edited in each language independently.

$groupMode (string) (Required) The field group translation mode. Possible values: translation or localization.
$field (array) (Required) The ACF field array.

Hook Example Usage:

add_filter( 'acfml_field_group_mode_field_translation_preference', function( $fieldTranslationPreference, $groupMode, $field ) {
    $fieldType = $field['type'] ?? null;

    if ( 'link' === $fieldType ) {
        return 2; // WPML_TRANSLATE_CUSTOM_FIELD
    }

    return $fieldTranslationPreference;
}, 10, 3 );

This example forces the link field type to be translatable, overriding its default copy or copy_once preference.

ACF Multilingual (ACFML) Constants

ACFML_EXCLUDE_FIELD_GROUP_STRINGS_IN_POST_JOBS

Starting with ACFML 2.1.5, you can use this constant to include field group strings in the post translation job.

To enable this, add the following line to your wp-config.php file:

define( 'ACFML_EXCLUDE_FIELD_GROUP_STRINGS_IN_POST_JOBS', false );

Notes:

• If you created a translation job before adding this code to your wp-config.php file, cancel it and create a new one.
• You can send field labels and choices for translation via the Translation Dashboard if needed.

ACFML_HIDE_FIELD_ANNOTATIONS

To each translated field, ACF Multilingual adds information about the value in the original language. 

To remove this information from translated fields, you can add the following line to your site’s wp-config.php file:

define( 'ACFML_HIDE_FIELD_ANNOTATIONS', true );

ACFML_REPEATER_SYNC_DEFAULT

You can use this constant to set the default value of the Repeater field sync feature. It is set to true by default. This means that the Repeater fields are automatically synced across translations. If you set this constant to false, the Repeater field sync will be disabled.

You can override the default value of ACFML_REPEATER_SYNC_DEFAULT in your theme’s functions.php file:

define('ACFML_REPEATER_SYNC_DEFAULT', false);

ACFML_SCAN_LOCAL_FIELDS

Setting this constant to false disables scanning of JSON files for local fields.

This means that if you change the translation preference in local fields, it won’t sync to the database. You need to set the translation preference manually for fields. 

For more information check out the official ACF documentation about using local JSON.