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 的执行流程如下：
- 加载插件主文件 → 执行 new Application()
- 进入 __construct() → 立即输出未翻译的 'Test Text'
- 继续初始化其他组件……
- 直到 do_action('init') 触发 → 才执行 translate_it() → 此时才调用 load_plugin_textdomain()
因此，首次 __('...') 调用永远发生在加载之前，必然回退为源字符串。
✅ 正确实践：所有翻译调用必须在 init 或之后的钩子中进行
将翻译逻辑移至 translate_it() 内部，并确保其在 init 阶段完成加载后再使用：
构建并排查Microsoft Word邮件合并及DOCX模板工作流，使用合并域、内容控件、文档属性、重复区块、数据等
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，而是其事件驱动架构的必然要求。
