如何在 WordPress 中翻译 ACF 自定义字段——字段组、中继器和选项页面

开始之前

安装并激活以下插件：

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

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

为每个字段组选择一个翻译选项

ACF 字段组在翻译时的表现并不完全相同。ACFML 为每个字段组提供三种翻译选项。要选择一个选项：

1. 前往 ACF → 字段组，编辑该字段组。
2. 在 Multilingual Setup 部分的 Select a translation option for this field group 下方，单击所需选项上的 Choose。
3. 保存该字段组。

ACFML 会将建议您的网站使用的选项标记为 recommended for this site。如果以后需要选择其他选项，请单击 Change option。较旧的 ACFML 版本将前两个选项称为 Same fields across languages 和 Different fields across languages。

在每种语言中显示相同的翻译内容

这是大多数 ACF 网站的典型设置。使用各种语言的访客都能以自己的语言看到相同的页面。文本会被翻译，而布局和设置保持不变。Our Team 页面就是常见的例子。您的团队在每种语言中都是相同的，因此只需翻译每位团队成员的姓名和简介，且字段结构保持不变。您可以使用默认语言输入团队信息，然后从 WPML → 翻译 → 仪表板 发送文章进行翻译。翻译后的值会返回到相同的字段中。此选项适用于自动翻译和翻译所有内容。

每种语言都有各自的内容

当每种语言在同一个字段组中显示不同内容时，请使用此选项。常见的例子是举办本地活动的公司。英语的 Events 页面显示面向英语受众的活动，而法语页面显示面向法语受众的活动。字段最初是原始内容的副本。之后，每种语言将保留其各自的值。您可以在 WordPress 编辑器中编辑每种语言：打开文章，单击语言框中目标语言的加号图标，填写该语言的值，然后发布。此后 WPML 不会同步语言版本，且自动翻译也不适用。

专家

当您需要混合设置时请使用此选项：某些字段需要翻译，某些保持不变，还有一些复制一次后在每种语言中进行更改。选择专家并手动设置每个字段的翻译首选项。在 Events 示例中，标题和说明使用翻译，而价格、日期和地址使用复制。ACFML 不建议新字段组使用此选项。在 PHP 或本地 JSON 中定义的字段组可以没有翻译选项。此时，仅当字段组在您的网站更新到 WPML 5.2 之前就已经存在时，它才会使用专家选项。

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

每个存储值的字段都有以下四种翻译首选项之一：

• 翻译。访客会以他们自己的语言看到该值。WPML 会使用翻译内容来填充它。您可以在翻译编辑器中对其进行编辑。
• 复制。使用各种语言的访客看到的完全是原始内容显示的内容。该字段在其他语言中被锁定。
• 复制一次。该值最初是原始内容的副本。之后，您可以在每种语言中手动对其进行编辑。如果您在某个翻译中清空了该字段，它将保持为空。WPML 不会再次将原始值复制到其中。
• 不翻译。翻译开始时没有此值。您可以在每种语言中手动填写它。

当您选择在每种语言中显示相同的翻译内容或每种语言都有各自的内容时，ACFML 会为每个字段提供其字段类型推荐的首选项。下表显示了这些推荐的首选项。要为一个字段设置不同的首选项，请使用专家。要更改整个网站上某种字段类型的推荐首选项，请使用 acfml_field_group_mode_field_translation_preference 过滤器（请参阅下文的边缘情况的开发者钩子）。

选项卡、手风琴、消息和分隔符字段不存储值，因此它们没有翻译首选项。表格中未列出的字段类型（例如来自其他插件的字段类型），在两种翻译选项下都会被设置为复制。

中继器、灵活内容、组和克隆字段

这些字段包含其他字段。容器字段的推荐首选项是复制或复制一次。ACFML 不为容器字段本身提供翻译选项。每个子字段都有自己的翻译首选项。

使用在每种语言中显示相同的翻译内容时，中继器和灵活内容字段的行将保持与默认语言相同的顺序。使用专家时，或者当文章使用具有不同选项的字段组时，文章编辑器会显示一个 ACFML Synchronise translations 框。当文章有翻译且包含中继器或灵活内容字段时，它会显示在原始文章上。选择 Keep repeater and flexible sub-fields in the same order as the default language，以使所有语言中的行保持对齐。

基本字段

内容字段

选择字段

jQuery 字段

布局字段

关系字段

对于链接字段，翻译涵盖链接文本和 URL。当 URL 指向您网站上的某个页面且您未更改它时，WPML 会以访问者的语言显示该页面。

URL 和链接字段

从 ACFML 5.0 开始，URL 和链接字段默认使用翻译首选项。

双向关系

从 ACF 6.2 开始，关系、文章对象、分类法和用户字段可以是双向的。当您在字段中选择一个目标时，ACF 会将您的文章添加到该目标的配对字段中。例如，书籍 Dune 将其 Author 字段设置为 Frank Herbert。然后，ACF 会将 Dune 添加到 Frank Herbert 的 Books 字段中。

ACFML 会在每种语言中保留该配对：

