如何在 WordPress 中翻译 ACF 自定义字段 – 字段组、Repeater、选项页面

开始之前

安装并激活以下插件：

• Advanced Custom Fields 或 ACF Pro。
• WPML 和 WPML 字符串翻译。
• ACFML（本页面介绍的附加组件）。

您的字段组应该已经在 ACF 中配置完毕。您可以之后随时更改每个字段的翻译首选项，因此操作顺序并不重要。请先设置字段组，然后再回到 ACFML。

为每个字段组选择翻译模式

在翻译时，并非所有 ACF 字段组的行为都相同。ACFML 为每个字段组提供了三种模式，可在 ACF → 字段组（Field Groups）的 Multilingual Setup（多语言设置）部分进行设置：

跨语言相同的字段

这是大多数 ACF 网站的典型设置。将字段值翻译成每种语言，同时保持结构不变。“我们的团队”（Our Team）页面就是一个典型示例。您的团队在每种语言中都是相同的，因此每个团队成员的姓名和简介都会按语言进行翻译，而字段结构保持完整。您使用源语言输入团队信息，然后通过 WPML → 翻译 → 仪表板发送文章进行翻译；翻译后的值将返回并附加到相同的字段上。

跨语言不同的字段

适用于每种语言在同一字段组中显示完全不同内容的情况。典型的案例是举办本地化活动的公司。英文的“活动”（Events）页面显示面向英语受众的活动，法文页面显示面向法语受众的活动。将字段组设置为跨语言不同的字段（Different fields across languages），然后打开您要本地化的文章 → 在右侧的“语言”框中，单击目标语言的加号图标 → 系统会打开一个自定义字段为空的空白草稿 → 填写特定语言的值并发布。

专家模式

适用于需要混合设置的情况：某些字段按语言翻译，有些保持不变，还有一些复制一次后各自独立。在字段组设置中选择专家模式（Expert Mode），并为每个字段设置首选项。具有混合行为的“活动”示例：标题和说明设置为翻译（Translate）；价格、日期和地址设置为复制（Copy）。

每种 ACF 字段类型的翻译首选项

字段组中的每个字段都有以下四种翻译首选项之一：

• 翻译（Translate）。字段的值按语言进行翻译。
• 复制（Copy）。字段的值在不同语言之间保持同步；编辑一次即可应用到所有语言。
• 复制一次（Copy Once）。字段的值作为翻译的初始内容，随后可以独立编辑每种语言版本。
• 不翻译（Don't translate）。翻译过程中将忽略该字段。

当您选择跨语言相同的字段或跨语言不同的字段时，每个字段都会根据字段类型采用合理的默认首选项。下表显示了这些默认值。使用专家模式可针对每个字段覆盖这些默认值，或者使用 acfml_field_group_mode_field_translation_preference 过滤器在全站范围内覆盖某种字段类型的默认值（请参阅下文的针对边缘情况的开发者钩子）。

Repeater 和 Flexible Content – 复制或复制一次

对于中继器（Repeater）和灵活内容（Flexible Content）字段，在子字段首选项生效之前，需要先在两种行级行为中做出选择：

• 复制。每种语言具有相同的布局和行数。译者看到的是相同的行；子字段根据其自身的首选项进行翻译。
• 复制一次。在初始生成后，每种语言可以有不同的布局和不同的行数。

当跨语言的结构相同时（大多数情况），请选择复制。当各语言版本的结构存在差异时（例如，每种语言有不同的活动列表），请选择复制一次。

基本字段

内容字段

选择字段

jQuery 字段

布局字段

关系字段

为在 PHP 或 JSON 中注册的字段设置首选项

在 PHP（通过 acf_add_local_field_group()）或通过 ACF 的 Local JSON 功能注册的 ACF 字段组不会从管理后台 UI 获取翻译首选项，因为管理后台并不管理这些字段。请在注册字段的同一位置设置首选项。

对于字段组定义中的每个字段，添加一个 wpml_cf_preferences 键。其值为一个整数，映射到四种翻译首选项：0 代表不翻译（WPML 忽略该字段），1 代表复制（值在不同语言之间保持同步），2 代表翻译（值进行翻译），3 代表复制一次（值复制到新的翻译中，然后每种语言可以独立编辑）。

