为什么你的翻译没有在 WordPress 中显示（故障排除指南）

在 WordPress 开发中，没有什么比“静默失败”更令人沮丧的了。

你做的一切都正确。你翻译了 .po 文件。你将它编译成 .mo 文件。你通过 FTP 将它上传到你的服务器。你清除了你的缓存。

你刷新页面，期望看到西班牙语、法语或德语。 但你看到的却是……英语。

没有错误消息，没有白屏——只是顽固的、未翻译的文本。在你抓狂之前，请阅读本指南。以下是 WordPress 中翻译无法加载的 5 个最常见原因以及如何修复它们。

1. 你命名文件的方式错误

WordPress 对文件命名非常严格。如果你遗漏了一个字符，它将无法加载该文件。

标准格式是：{text-domain}-{locale}.mo

• 文本域（Text Domain）： 这是主题或插件的唯一 ID（例如，woocommerce、twentytwentyfour、my-custom-plugin）。
• 区域设置（Locale）： WP 区域设置代码（例如，es_ES 代表西班牙西班牙语，fr_FR 代表法语）。

常见错误：

• 仅将文件命名为 es_ES.mo（这仅适用于全局 WordPress 核心文件，不适用于插件）。
• 使用错误的破折号：my_plugin_es_ES.mo（下划线）而不是 my-plugin-es_ES.mo（连字符）。
• 猜测文本域。你必须检查插件的代码（style.css 标头或 load_plugin_textdomain 函数）才能找到确切的 slug。

2. 你将文件放在错误的文件夹中

你上传文件的位置与你如何命名它同样重要。WordPress 会按特定顺序在特定目录中查找。

• “安全”系统文件夹： /wp-content/languages/plugins/ 或 /wp-content/languages/themes/。
  • 优点： 这可以防止插件更新。
  • 缺点： 你必须将文件命名为 textdomain-locale.mo。
• 作者文件夹： /wp-content/plugins/plugin-name/languages/。
  • 优点： 容易找到。
  • 缺点： 危险。 当你更新插件时，此文件夹将被完全清除。你的翻译将会消失。

最佳实践： 始终将你的自定义 .mo 文件放在全局 /wp-content/languages/ 目录中，以防止更新期间的数据丢失。

3. “静默杀手”：.po 文件中的语法损坏

这是最难调试的问题，并且经常发生在通用 AI 翻译工具中。

WordPress 读取二进制 .mo 文件，这些文件是从 .po 文本文件编译而来的。如果你的 .po 文件包含语法错误，则可能会生成 .mo 文件，但它在内部会“损坏”。

这是如何发生的？ 如果翻译人员（无论是人类还是 AI）弄乱了 Gettext 格式，则该字符串将变为无效。

• 示例： 缺少右引号 "。
• 示例： 打断变量（将 %s 更改为 % s）。
• 示例： 搞乱了 msgid_plural 计数。

当 WordPress 在 .mo 文件中遇到损坏的条目时，它通常会跳过它或停止读取整个文件，从而恢复为原始英语。

4. 你忘记编译（.po vs .mo）

WordPress 无法直接读取 .po 文件。这是一个常见的误解。

• .po = 人类可读（Portable Object）。
• .mo = 机器可读（Machine Object）。

如果你上传 my-theme-es_ES.po 文件但忘记生成匹配的 .mo 文件，则什么也不会发生。你必须编译它。

5. 缓存（常见的嫌疑人）

如果你使用的是缓存插件（WP Rocket、LiteSpeed）或服务器端缓存（Varnish、Redis），你的网站可能正在提供 在你上传翻译之前 的缓存 HTML 版本。

修复： 清除所有缓存，包括你的浏览器缓存和对象缓存。

最终修复：从一开始就使用有效的文件

排除文件路径和名称故障很容易。排除损坏的语法故障（原因 #3）是一场噩梦。

如果你使用的工具破坏了你的代码变量或损坏了 Gettext 结构，你将花费数小时想知道为什么该文件不起作用，而没有意识到该文件本身已被“污染”。

这就是我们构建 SimplePoTranslate 的原因。

• 语法锁定： 我们确保每个字符串在您下载之前都具有语法有效性。我们锁定像 %s 这样的变量，因此它们不会被破坏。
• 完美格式： 我们生成干净、标准的 .po 文件，这些文件 100% 的时间都可以编译成有效的 .mo 文件。
• 无需插件： 你下载文件，并且知道它可以工作。你只需要将其上传到正确的文件夹即可。
• WordPress 插件： 想要完全跳过手动上传吗？我们的官方 SimplePoTranslate WordPress 插件会自动检测你的主题和插件 .pot 文件，在云中翻译它们，并将结果部署到正确的目录，并使用正确的文件名。不再有错误命名的文件，不再有错误的文件夹路径——这是翻译无法显示的两个最常见原因。

不要再猜测为什么你的翻译是不可见的。从你可以信任的文件开始。

准备好轻松翻译了吗？在 SimplePoTranslate.com 免费开始