配置 WPML 与 WordPress 主题和插件的兼容性 – 设置和自定义 wpml-config.xml

此页面针对其他情况而设：较冷门的主题和插件、作者在 WPML 兼容性更新之前发布的最新版本，以及少数针对遇到特定症状的网站的通用辅助工具。大多数客户永远不需要访问这里。如果您来到这里，通常是因为 WPML 支持团队指示您开启特定的切换开关或粘贴 wpml-config.xml。

有两个“设置”子页面涉及兼容性，本页面将涵盖这两个子页面。设置 > 兼容性包含针对常见症状的切换开关。设置 > 自定义 XML 配置是您编写自己的 wpml-config.xml 的地方 – 本页面的后半部分对此进行了说明。最常见默认设置（每种文章类型、每种分类法、每个字段的翻译首选项）的 UI 位于一个单独的“设置”页面中，在翻译哪些内容和不翻译哪些内容中有详细说明；大多数客户使用该 UI，只有在它无法满足需求时才会来到这里。

兼容性切换开关

打开 WPML > 设置 > 兼容性。该页面有四张卡片。每张卡片针对一类特定的兼容性问题。

本地化选项 – 针对翻译无法加载的主题和插件

当主题或插件已经包含其自身的 UI 翻译（/languages/ 文件夹中的 .mo 文件），但这些翻译未在您的网站上显示时，本地化选项卡片提供了三个切换开关，帮助 WPML 查找并应用它们。

• 使用 load_textdomain 自动加载主题的 .mo 文件。强制 WPML 为主题的文本域调用 load_textdomain()。当主题的翻译已存在于磁盘上但未显示时使用。
• 输入文本域。覆盖自动检测到的文本域。某些主题以非标准方式注册其文本域；此字段允许您明确指定它。
• 当 gettext 调用不使用字符串字面量时，使用主题或插件文本域。这是一个兼容性标志，适用于使用带变量参数而非字符串字面量的 __() 调用的主题/插件。WPML 无法自动检测这些内容，而此切换开关可帮助它强制应用翻译。

如果 WPML 支持团队引导您来到这里，他们会告诉您要设置哪个切换开关和哪个文本域。

使主题实现多语言功能

调整ID以实现多语言功能。这是针对硬编码单语言假设的主题（例如，某个主题只存储一次“特色图像 ID”，并在每种语言中使用相同的图像）的兼容性层。

大多数现代且兼容 WPML 的主题不需要此功能。较旧或对 WPML 兼容性较差的主题有时需要。如果您看到内容引用（图像、菜单、特色项目）在不同语言之间错误地串用，请开启此功能。

AJAX 操作的语言过滤

存储语言 cookie 以支持 AJAX 的语言过滤。某些插件使用 AJAX 来获取内容：过滤后的产品列表、AJAX 分页的文章列表、边输入边搜索的结果。如果没有语言 cookie，AJAX 端点就不知道该以哪种语言响应，从而返回错误语言的结果。

如果您看到以下症状，请开启 cookie：法语页面上的访问者从 AJAX 加载的部分获得了英语结果。这是一个只需勾选一个复选框即可修复一整类错误的解决方案。

登录和注册页面

允许翻译登录和注册页面。WordPress 内置的 /wp-login.php 和注册屏幕不属于 WPML 翻译的常规内容。它们位于主题的模板链之外。此切换开关将它们添加到 WPML 的可翻译页面集合中。

如果您的网站在 nginx 上运行，此切换开关还需要调整服务器配置。该页面链接到 WPML 的 nginx 指南，其中包含确切的配置块。

主题和插件文本 – 在此处设置，在其他位置扫描

两种主题/插件字符串工作分布在两个屏幕上：

• 此页面上的设置。它们处理主题/插件已包含的翻译的兼容性：load_textdomain、文本域覆盖、非字面量 gettext。
• 扫描器位于单独的屏幕中。当您需要查找尚未注册翻译的主题和插件字符串时，请使用管理文本翻译屏幕。您可以从翻译中的字符串选项卡下方的“没有看到您要查找的字符串？”部分进入该屏幕。

