WPML

ACF Multilingual (ACFML) Constants and Hooks Reference

Updated: October 6, 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 filter decides whether ACFML shows the translated labels of an ACF field or field group. Return false to show the original labels in every language. The field values do not change.

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;
}, 10, 3 );

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 content in every language, translated or Each language has its own content.

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 ( 'url' === $fieldType ) {
        return 1; // WPML_COPY_CUSTOM_FIELD
    }

    return $fieldTranslationPreference;
}, 10, 3 );

This example gives the url field type the Copy preference instead of its recommended Translate 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 Translations 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

This constant sets the default state of the Keep repeater and flexible sub-fields in the same order as the default language checkbox. ACFML shows this checkbox in the ACFML Synchronise translations box of a post that uses the Expert option. The default is true, so the checkbox starts selected. Set the constant to false to start with the checkbox cleared. A choice that you save on a post overrides this default.

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

This constant sets the default of the Sync Translation Preferences for Local Fields setting in ACFTools. Set it to true to sync the translation preferences of local fields (Local JSON and PHP-registered fields) on every admin request. When the constant is not defined or is false, ACFML does not sync them automatically.

A choice that you save in ACFTools overrides this constant. To sync one time, select Sync once now there and click Apply.

For more information check out the official ACF documentation about using local JSON (opens in a new tab).

Written byAmir