.pot、.po、.mo：WordPress 语言文件的作用与翻译方法

译文完成后未在网站上生效，常见原因是没有编译，或文件名不正确。这两项在本页最后几节说明。

三种文件

• .pot：模板。包含主题或插件中所有可翻译的字符串，译文为空。由开发者从源码生成，使用时复制，不直接修改。
• .po：某一种语言的译文。纯文本，每条原文下方是对应译文。翻译工作在这个文件中进行。
• .mo：.po 的编译结果。二进制格式，不供人阅读。WordPress 加载的是这个文件。

WordPress 6.5 起还有第四种格式：.l10n.php。它加载更快，存在时优先使用，.mo 作为备用。该文件无需手动生成，WordPress 会自动生成，因此语言目录中可能出现未手动添加的文件。

翻译 .pot 文件的步骤

1. 找到 .pot 文件。它通常位于插件或主题目录下的 languages/ 中。
2. 按下一节的命名规则，将其复制为目标语言的 .po 文件。
3. 翻译其中的条目，可在 PO 编辑器中逐条翻译，也可批量翻译。每个占位符都必须与原文完全一致。
4. 将 .po 编译成 .mo，并把两个文件放到 WordPress 读取的位置。未安装 gettext 时，可使用免费的浏览器编译工具。

文件较大时，PO / POT 翻译工具可一次翻译整个文件，并导出为相同格式。工具只发送字符串，不上传文件。

文件命名

WordPress 按 {文本域}-{locale}.mo 查找文件。文件名只要有一个字符不同，WordPress 就不会加载该文件，并直接回退到英文，不显示任何错误或提示。这是译文完成后不生效的最常见原因。

• 文本域由插件或主题自身定义，例如 woocommerce、twentytwentyfive、my-cool-plugin。它声明在插件头部，不一定与文件夹名相同。
• locale 使用 WordPress 的区域代码，而不是两位语言码。简体中文为 zh_CN、英语为 en_US、法语为 fr_FR；日语为 ja、阿拉伯语为 ar、芬兰语为 fi，不带地区码。
• 源文件名已包含 locale 时（如 woocommerce-en_US.po），需先去掉原有 locale 再添加新的，否则会得到 woocommerce-en_US-zh_CN.mo，无法匹配任何语言。

文件存放位置

WordPress 会从两个位置加载译文，两者在插件或主题更新时的表现不同。

• wp-content/languages/plugins/ 和 wp-content/languages/themes/：推荐使用。 WordPress 优先读取这里，插件或主题更新不会覆盖其中的文件。
• 插件或主题自身的 languages/ 目录：同样会被读取，但下次更新会替换整个目录，译文随之丢失。

译文未生效的排查顺序

1. 确认存在 .mo 文件。只有 .po 文件不会产生任何效果。
2. 确认文件名严格符合 {文本域}-{locale}.mo。文本域以插件头部为准，locale 以 WordPress 的区域代码列表为准。
3. 确认站点语言已在 设置 → 常规 中设为该语言。
4. 确认文件位于 wp-content/languages/…。只放在插件目录中的文件，会在插件更新时被删除。
5. 仍未生效时，清除对象缓存和页面缓存。译文在每个请求中只加载一次，并会被缓存。

占位符

显示 %1$s 条，共 %2$s 条 这类字符串包含由 PHP 填入数值的占位符。译文中缺少占位符、未使用编号形式就调换顺序，或把 %s 写成全角的 ％s，都不是显示问题，而是页面上的运行时错误。部署文件前应检查占位符；带有占位符检查的编译工具会标出这类错误。