有关完整的字符串扫描工作流，请参阅翻译字符串。

自定义 wpml-config.xml

兼容 WPML 的主题和插件附带一个 wpml-config.xml 文件，该文件准确告知 WPML 它们的哪些字段、文章类型、分类法、简码和元数据键应该是可翻译的。WPML 在激活时会读取该文件。对于所有主流和热门的主题和插件，这意味着翻译功能开箱即可正常工作。您无需执行任何操作。

当主题或插件附带的 wpml-config.xml 不足以满足您的网站需求时，您可以编写自己的文件。WPML 会将其应用在主题或插件附带的配置之上。

何时需要编写自己的 wpml-config.xml

有三种情况。

• 您需要翻译的字段不在附带的 wpml-config.xml 中。主题或插件的作者未将某个自定义字段声明为可翻译，但您需要在网站上翻译它。
• 字段的默认设置错误。附带的 wpml-config.xml 将某些内容标记为复制，而您希望将其标记为翻译，反之亦然。
• 您正在构建自定义主题或插件，并且希望从 WPML 的“设置”页面声明其翻译行为，而不是将 wpml-config.xml 文件与代码捆绑在一起。

在每种情况下，WPML 支持团队都可能会引导您来到这里，并提供要粘贴的确切 wpml-config.xml。这通常是由支持团队驱动的操作，偶尔也是由开发人员驱动的操作。

为什么要在 WPML 的管理后台中编辑 wpml-config.xml 而不是在主题文件中编辑

您可以直接编辑主题或插件自身的 wpml-config.xml。但是，在下次主题或插件更新时，该更改将会丢失。WPML 位于 WPML > 设置 > 自定义 XML 配置中的后台编辑器会将您的 wpml-config.xml 叠加在主题或插件附带的配置之上，并且在更新后依然有效。这是进行特定于网站的调整的正确位置。

wpml-config.xml 的结构

该页面是一个 XML 编辑器。粘贴 <wpml-config>...</wpml-config> 块，保存后，WPML 就会应用您的 wpml-config.xml。

一个将简码声明为可翻译的最小 wpml-config.xml：

<wpml-config>
  <shortcodes>
    <shortcode>
      <tag>add_to_cart_link</tag>
    </shortcode>
  </shortcodes>
</wpml-config>

您通常会声明的元素类型：

• <custom-fields>。将自定义字段标记为 translate、copy、copy-once 或 nothing。
• <custom-types>。将自定义文章类型声明为可翻译。
• <taxonomies>。将自定义分类法声明为可翻译。
• <shortcodes>。列出 WPML 应该翻译其内容的简码。
• <custom-term-fields>。用于术语元数据。

每个元素都有其自身的属性（例如，自定义字段上的 action="translate"）。有关完整的 wpml-config.xml 参考（每个元素、每个属性、每个允许的值），请参阅 WPML 开发人员信息。

实用的工作流

如果 WPML 支持团队为您提供了要粘贴的 wpml-config.xml 块：

1. 打开 WPML > 设置 > 自定义 XML 配置。
2. 将他们的 XML 粘贴到现有的 <wpml-config> 块中（如果他们为您提供了完整的块，则替换其内容）。
3. 保存。
4. WPML 会立即应用您的 wpml-config.xml。如果它声明了新的可翻译文章类型或字段，该条目会立即出现在设置 > 文章类型翻译 / 自定义字段翻译中。

如果您正在构建自定义主题或插件，并希望将它的 WPML 配置与代码一起提供，则应将相同的 <wpml-config> 块放入主题或插件根目录下的 wpml-config.xml 文件中。WPML 会在激活时读取它。管理后台中的编辑器用于特定于网站的调整；捆绑的文件则用于主题/插件自身的默认设置。