• 当 WPML 将字段复制到翻译中时，ACFML 会将该字段指向相同语言的目标。然后，ACFML 会将翻译添加到该目标的配对字段中。西班牙语的 Dune 会显示西班牙语的 Frank Herbert，而西班牙语的 Frank Herbert 会列出西班牙语的 Dune。
• 当字段使用复制并且您更改了原始文章中的目标时，WPML 会更新翻译。ACFML 会将翻译添加到该语言的新目标中，并将其从旧目标中移除。
• ACFML 仅更改翻译语言中的目标。原始语言的文章会保留其自己的配对。
• 当目标尚未翻译时，翻译将指向原始目标，并且 ACFML 不会更改原始目标。当您稍后翻译该目标时，ACFML 会将字段指向新的翻译，并将文章添加到其配对字段中。该字段会列出该目标一次。
• 用户没有翻译，因此 ACFML 不会将翻译添加到用户的配对字段中。该字段会保留原始文章。在另一种语言中，ACFML 会显示该文章的翻译，除非该字段使用复制。

这适用于复制和复制一次首选项，它们是这些字段类型的推荐首选项。当您使用 WPML 复制文章时，这也同样适用。

翻译 ACF 区块

默认情况下，ACF 区块将其字段值保存在区块内部的文章内容中，而不是作为自定义字段。ACFML 会在同一个翻译任务中，将这些值与文章的其余部分一起发送以进行翻译。

• 该区块使用位置规则为该区块的字段组的翻译选项和字段首选项。
• ACFML 仅发送使用翻译的字段。使用复制、复制一次或不翻译的字段将保留原始区块中的值。
• 区块内的中继器和灵活内容字段也会被翻译，即使它们是嵌套的。每个子字段都使用其自己的翻译首选项。
• 在 block.json 的 acf 部分中带有 "usePostMeta": true 的区块，会将其值保存为文章的自定义字段，而不是保存在区块中。这些值会像文章的任何其他自定义字段一样，使用字段组的翻译选项和字段首选项进行翻译。
• 当您更改在区块上使用的字段组中的翻译首选项时，WPML 会询问您是否要更新现有翻译。如果您确认，WPML 会将这些文章的翻译标记为需要更新。再次发送它们进行翻译以应用更改。更改为不翻译不会标记它们。

在 block.json 中声明的字段

从 ACF 6.8.1 开始，区块可以在其 block.json 文件的 acf.fields 中声明其字段。ACF 会为这些字段创建一个字段组，并且您无法在管理后台中编辑此字段组。ACFML 会为其提供每种语言的内容相同，已翻译选项以及每种字段类型的推荐首选项，就像在 PHP 中注册的字段组一样。

要为整个组使用另一个选项，请将 acfml_field_group_mode 添加到 block.json 的 acf 部分或 acf_register_block_type() 中。接受的值为 translation（每种语言的内容相同，已翻译）、localization（每种语言都有自己的内容）和 advanced（专家）。ACFML 会忽略任何其他值。

{
    "name": "acme/event-card",
    "title": "Event Card",
    "acf": {
        "mode": "preview",
        "acfml_field_group_mode": "localization",
        "fields": [ ... ]
    }
}

要设置一个字段的首选项，请将 wpml_cf_preferences 添加到该字段。ACFML 会在每个选项中保留此首选项。使用专家选项时，只有声明了 wpml_cf_preferences 的字段才会获得首选项。

当 block.json 未指定选项时，ACFML 会存储其首次看到该组时赋予该组的选项，并在之后保留它。在使用旧版 ACFML 版本且包含这些区块的网站上，存储的选项为专家。

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

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

要设置字段组的翻译选项，请向定义中添加 acfml_field_group_mode 键，并使用 translation、localization 或 advanced（Expert）。如果定义未设置翻译选项，ACFML 会在首次看到该字段组时为其分配 Same content in every language, translated 选项。ACFML 会存储此选项并在此后保留它。在您的站点更新到 WPML 5.2 之前存在的字段组将保留 Expert。

对于字段组定义中的每个字段，请添加 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 → 工具。
2. 滚动至 Translate ACF Local JSON and PHP-Registered Fields。
3. 在 Sync Translation Preferences for Local Fields 中，选择 Sync once now 并单击应用。

WPML 会从您的字段定义中读取首选项并将其存储起来。Sync once now 仅运行一次。如果您经常更改定义，请改为选择 Sync on every request (may affect performance)。此选项会在每次管理后台请求时运行同步。

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

ACF 使用 wp acf json import WP-CLI 命令或通过其面向 AI 工具的 Abilities API 创建的字段组存储在数据库中。ACFML 会为它们分配 Same content in every language, translated 选项以及针对每种字段类型的推荐首选项。如果导入的 JSON 已经包含 acfml_field_group_mode 键，ACFML 将改用该选项。

Local JSON 文件中的字段组

ACF 在每次请求的很早阶段就会加载 acf-json 文件夹中的字段组。从 WPML 5.2 开始，ACFML 会在同一时间读取这些字段组。因此，当您同步翻译首选项时，同步也会涵盖 JSON 字段组。然后，WPML 会使用 JSON 文件中的首选项。

