WordPress 插件翻译不生效？关键在于文本域加载时机与调用顺序

wordPress 自定义插件中翻译未生效，通常并非因 .mo 文件路径或命名错误，而是因 __() 等翻译函数在文本域（text domain）加载前就被执行——即 load_plugin_textdomain() 尚未运行，导致翻译回退为原文。

wordpress 自定义插件中翻译未生效，通常并非因 `.mo` 文件路径或命名错误，而是因 `__()` 等翻译函数在文本域（text domain）加载前就被执行——即 `load_plugin_textdomain()` 尚未运行，导致翻译回退为原文。

在 wordpress 插件开发中，实现多语言支持需严格遵循「先加载、后使用」的执行时序。你提供的代码看似配置完整：Text Domain 声明正确、.pot/.mo 文件位于 /languages/ 目录、load_plugin_textdomain() 返回 true，但 __(‘Test Text’, ‘translated_plugin’) 仍显示原文——根本原因在于 翻译函数调用早于文本域初始化。

? 问题定位：构造函数中的执行陷阱

观察你的 Application 类：

public function __construct() {     add_action('init', [$this, 'translate_it']); // ✅ 注册钩子（延迟执行）     echo __('Test Text', 'translated_plugin');     // ❌ 立即执行！此时 text domain 尚未加载 }

此处 echo 语句在 new Application() 实例化时同步执行，而 add_action(‘init’, …) 仅将回调加入 WordPress 的 init 动作队列，并不立即运行。WordPress 的执行流程如下：

1. 加载插件主文件 → 执行 new Application()
2. 进入 __construct() → 立即输出未翻译的 ‘Test Text’
3. 继续初始化其他组件……
4. 直到 do_action(‘init’) 触发 → 才执行 translate_it() → 此时才调用 load_plugin_textdomain()

因此，首次 __(‘…’) 调用永远发生在加载之前，必然回退为源字符串。

✅ 正确实践：所有翻译调用必须在 init 或之后的钩子中进行

将翻译逻辑移至 translate_it() 内部，并确保其在 init 阶段完成加载后再使用：

class Application {     public function __construct() {         add_action('init', [$this, 'translate_it']);         // ✅ 移除构造函数中的任何 __('...') 调用     }      public function translate_it() {         // 推荐写法：使用 plugin_basename + dirname 安全获取语言目录         $loaded = load_plugin_textdomain(             'translated_plugin',             false,             dirname(plugin_basename(__FILE__)) . '/languages/'         );          if (!$loaded) {             error_log('[Translated Plugin] Failed to load text domain.');         }          // ✅ 此处调用才安全有效         echo '<p>' . __('Test Text', 'translated_plugin') . '</p>';     } }

? 路径说明：dirname(plugin_basename(__FILE__)) . ‘/languages/’ 比嵌套 dirname(dirname(…)) 更清晰可靠。假设插件主文件为 wp-content/plugins/translated_plugin/translated_plugin.php，则该表达式生成相对路径 translated_plugin/languages/，与 Domain Path: /languages 完全匹配。

⚙️ 补充验证与最佳实践

• 确认语言文件命名规范：
  .mo 文件必须命名为 translated_plugin-{locale}.mo（如 translated_plugin-zh_CN.mo），且存放在 wp-content/plugins/translated_plugin/languages/ 下。

• 强制刷新语言缓存：
  修改 .mo 后，清除对象缓存（如使用 WP Super Cache）并切换前台语言（通过用户资料或 URL 参数 ?lang=zh_CN）验证。

• 避免在 plugins_loaded 之前加载：
  load_plugin_textdomain() 应在 init 钩子（推荐）或最晚 plugins_loaded 中调用。init 是标准时机，兼顾主题与插件兼容性。

• 调试技巧：
  在 translate_it() 中添加日志：

  error_log('Text domain loaded: ' . ($loaded ? 'YES' : 'NO')); error_log('Current locale: ' . get_locale());

✅ 总结

WordPress 插件翻译失效的常见根源不是配置错误，而是生命周期认知偏差。牢记黄金法则：

所有 __(), _e(), esc_html__() 等翻译函数，必须在 load_plugin_textdomain() 成功执行之后调用。
将翻译逻辑封装在 init 及之后的钩子中，而非类构造函数或插件主文件全局作用域，即可彻底解决此问题。这并非 WordPress bug，而是其事件驱动架构的必然要求。