WPML

ACF Multilingual (ACFML) 常量和钩子参考

更新日期：2026年10月6日

探索 ACF Multilingual (ACFML) 常量和钩子的完整列表，以及在代码中使用它们的示例。

ACF Multilingual (ACFML) 钩子

acfml_should_translate_acf_entity

此过滤器决定 ACFML 是否显示 ACF 字段或字段组的已翻译标签。返回 false 以在所有语言中显示原始标签。字段值不会改变。

类型：过滤器

可用版本：ACFML 2.1.4

参数：

$shouldTranslate
(bool)（必填）是否应翻译该字段或字段组。默认为 true。

$entity
(array)（必填）正在翻译的实体，可以是字段数组或组数组。

$entityType
(string)（选填）正在翻译的实体类型。它可以是“field”或“group”。

钩子使用示例：

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

当字段组使用在所有语言中保持相同内容，已翻译或每种语言都有自己的内容时，此过滤器允许您覆盖 ACF 字段的默认翻译首选项。

注意：此过滤器仅更改默认翻译首选项，而不会更改各个字段已保存的首选项。如果您修改了默认值，则需要重新保存受影响的字段组，以便新的默认值生效。

类型：过滤器

可用版本：ACFML 2.0.0

参数：

$fieldTranslationPreference (int)（必填）字段的默认翻译首选项。可能的值包括：

  • 0 — 不翻译。WPML 将完全忽略该字段。
  • 1 — 复制。字段值将被复制到所有语言并保持同步。
  • 2 — 翻译。字段值将可供翻译。
  • 3 — 复制一次。字段值将被复制到所有语言一次，之后可以在每种语言中独立编辑。

$groupMode (string)（必填）字段组翻译模式。可能的值包括：translation 或 localization。
$field (array)（必填）ACF 字段数组。

钩子使用示例：

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 );

此示例为 url 字段类型赋予了复制首选项，而不是其推荐的翻译首选项。

ACF Multilingual (ACFML) 常量

ACFML_EXCLUDE_FIELD_GROUP_STRINGS_IN_POST_JOBS

从 ACFML 2.1.5 开始，您可以使用此常量将字段组字符串包含在文章翻译任务中。

要启用此功能，请将以下代码行添加到您的 wp-config.php 文件中：

define( 'ACFML_EXCLUDE_FIELD_GROUP_STRINGS_IN_POST_JOBS', false );

注意：

  • 如果您在将此代码添加到 wp-config.php 文件之前创建了翻译任务，请将其取消并创建一个新任务。
  • 如果需要，您可以通过翻译仪表板发送字段标签和选项以进行翻译。

ACFML_HIDE_FIELD_ANNOTATIONS

对于每个已翻译的字段，ACF Multilingual 都会添加有关原始语言中该值的信息。

要从已翻译的字段中删除此信息，您可以将以下代码行添加到网站的 wp-config.php 文件中：

define( 'ACFML_HIDE_FIELD_ANNOTATIONS', true );

ACFML_REPEATER_SYNC_DEFAULT

此常量设置保持中继器和灵活子字段与默认语言的顺序相同复选框的默认状态。ACFML 会在使用专家选项的文章的 ACFML 同步翻译框中显示此复选框。默认值为 true，因此该复选框初始为选中状态。将常量设置为 false 可使复选框初始为清除状态。您在文章上保存的选择将覆盖此默认值。

您可以在主题的 functions.php 文件中覆盖 ACFML_REPEATER_SYNC_DEFAULT 的默认值：

define('ACFML_REPEATER_SYNC_DEFAULT', false);

ACFML_SCAN_LOCAL_FIELDS

此常量设置 ACF工具中同步本地字段的翻译首选项设置的默认值。将其设置为 true 以在每次后台请求时同步本地字段（本地 JSON 和 PHP 注册的字段）的翻译首选项。如果未定义该常量或将其设置为 false，ACFML 将不会自动同步它们。

您在 ACF工具中保存的选择将覆盖此常量。要同步一次，请在该处选择立即同步一次，然后单击应用。

有关更多信息，请查看关于使用本地 JSON （在新标签页中打开） 的 ACF 官方文档。

作者：Amir