在 JSON 文件中，向每个字段添加 wpml_cf_preferences，其值与 PHP 中的相同。无论字段组的翻译选项是什么，此键都会设置每个字段的首选项。该示例使用 Expert：

{
    "key": "group_event",
    "title": "Event",
    "acfml_field_group_mode": "advanced",
    "fields": [
        {
            "key": "field_event_title",
            "label": "Event Title",
            "name": "event_title",
            "type": "text",
            "wpml_cf_preferences": 2
        },
        {
            "key": "field_event_price",
            "label": "Price",
            "name": "event_price",
            "type": "number",
            "wpml_cf_preferences": 1
        }
    ]
}

要将 JSON 字段组的首选项和标签发送到 WPML：

1. 前往 ACF → 工具。
2. 滚动至 Translate ACF Local JSON and PHP-Registered Fields。
3. 在 Sync Translation Preferences for Local Fields 中，选择 Sync once now 或 Sync on every request (may affect performance)。
4. 在 Register Labels for Translation 中，选择 Register labels now。
5. 单击应用。

要检查结果，请前往 WPML → 设置 并在自定义字段翻译中找到这些字段。每个字段都会显示来自 JSON 文件的首选项。ACFML 还会注册仅存在于代码中的字段组、文章类型、分类法和 Options Pages 的标签：位于 acf-json 文件夹中或在 PHP 中注册。像翻译任何其他字段组的标签一样翻译它们（请参阅下文的翻译 ACF 字段标签）。

翻译 ACF 字段标签

ACF 字段标签是在 WordPress 编辑器和前端识别每个自定义字段的名称（例如，Phone number、Address）。它们与字段值分开翻译，并且位于 WPML 字符串翻译中，而不是在文章的翻译任务中。

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

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

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

停止翻译字段标签

默认情况下，文章的翻译作业不包含字段标签。只有从仪表板发送 Field Group Labels 项目时，才会翻译它们。如果不发送，ACF 会显示原始标签。要在存在翻译时仍显示原始标签，请使用 acfml_should_translate_acf_entity 过滤器并为要跳过的字段或字段组返回 false。ACFML 钩子和常量参考中提供了一个示例。

翻译 ACF 字段选项

选择类字段（Select、Checkbox、Radio Button、Button Group）带有自己的选项标签（例如 Small / Medium / Large）。这些标签也与字段标签存放在一起，而不是在文章翻译内。请以相同的方式发送它们：

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

翻译 ACF 选项页面

ACF 选项页面（如 Contact details、Header settings、Footer links 等全局设置屏幕）作为其自身的对象类型进行翻译，与文章分开：

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

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

选项页面上字段组的翻译选项决定了每个字段的处理方式：

• 使用 翻译 的字段会进入您从翻译仪表板发送的 ACF Options 项目中。翻译完成后，ACFML 会将值写入该语言的选项页面。Repeater 和 Flexible Content 字段会获得与原始内容相同的行。
• 使用 复制 的字段会在每种语言中获取原始值。保存原始内容时，ACFML 会更新其他语言。
• 使用 复制一次 的字段最初作为原始内容的副本。之后，您可以在每种语言的选项页面上对其进行编辑。

当选项因语言而异时，请使用 Each language has its own content。例如，选项页面在英语中列出了三名销售代理，在西班牙语中列出了两名。要选择该选项，请像编辑任何其他字段组一样编辑该字段组。

要更改已完成的翻译，请前往 WPML → 翻译 → 翻译作业，并在 ACF Options 作业上单击编辑。您也可以在 WPML → 字符串翻译 中编辑翻译后的值。当您在那里保存翻译时，ACFML 会将其写入该语言的选项页面。

更改网站的默认语言时，现有的选项页面值将保留在您编写它们时使用的语言中。ACF 会读取与更改前相同的值。

在代码中，get_field( 'my_field', 'option' ) 会返回当前语言的值。在 do_action( 'wpml_switch_language', 'fr' ) 之后，它会返回法语值。这也适用于具有自定义 post_id 的选项页面。

常见陷阱

• 字段标签看起来未翻译。 它们位于字符串翻译中，而不是文章翻译中。请从仪表板发送字段组的 Field Group Labels 项目（请参阅上文的翻译 ACF 字段标签）。
• 选项值看起来未翻译。 情况相同。从仪表板的 ACF Field Group 部分发送该字段组，以便包含选项值。
• Repeater 行不同步。 字段组可能使用了 Expert。编辑原始文章，在 ACFML Synchronise translations 框中选择 Keep repeater and flexible sub-fields in the same order as the default language，然后更新文章。或者将字段组切换为 Same content in every language, translated。
• 条件逻辑行为异常。 当控制字段设置为 复制 或 不翻译 时，条件行为将在所有翻译中遵循源语言的值。如果控制字段的值因语言而异，请将其设置为 翻译。
• 本地字段（通过 PHP 注册）忽略在管理后台中设置的翻译首选项。 请在字段组定义本身中设置 wpml_cf_preferences 键，并从 ACF → 工具 进行同步。具体步骤请参阅上文的设置通过 PHP 或 JSON 注册的字段的首选项。

开发者钩子

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