wp-cli生成POT文件后pl_PL波兰语翻译设置不生效求助

1. 翻译文件格式/后缀完全错误 #

你将生成的POT模板文件直接重命名为pl_PL.pot的操作，从根源上就不符合WordPress的翻译加载规则：

• POT是供翻译人员参考的源模板文件，WordPress运行时不会扫描、加载任何pot后缀的文件
• 波兰语对应的合法翻译文件必须满足后缀要求：
  • WordPress通用兼容格式：pl_PL.mo（二进制编译格式）
  • WordPress 6.5+ 支持的高性能格式：pl_PL.l10n.php（原生PHP数组格式）
    哪怕你在pl_PL.pot里写满了翻译内容，WordPress也根本找不到要加载的翻译包

2. 翻译文件存放路径不符合规范 #

主题自带的翻译文件有固定的存放位置，路径不对就算文件格式正确也无法加载：

• 合法路径必须为：wp-content/themes/my-theme/languages/pl_PL.mo
• 禁止将翻译文件直接丢在主题根目录、或者错放到wp-content/languages/global这类全局翻译目录下

3. 未挂载主题翻译加载钩子 #

仅在style.css中声明Text Domain: my-theme是不够的，WordPress不会自动扫描主题目录加载翻译包，必须在functions.php中添加初始化钩子，示例代码：

add_action( 'after_setup_theme', function() {
    // 第一个参数必须和style.css声明的文本域完全一致（大小写、连字符都不能错）
    load_theme_textdomain( 'my-theme', get_template_directory() . '/languages' );
} );

4. 翻译函数未正确匹配文本域 #

虽然你已使用标准的__()、_e()函数，但要逐行核对所有翻译调用的参数：

• 合法的翻译调用必须将自定义文本域作为第二个参数传入，例如：__( 'Theme options', 'my-theme' )
• 漏传文本域、或者文本域拼写不一致（如错写为My-Theme、mytheme），会导致WordPress将文案归类到默认的核心翻译域，完全不会读取你为主题准备的翻译包

5. 翻译内容未完成编译 #

你示例中列出的msgid和msgstr内容格式本身是符合po文件规范的，但编辑完成的pl_PL.po文件必须经过编译，生成对应的pl_PL.mo文件才能被WordPress加载：

• 不要直接修改po文件的后缀为mo就直接使用，二进制格式的mo文件需要专门编译生成
• 可以通过wp-cli直接编译：wp i18n make-mo wp-content/themes/my-theme/languages/pl_PL.po
• 也可以通过Poedit等翻译工具打开po文件，保存时会自动生成对应mo文件

6. 缓存层拦截翻译加载 #

如果网站开启了页面缓存、对象缓存、CDN缓存，就算所有配置都正确，缓存中存储的仍旧是之前的英文渲染结果：

• 清空全链路缓存（服务器缓存、页面缓存、CDN缓存）后再验证效果
• 临时开启翻译调试模式排查：在wp-config.php中添加define('L10N_DEBUG', true);，可以在页面源码中看到当前加载的翻译包匹配情况，排查完成后再删除该定义

内容的提问来源于stack exchange，提问作者Kishieel