一个最简示例：

acf_add_local_field_group( [
    'key'    => 'group_1',
    'title'  => 'My Group',
    'fields' => [
        [
            'key'                 => 'field_1',
            'label'               => 'Sub Title',
            'name'                => 'sub_title',
            'type'                => 'text',
            'wpml_cf_preferences' => 2, // Translate.
        ],
    ],
    // ...rest of the field-group config
] );

在代码中定义字段后，需要将首选项同步到 WPML，以便管理后台能够识别：

1. 前往 ACF → 工具（Tools）。
2. 滚动到 Translate ACF Local JSON and PHP-Registered Fields。
3. 在 Sync Translation Preferences for Local Fields 中，选择 Sync once now，然后单击应用（Apply）。

WPML 会从您的 PHP 定义中读取首选项并将其存储起来。同步操作仅在您触发时运行一次，而不是在每次加载页面时运行。

如果您使用 ACF 的 Local JSON 功能在站点之间共享字段组，ACFML 会自动将翻译首选项写入 JSON 文件中。从一个站点导出 JSON 文件，再导入到另一个站点；只要两端都激活了 ACFML，目标站点就会获取这些首选项。

翻译 ACF 字段标签

ACF 字段标签是用于在 WordPress 编辑器和前端标识每个自定义字段的名称（例如，电话号码、地址）。它们与字段值分开翻译，存放在 WPML 字符串翻译中，而不在文章的翻译任务里。

要发送字段标签进行翻译：

1. 打开 WPML → 翻译 → 仪表板。
2. 展开 ACF Field Group 部分。
3. 选择您要翻译的字段组的 Field Group Labels 项。
4. 选择一种翻译方法（PTC、您的译员或自己翻译），然后发送。

翻译完成后，译好的标签会自动显示在前端。

翻译 ACF 字段选项

选择字段（选择、复选框、单选按钮、按钮组）带有自己的选项标签（例如，小 / 中 / 大）。这些内容同样与字段标签存放在一起，而不在文章翻译中。以相同的方式发送它们：

1. 打开 WPML → 翻译 → 仪表板。
2. 展开 ACF Field Group 部分。
3. 选择您要翻译其选项值的字段组。
4. 选择一种翻译方法并发送。

翻译 ACF 选项页面

ACF 选项页面（全局设置界面，如联系方式、页眉设置、页脚链接）作为其自身的对象类型进行翻译，与文章分开：

1. 打开 WPML → 翻译 → 仪表板。
2. 展开 ACF Options 部分。
3. 选择您要翻译的选项页面。
4. 选择一种翻译方法并发送。

当 ACF 在特定语言的上下文中读取选项时，每种语言的选项页面值会自动显示。

常见陷阱

• 字段标签看起来未翻译。它们位于字符串翻译中，而不是文章翻译中。从仪表板发送字段组的 Field Group Labels 项（请参阅上文的翻译 ACF 字段标签）。
• 选项值看起来未翻译。情况相同。从仪表板的 ACF Field Group 部分发送字段组，以便包含选项值。
• Repeater 行不同步。该字段很可能设置成了复制一次，而使用复制才能保持行对齐。打开字段组 → 将 Repeater 字段的行为切换为复制。
• 条件逻辑行为异常。当控制字段设置为复制或不翻译时，条件行为将在所有翻译中遵循源语言的值。如果控制字段的值应因语言而异，请将其设置为翻译。
• 本地字段（在 PHP 中注册）忽略在管理后台中设置的翻译首选项。请在字段组定义本身中设置 wpml_cf_preferences 键，并从 ACF → 工具进行同步。具体步骤请参阅上文的为在 PHP 或 JSON 中注册的字段设置首选项。ACFML 2.2.0（2026年2月）添加了对本地字段的全面支持；旧版本在此处存在限制。

针对边缘情况的开发者钩子

为了实现编程式控制（让特定字段不参与翻译、在全站范围内覆盖字段类型的默认首选项、向译者隐藏注释或从文章翻译任务中排除字段组字符串），ACFML 提供了两个过滤器和四个常量。包含代码示例的完整参考资料位于 ACFML 钩子和常量参考。