WPML

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

WPML 开箱即用，兼容所有主流和热门的 WordPress 主题与插件。在运行 Elementor、WooCommerce、Yoast、Gravity Forms 或 ACF 的网站上安装 WPML，翻译功能即可正常运行。您无需修改此页面上的任何设置。

此页面专为其他情况而设：较冷门的主题和插件、在 WPML 兼容性更新前发布的最新版本，以及为出现特定症状的网站提供的少量通用辅助工具。大多数客户永远不会来到这里。当您访问此页面时，通常是因为 WPML 支持团队建议您开启某个特定开关或粘贴一段 wpml-config.xml。

有两个“设置”子页面涉及兼容性，本页面将涵盖这两者：

  • WPML设置兼容性包含针对常见症状的开关。
  • WPML设置自定义 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设置自定义字段翻译 中。

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

作者：Amir

作者：Amir