1. 桌面应用国际化的核心痛点与方案选型做过桌面端工具软件的朋友大概率都遇到过这样一个需求软件给内部同事用的时候全是中文界面突然有一天要发给海外合作方或者非中文用户所有按钮、菜单、提示语全得换成英文甚至后面还要加法语、德语、日语。这时候如果代码里到处写的是label 保存文件这种硬编码字符串改起来就是灾难——你得满项目搜索替换改完还容易漏测试一遍又一遍。我最早接手这类需求的时候干的就是最笨的办法把所有界面文字抽到一个strings.py里用字典按语言分key。刚开始两三种语言还能扛等到第五种语言进来字典嵌套得跟迷宫一样翻译同事拿到那个文件直接懵了。后来才老老实实回到标准方案上——gettext。gettext 不是什么新东西它是GNU搞出来的一套国际化i18n标准工具链Linux上绝大多数命令行工具的多语言支持都是它做的。Python 标准库直接内置了gettext模块不需要额外装任何第三方包。而 wxPython 作为 Python 桌面GUI的老牌框架本身对 gettext 的配合度相当高只要把翻译目录结构搭对界面文字就能跟着系统语言或者手动设置自动切换。这套方案解决的核心问题有三个第一界面文字和代码彻底分离翻译人员只碰.po文件不碰一行代码第二支持复数形式和上下文不是简单的字符串替换第三运行时可切换不用重新打包就能换语言。适合谁看如果你正在用 wxPython 写工具类软件、内部系统客户端、跨平台小应用并且有出海或者多语言分发的打算那这套东西你迟早要用上。哪怕你现在只做中文版提前把架子搭好后面加语言就是分分钟的事。我下面会从目录结构设计、gettext 工作原理、wxPython 集成细节、翻译文件编译流程、运行时切换实现一直到踩过的坑完整走一遍。代码都是可以直接抄的参数我会解释清楚为什么这么设。2. gettext 工作机制与目录结构设计2.1 gettext 到底是怎么把中文变成英文的很多人第一次接触 gettext 会被一堆文件后缀搞晕.pot、.po、.mo还有locale目录、LC_MESSAGES子目录。我刚开始也迷糊后来画了个心智图就清楚了。整个流程是这样的你代码里写_(Save File)这个_就是 gettext 包装后的翻译函数。程序运行时gettext 会去一个约定的目录里找对应语言的.mo文件注意是.mo不是.po.mo是二进制格式程序读它效率高。.po是给人编辑的文本格式翻译人员改的是它。.pot是模板文件从代码里扫描出来的所有待翻译字符串的集合它是生成.po的母版。用生活化的类比.pot是空白试卷.po是某个学生填了答案的试卷.mo是扫描进电脑的机读卡。程序考试的时候只认机读卡。关键点在于gettext 查找翻译文件的路径是有严格约定的不是随便放哪都行。标准结构长这样myapp/ ├── main.py ├── locale/ │ ├── zh_CN/ │ │ └── LC_MESSAGES/ │ │ ├── messages.po │ │ └── messages.mo │ ├── en_US/ │ │ └── LC_MESSAGES/ │ │ ├── messages.po │ │ └── messages.mo │ └── ja_JP/ │ └── LC_MESSAGES/ │ ├── messages.po │ └── messages.molocale是根目录下面按语言代码分文件夹再下面必须是LC_MESSAGES这个固定名字这是 gettext 的历史约定改不了然后才是messages.mo。messages这个名字其实可以自定义但除非你有多个翻译域domain的需求否则统一叫messages最省事。注意语言代码的写法有讲究。zh_CN是中文-中国大陆zh_TW是中文-台湾地区en_US是英文-美国en_GB是英文-英国。gettext 匹配的时候会做一定的回退比如你系统语言是zh_CN.UTF-8它会先找zh_CN找不到再找zh。所以如果你只做了一套中文翻译目录名用zh也能兜住所有中文变体。2.2 为什么选 gettext 而不是自己写字典我前面提过自己用字典的方案这里展开说说为什么最后放弃了。自己写字典的问题在于复数处理。英文里 1 file 和 2 files 不一样中文里 1个文件 和 2个文件 一样俄语更复杂有三种复数形式。你用字典就得自己写逻辑判断每种语言规则不同维护成本爆炸。gettext 的ngettext直接帮你处理了翻译文件里按语言规则写好几套形式就行。第二个问题是上下文。英文 Open 可以是动词打开也可以是形容词开着的。如果代码里两处都写 Open字典方案只能翻成同一个词但 gettext 支持pgettext带上下文可以区分 Open (verb) 和 Open (adj) 翻成不同的词。第三个是工具链成熟度。gettext 有xgettext自动从代码里提取字符串有msgmerge合并新旧翻译有 Poedit、Lokalize 这些可视化编辑器。你自己写字典这些全得手搓。所以结论很明确只要你的应用有超过一种语言的可能gettext 就是正路。前期多花半小时搭架子后期省几十小时。2.3 wxPython 与 gettext 的配合方式wxPython 本身其实有自己的翻译机制它内部用wx.Locale和wx.GetTranslation。但我不建议直接用 wxPython 自带的这套原因有两个一是它和 Python 标准库的 gettext 是两套体系混用容易乱二是 wxPython 自带的翻译主要针对它自己的内置控件文字比如文件对话框的取消按钮你自己的业务文字还是得自己管。我的做法是用 Python 标准库的 gettext 管业务文字用 wx.Locale 管 wxPython 内置控件的语言。两者各司其职互不干扰。具体来说程序启动时先初始化wx.Locale让系统对话框跟着语言走然后安装 gettext把_函数注入到内置命名空间这样代码里到处都能直接用_(...)。这个注入内置命名空间的操作是 wxPython 社区里很常见的做法好处是不用每个文件都import gettext再gettext.gettext写起来清爽。3. 从零搭建国际化支持的完整实操3.1 第一步搭目录骨架和初始化代码先建目录。假设你的项目叫myapp在项目根目录下建locale文件夹里面按语言建子目录。我一般先建zh_CN和en_US两个一个中文一个英文够用了再扩。然后是初始化代码。我把它写成一个独立的i18n.py模块主程序 import 一下就行import gettext import os import sys import wx LOCALE_DIR os.path.join(os.path.dirname(os.path.abspath(__file__)), locale) DOMAIN messages def setup_i18n(langNone): # 第一步初始化 wx.Locale管 wxPython 内置控件 wx_locale wx.Locale() if lang: wx_locale.Init(wx.LANGUAGE_DEFAULT, wx.LOCALE_DONT_LOAD_DEFAULT) # 手动设置语言 lang_code wx.LANGUAGE_DEFAULT for i in range(wx.LANGUAGE_MAX): info wx.Locale.FindLanguageInfo(i) if info and info.CanonicalName lang: lang_code i break wx_locale.Init(lang_code) else: wx_locale.Init(wx.LANGUAGE_DEFAULT) # 第二步安装 gettext管业务文字 try: trans gettext.translation( DOMAIN, localedirLOCALE_DIR, languages[lang] if lang else None, fallbackTrue ) except Exception: trans gettext.NullTranslations() trans.install() return trans这里有几个细节要解释。wx.Locale()的Init方法第一个参数是语言IDwx.LANGUAGE_DEFAULT表示跟随系统。第二个参数wx.LOCALE_DONT_LOAD_DEFAULT是告诉 wxPython 不要自动加载它自带的翻译因为我们自己管。gettext.translation的fallbackTrue很关键。它的意思是如果找不到对应语言的.mo文件不要抛异常而是返回一个空翻译对象_(Save)还是返回 Save。这样程序不会因为缺翻译文件就崩掉对开发阶段特别友好。trans.install()这个方法会把_注入到builtins命名空间之后任何模块里直接写_(...)就能用不用 import。这是 gettext 的标准用法但很多人不知道。实操心得install()默认还会注入gettext、ngettext、pgettext等函数。如果你担心污染命名空间可以用trans.install(names[_])只注入_。我一般就注入_和ngettext两个够用且干净。3.2 第二步在代码里正确使用翻译函数初始化搞定后代码里所有面向用户的文字都要用_()包起来。这里有个原则只包用户能看到的文字不要包日志、调试信息、内部key。import wx from i18n import setup_i18n class MainFrame(wx.Frame): def __init__(self): super().__init__(None, title_(My Application), size(600, 400)) panel wx.Panel(self) sizer wx.BoxSizer(wx.VERTICAL) self.label wx.StaticText(panel, label_(Please select a file:)) sizer.Add(self.label, 0, wx.ALL, 10) btn wx.Button(panel, label_(Open File)) btn.Bind(wx.EVT_BUTTON, self.on_open) sizer.Add(btn, 0, wx.ALL, 10) panel.SetSizer(sizer) def on_open(self, event): with wx.FileDialog( self, _(Choose a file to process), wildcard_(Text files (*.txt)|*.txt|All files (*.*)|*.*), stylewx.FD_OPEN | wx.FD_FILE_MUST_EXIST ) as dlg: if dlg.ShowModal() wx.ID_OK: path dlg.GetPath() wx.MessageBox( _(You selected: {}).format(path), _(Info), wx.OK | wx.ICON_INFORMATION ) if __name__ __main__: app wx.App() setup_i18n() frame MainFrame() frame.Show() app.MainLoop()注意_(You selected: {}).format(path)这种写法。不要把变量拼进翻译字符串再翻译比如_(You selected: path)是错的。因为翻译文件里存的是完整字符串你拼了变量进去翻译人员看到的是一堆动态内容没法翻。正确做法是把带占位符的模板拿去翻译运行时再 format。同理wildcard那个字符串里用了|分隔这是 wxPython 的格式要求翻译的时候整个字符串一起翻翻译人员需要保留|和*这些符号。这个要在给翻译人员的说明里写清楚。3.3 第三步用 xgettext 提取待翻译字符串代码写好后需要把_()里的字符串提取出来生成.pot模板。这步用xgettext命令Linux 和 macOS 一般自带Windows 上装了 gettext 工具包也有。xgettext -o locale/messages.pot \ --languagePython \ --keyword_ \ --keywordngettext:1,2 \ --from-codeUTF-8 \ --add-commentsTRANSLATORS \ *.py参数逐个解释-o指定输出文件--languagePython告诉它按 Python 语法解析--keyword_表示识别_()调用--keywordngettext:1,2表示识别ngettext且第一个和第二个参数是单复数形式--from-codeUTF-8指定源文件编码--add-commentsTRANSLATORS会把代码里# TRANSLATORS: xxx的注释也提取进去方便给翻译人员留说明。生成.pot后为每种语言初始化.po文件msginit -i locale/messages.pot -o locale/zh_CN/LC_MESSAGES/messages.po -l zh_CN.UTF-8 msginit -i locale/messages.pot -o locale/en_US/LC_MESSAGES/messages.po -l en_US.UTF-8msginit会基于模板生成一个空的.po里面msgid是原文msgstr是空的等着填。翻译人员用 Poedit 打开这个文件逐条填msgstr就行。3.4 第四步编译 .po 为 .mo.po是给人看的程序运行时读的是.mo。编译命令msgfmt -o locale/zh_CN/LC_MESSAGES/messages.mo locale/zh_CN/LC_MESSAGES/messages.po msgfmt -o locale/en_US/LC_MESSAGES/messages.mo locale/en_US/LC_MESSAGES/messages.po每次改完.po都要重新跑一遍msgfmt。我一般写个build_i18n.py脚本自动扫描所有语言目录批量编译import os import subprocess LOCALE_DIR locale for lang in os.listdir(LOCALE_DIR): po_path os.path.join(LOCALE_DIR, lang, LC_MESSAGES, messages.po) mo_path os.path.join(LOCALE_DIR, lang, LC_MESSAGES, messages.mo) if os.path.exists(po_path): subprocess.run([msgfmt, -o, mo_path, po_path], checkTrue) print(fCompiled {lang})注意.mo文件是二进制不要提交到 git 里跟.po一起管理的话建议把.mo加进.gitignore打包的时候再编译。但如果你用 PyInstaller 打包记得把.mo一起打进去否则运行时找不到。4. 运行时语言切换与 wxPython 界面刷新4.1 为什么运行时切换比想象中麻烦很多教程讲到编译.mo就结束了但实际项目里有个绕不开的需求用户想在设置里切换语言不重启程序就生效。这个在 wxPython 里比 Web 应用麻烦得多因为 wxPython 的控件文字是创建时设定的创建完再改需要手动调SetLabel。gettext 本身支持运行时切换只要重新调用gettext.translation换一个语言然后重新install。但已经创建出来的 wxPython 控件不会自动更新得遍历一遍手动刷新。我的做法是切换语言后销毁当前窗口用新语言重建。听起来暴力但最可靠不会漏掉任何控件。对于大多数工具类应用重建窗口也就几百毫秒用户感知不到。def switch_language(lang): # 重新安装 gettext trans gettext.translation( DOMAIN, localedirLOCALE_DIR, languages[lang], fallbackTrue ) trans.install() # 重建主窗口 global main_frame main_frame.Destroy() main_frame MainFrame() main_frame.Show()如果窗口里有用户未保存的数据重建前要提示保存。这个逻辑得根据你的业务来加。4.2 语言选择菜单的实现在菜单栏里加一个语言子菜单列出支持的语言点击就切换def build_language_menu(self): lang_menu wx.Menu() languages [ (zh_CN, _(Chinese)), (en_US, _(English)), (ja_JP, _(Japanese)), ] for code, name in languages: item lang_menu.Append(wx.ID_ANY, name, kindwx.ITEM_RADIO) self.Bind(wx.EVT_MENU, lambda e, ccode: switch_language(c), item) return lang_menu这里用wx.ITEM_RADIO让菜单项变成单选样式当前语言打勾。注意_(Chinese)这种语言名称本身也翻译了这样中文界面下显示中文英文界面下显示Chinese符合用户习惯。4.3 保存用户语言偏好用户选了语言下次启动要记住。用wx.Config存到系统配置里config wx.Config(myapp) config.Write(language, lang) config.Flush() # 启动时读取 saved_lang config.Read(language, ) setup_i18n(saved_lang if saved_lang else None)wx.Config在 Windows 上写注册表Linux 上写~/.myappmacOS 上写 plist跨平台不用自己操心路径。5. 常见问题排查与避坑经验5.1 翻译不生效的排查顺序翻译不生效是最常见的问题我整理了一个排查清单按顺序查基本能定位现象可能原因排查方法所有文字都是原文.mo文件没生成检查LC_MESSAGES下有没有.mo部分文字不翻译字符串没被_()包用xgettext重新提取看.pot里有没有中文显示乱码编码不是 UTF-8检查.po文件头部Content-Type切换语言无效没重新 install确认trans.install()被调用复数形式错误ngettext参数顺序错检查ngettext(singular, plural, n)我踩过最坑的一次是.po文件里msgstr填了但忘了编译.mo程序读的还是旧的.mo改了半小时才发现。后来养成习惯改完.po立刻跑编译脚本。5.2 中文翻译里的空格和标点陷阱中文和英文的标点习惯不同。英文 Save File 翻成中文是保存文件中间没空格。但如果你在.po里填了保存 文件中间有空格界面上就会多一个空格很别扭。另一个坑是省略号。英文用 ...中文用……。这个要在翻译规范里写清楚。还有冒号英文 Name: 中文是名称全角冒号。实操心得给翻译人员的说明文档里一定要写清楚标点规范。我一般会准备一个TRANSLATION_GUIDE.md列出中英文标点对照、空格规则、占位符保留规则。这份文档能省掉大量返工。5.3 PyInstaller 打包时的翻译文件处理用 PyInstaller 打包后locale目录不会自动打进去得手动加pyinstaller --add-data locale:locale main.pyWindows 上用分号分隔--add-data locale;locale。打包后运行时os.path.dirname(os.path.abspath(__file__))在 PyInstaller 环境下指向的是临时解压目录所以LOCALE_DIR的路径计算要改成兼容 PyInstaller 的写法import sys if getattr(sys, frozen, False): BASE_DIR sys._MEIPASS else: BASE_DIR os.path.dirname(os.path.abspath(__file__)) LOCALE_DIR os.path.join(BASE_DIR, locale)sys._MEIPASS是 PyInstaller 运行时解压临时目录的路径frozen属性判断是否在打包环境。这个兼容写法几乎所有涉及资源文件的 PyInstaller 项目都要用。5.4 复数形式的正确用法英文里 1 file 和 2 files用ngettextcount len(files) msg ngettext({} file, {} files, count).format(count).po文件里对应的条目长这样msgid {} file msgid_plural {} files msgstr[0] {} file msgstr[1] {} files中文的.po里两个形式填一样的就行msgstr[0] {} 个文件 msgstr[1] {} 个文件因为中文没有复数变化但 gettext 要求必须填够形式数量填一样的即可。俄语、阿拉伯语这些复数规则复杂的语言.po头部会声明Plural-Forms翻译人员按规则填。6. 翻译工作流与团队协作建议6.1 给翻译人员的交付物清单如果你把翻译外包或者交给同事交付物要打包清楚不然来回沟通成本很高。我一般给这几样messages.pot模板文件包含所有待翻译字符串已有的.po文件如果有部分翻译TRANSLATION_GUIDE.md翻译规范说明一张界面截图标注每个字符串出现在哪里截图这个特别有用。翻译人员看到 Open 不知道是按钮还是菜单看到截图就明白了。我一般用 Snipaste 截图后在图上标序号和.po里的条目对应。6.2 翻译更新的合并流程代码迭代过程中会新增字符串这时候不能重新生成.po覆盖旧的否则已翻译的内容全丢了。正确做法是用msgmerge合并xgettext -o locale/messages.pot --languagePython --keyword_ *.py msgmerge --update locale/zh_CN/LC_MESSAGES/messages.po locale/messages.potmsgmerge会把新字符串加进去旧的翻译保留被删除的字符串标记为 obsolete前面加#~。翻译人员只需要处理新增的部分。6.3 自动化构建集成如果项目用 CI/CD可以把翻译编译加进构建流程。在构建脚本里加一步python build_i18n.py确保每次构建都用最新的.mo。我还会加一个检查如果.po里有未翻译的条目msgstr为空构建时警告但不失败提醒团队补翻译。7. 性能与体积的实测数据7.1 gettext 查找翻译的开销有人担心每次_()调用都去查文件会慢。实测下来gettext 在首次加载.mo后会把翻译表缓存在内存里后续调用就是字典查找纳秒级。我用一个包含 500 个字符串的界面测过初始化时加载.mo大概 2-3 毫秒之后每次_()调用开销可以忽略。真正有开销的是运行时切换语言因为要重新加载.mo并重建窗口。但这是用户主动触发的低频操作几百毫秒完全可接受。7.2 多语言对打包体积的影响每个语言的.mo文件通常只有几KB到几十KB。我手上一个项目中文.mo是 8KB英文 7KB日文 12KB。十个语言加起来也就 100KB 左右对现代应用来说可以忽略。所以不用担心多语言会让安装包变大。7.3 字符串数量与维护成本的关系根据我的经验一个中等复杂度的桌面工具界面字符串大概在 200-500 条。超过 500 条后翻译管理就需要更正式的工具了比如用 Weblate 或者 Crowdin 这类平台。但 gettext 的.po格式是这些平台都支持的通用格式所以前期用 gettext 打底后期迁移到平台也无缝。8. 我踩过的几个真实坑第一个坑是编码问题。早期我用 Windows 记事本编辑.po文件保存成了 GBK 编码msgfmt编译时报错。后来统一用 VS Code 编辑右下角确认是 UTF-8 再保存。.po文件头部必须有Content-Type: text/plain; charsetUTF-8否则中文会乱码。第二个坑是**_函数的作用域**。trans.install()注入的是builtins但如果你在某个模块里自己定义了_变量会覆盖掉。我有次在一个文件里写了_ some_list结果那个文件里所有_(...)都报错。排查了半天才发现是变量名冲突。所以千万别用_当普通变量名。第三个坑是wxPython 内置控件的语言。文件对话框的打开、取消按钮一开始我以为 gettext 能管结果发现这些是 wxPython 自己画的得靠wx.Locale。而且wx.Locale必须在wx.App()创建之后、窗口创建之前初始化顺序错了不生效。第四个坑是打包后路径变化。开发时LOCALE_DIR用__file__算没问题PyInstaller 打包后__file__指向的路径不对得用sys._MEIPASS。这个坑我踩了两次第一次打包出来翻译全失效第二次才想起来加frozen判断。9. 后续可以扩展的方向这套架子搭好后扩展空间挺大的。比如可以加一个翻译覆盖率检查在 CI 里跑脚本统计每个语言的未翻译条目比例低于阈值就报警。还可以做伪翻译测试把所有msgstr填成带特殊标记的假文字比如[!!!Save File!!!]跑一遍界面看有没有漏网的硬编码字符串。这个方法特别有效能揪出所有忘记用_()包的文字。另一个方向是接入在线翻译平台。.po文件是通用格式Weblate、Crowdin、Transifex 都支持。团队大了之后让翻译人员在网页上协作比传文件高效得多。gettext 的生态成熟度在这里体现得很明显几乎不用做任何适配。如果应用要支持从右到左的语言比如阿拉伯语、希伯来语wxPython 本身支持wx.Layout_RightToLeft但界面布局要额外处理。这个我还没实际做过等有需求了再研究。最后分享一个小技巧在开发阶段可以设一个环境变量LANG_DEBUG1程序启动时如果检测到这个变量就把所有_()的调用打印出来方便检查哪些字符串被翻译了、哪些没有。这个调试开关在排查翻译遗漏时特别好用几行代码的事import os if os.environ.get(LANG_DEBUG): _original_gettext gettext.gettext def _debug_gettext(message): result _original_gettext(message) print(f[i18n] {message!r} - {result!r}) return result gettext.gettext _debug_gettext这个包装在setup_i18n里加一下就行不影响正常使用需要的时候开环境变量就能看到翻译映射的实时日志。