简介面向在 Visual Studio 2015 下开发全球化桌面软件的 MFC 开发者这份资源围绕「界面多语言切换」这一常见难题展开给出一套可直接编译运行的完整示例。包内共 28 个文件约 1.18MB包含 6 个头文件与 4 个 cpp 源文件承载语言切换核心逻辑2 个 po 与 2 个 mo 语言包配合 POEdit 演示翻译流程另有 rc、rc2 资源脚本、sln 与 vcxproj 工程文件、dll 与 lib 库以及 exe 可执行程序方便对照阅读与直接运行验证。资源从资源文件分语言组织、Gettext 翻译文件管理到 AfxSetResourceHandle 切换资源句柄、LoadString 更新界面文本再到长文本下的界面尺寸适配形成了较完整的实践路径可作为排查字符串未刷新、布局错位等问题的参考。目前已有 1388 人学习下载适合具备一定 MFC 基础、需要为产品补充国际化能力的中级开发者。1. MFC 多语言切换从一次 RC 复制两份的返工说起前年接手某模拟项目X 的 MFC 客户端做中英双语第一版方案很朴素复制一份 .rc把字符串挨个改一遍切语言时重新 LoadFrame。上线三周收到两类反馈模态对话框标题栏还是中文英文环境下设备型号后面的单位变成了方块。返工两天最后推倒重来改成 gettext 的 PO/MO 语言包路线界面文本全部从 .rc 里剥出来集中管理。MFC 多语言切换、界面文本抽取、Poedit 编辑、mo 语言包编译这套组合不新鲜但对编码和加载顺序特别敏感字符集差一个选项中文就是问号资源句柄换晚一步已经打开的对话框纹丝不动。这篇记录按我实际装下来的顺序走一遍从版本选型到验证收口照着做能跑通也能看懂每一步为什么这么配。2. 环境对齐VS 2022 的 MFC 组件、Poedit 3.4 与 gettext 0.21动手前先把四样东西备齐版本错了后面全是白工。这套环境不复杂麻烦的是几个组件名字长得像、装完才发现少一个。2.1 Visual Studio 的 MFC 组件与字符集选项VS 2022 建议 17.8 以上平台工具集 v143如果团队还锁在 VS 2019用 16.11 配 v142 也能跑但 C17 的std::string_view支持和 MFC 头文件的小修补有差异两边混着编译容易出怪问题。安装器里有两个勾选项名字很像工作负载「使用 C 的桌面开发」和单个组件「适用于最新 v143 生成工具的 C MFC (x86 和 x64)」。前者默认只装核心库afxwin.h根本不在里面很多人装完 VS 新建 MFC 项目报「无法打开 afxwin.h」就是漏了这个。稳妥做法是工作负载勾上后切到「单个组件」搜索 MFC把对应工具集那一项手动勾选。装完先确认三处工程属性缺一处后面都要返工位置配置项取值为什么配置属性 → 高级字符集使用 Unicode 字符集MO 里是 UTF-8 窄串最终要转宽字符上屏配置属性 → 常规使用 MFC在共享 DLL 中使用 MFC静态链接会让 exe 膨胀十几兆语言包没必要背这个C/C → 语言C 语言标准ISO C17 (/std:c17)加载器用std::map、std::string别用老标准硬扛字符集这一项是血泪经验。项目如果是从 VC6 或 VS2010 迁上来的很可能还是「使用多字节字符集」CString是CStringASetWindowText走的也是 ANSI 版本中文在某些系统区域设置下直接变问号。改成 Unicode 之后所有CString相关代码要跟着改一遍_T()包裹工作量不小但这是一次性成本越早改越省事。还有一处容易漏发布时共享 DLL 模式要带mfc140u.dll、vcruntime140.dll、msvcp140.dll这一套。要么在目标机装 VC 运行库要么把 DLL 放 exe 同目录。我们后来选的是随包分发省得用户机上版本冲突。2.2 Poedit 与 gettext 命令行装哪个、装在哪Poedit 装 3.4.x 就行免费版够用。它自带msgfmt.exe和msgcat.exe位置在C:\Program Files\Poedit\bin\。但注意——它不带xgettext。Poedit 内部有自己的抽取逻辑可命令行工具没暴露出来所以想从源码批量生成.pot还得单独装 gettext。gettext 用 0.21 的 Windows 二进制包gettext-tools和gettext-runtime两个压缩包解压到C:\tools\gettext\把bin加进系统 PATH。加完开一个新的 PowerShell 窗口验证老窗口 PATH 不会刷新# 三条命令都要能打印版本号缺一条就回去补装 C:\Program Files\Poedit\bin\msgfmt.exe --version xgettext --version msbuild -version如果嫌 gettext 包里的libintl-8.dll和项目其他依赖打架可以只把xgettext.exe和它依赖的libgettextpo拷到独立目录用绝对路径调用。我一般会把xgettext、msgfmt、msgmerge三个 exe 的路径写进项目的构建脚本变量里不依赖全局 PATH换机器时改一行就行。版本上有个参考对照都是实践证明能配合起来的组合组件版本用途备注Visual Studio2022 17.8 / 2019 16.11编译 MFC 工程必须含 MFC 单个组件Windows SDK10.0.19041 以上系统头文件VS 安装器自带即可Poedit3.4.x编辑 PO、预览翻译自带 msgfmt / msgcatgettext0.21xgettext 抽取、msgmerge 合并只用 tools 包runtime 可选不建议上 gettext 0.22 之后的开发版Windows 二进制包不全xgettext有时候链接不上libiconv。0.21 是老版本但稳。2.3 目录与编码约定UTF-8、LC_MESSAGES 与长路径这套东西出问题八成栽在编码和路径上装之前先把约定定死后面谁也别改。源码文件.cpp / .h统一存成UTF-8 with BOM同时在工程属性 C/C → 命令行里加/utf-8。两个都做不是多余BOM 让编辑器正确识别/utf-8让 MSVC 按 UTF-8 读源文件并把执行字符集设成 UTF-8。只做其中一个中文注释里的乱码依然会顺着预编译头污染下去。.po文件全程UTF-8 无 BOMPoedit 默认就是这个别手动改。.rc文件是另一回事VS 资源编辑器保存时按本地代码页走中文环境就是 GBK。稳妥做法是把 .rc 另存为「Unicode (UTF-16 LE)」VS 能正确识别rc.exe也不会抱怨。语言包目录用固定的三级结构跨平台工具链都认这个约定locales/ zh_CN/LC_MESSAGES/app.mo en_US/LC_MESSAGES/app.mo ja_JP/LC_MESSAGES/app.moLC_MESSAGES目录名全大写虽然 Windows 文件系统不区分大小写但你的构建脚本可能跑在别的系统上别给自己埋雷。最后一个坑长路径。exe 装在C:\Program Files\某模拟项目X\下时拼出来的语言包全路径很容易超过 260 字符CFile::Open直接失败还不报错返回 FALSE很多人不检查返回值。两个办法一是给 exe 加longPathAware清单二是把locales放在 exe 同级但控制嵌套层级。我一般直接在Load里加一句路径长度断言超过 240 就ASSERT出来开发期就能发现。3. 资源改造把界面文本从 .rc 里剥出来交给 gettext环境齐了接下来是真正花时间的部分把散落在对话框模板、字符串表、菜单资源里的文本变成 gettext 能抽取、Poedit 能翻译、运行时能查表的形式。3.1 资源模板只留英文运行时按控件回填第一件事是把.rc里所有可见文本改成英文。为什么不是清空因为设计器里得看见布局而且英文作为兜底语言语言包加载失败时界面至少还是可读的英文不会露出一片空白。对话框模板里每一行LTEXT 打开文件,IDC_STATIC,7,7,60,8都要改成英文。控件的ID 一个都不能动因为后面回填文本靠 ID 定位。菜单资源同理顶层菜单和子项的 ID 保持不变CAPTION和MENUITEM的文本改英文。改完还要处理字符串表。原来IDS_FILE_OPEN对应「打开(O)」现在值改英文Open。这一步看着机械但它是整个方案的地基地基是英文中文是「翻译」翻译丢了界面还能用。提示改造前先提交一次版本或者打个 tag。这一步改错很难靠 diff 回滚尤其是几百行的对话框模板。3.2 xgettext 抽取关键字、注释与 .pot 生成代码里所有需要翻译的地方统一用_()宏包起来非界面文本继续用_T()两者泾渭分明。_()的定义放在I18n.h// I18n.h —— 全工程唯一的翻译入口别在别处再定义第二个 #pragma once #include string #include map class CI18n { public: static CI18n Instance(); // strMoPath 传完整路径加载失败返回 false调用方决定用哪种兜底 bool Load(const CString strMoPath); // 查不到就原样返回绝不返回空串否则界面会出现大片空白 CString Tr(const CString strSrc) const; // 按语言标签重载内部会把 zh-CN / zh-Hans 规范成 zh_CN bool Reload(const CString strLangTag); private: std::mapstd::string, std::string m_map; // key 和 value 都存 UTF-8 }; // 界面文本用这个xgettext 认 _ 这个关键字 #define _(s) CI18n::Instance().Tr(_T(s))宏里套了_T()是为了让_(Open)直接产出CString省得调用处到处写转换。但要注意xgettext只认_()里的裸字符串字面量写成_(strText)这种运行时变量它抽不到——这一点在第 5 章会引发一个典型翻车这里先记住。抽取命令xgettext --languageC --from-codeUTF-8 \ --keyword_ \ --add-commentsI18N \ --package-name某模拟项目X --package-version1.0 \ -o locales/app.pot \ src/i18n/*.cpp src/ui/*.cpp src/ui/*.h参数逐个说--languageC决定解析器按 C 语法切分--from-codeUTF-8告诉它源文件是 UTF-8不写这一条中文 msgid 会变成乱码字节--keyword_声明_()括号里的内容是待翻译串如果代码里还用了N_()做延迟翻译再加一个--keywordN_--add-commentsI18N会保留源码里// I18N: 这里是按钮文字这类注释译者在 Poedit 里看得到上下文能省一半沟通成本。.pot是模板文件每次xgettext都会整个覆盖。所以不要直接翻译 .pot已有的翻译要用msgmerge合并进去# 把新模板合并进已有中文 PO--backupnone 不留 .po~ 备份文件 msgmerge --update --backupnone --no-fuzzy-matching \ locales/zh_CN/LC_MESSAGES/app.po locales/app.pot--no-fuzzy-matching是我个人的偏好自动 fuzzy 匹配有时候会把两句话强行凑一起译者一眼没看出来就上线了。宁可让它留空人工补。3.3 对话框文本回填一个递归函数解决八成控件模板里现在是英文代码里也不写死文本中间的桥梁是OnInitDialog里的统一回填。写一个递归函数遍历窗口和所有子控件把当前文本作为 key 去翻译表里查// 递归翻译窗口及其全部子控件找不到译文时保持原样 static void TranslateWindow(CWnd* pWnd) { CString strText; pWnd-GetWindowText(strText); if (!strText.IsEmpty()) { CString strNew CI18n::Instance().Tr(strText); if (strNew ! strText) pWnd-SetWindowText(strNew); } // GW_CHILD 拿第一个子窗口再靠 GW_HWNDNEXT 横向遍历兄弟 CWnd* pChild pWnd-GetWindow(GW_CHILD); while (pChild ! nullptr) { TranslateWindow(pChild); pChild pChild-GetNextWindow(GW_HWNDNEXT); } }逻辑很直白取当前窗口文本非空才查表查到不同才写回然后递归子控件。GW_CHILD只返回第一个子窗口必须配合GW_HWNDNEXT遍历同级链表漏了这一步界面上只有一个控件会被翻译。这个函数依赖一个前提.rc里的英文文本必须出现在.po的 msgid 里。xgettext抽不到资源文件所以得单独跑一个脚本把.rc里的控件文本抠出来# tools/rc2pot.py 从 .rc 里抽控件可见文本输出 pot 片段 import re, sys CTRL r(LTEXT|CTEXT|RTEXT|PUSHBUTTON|DEFPUSHBUTTON|CHECKBOX|RADIOBUTTON|GROUPBOX|CAPTION) PAT re.compile(CTRL r\s((?:[^]|)*)\s*,\s*([A-Za-z_]\w*), re.IGNORECASE) seen, out set(), [] # .rc 存的是 UTF-16LE编码参数别写错否则读出来全是乱码 with open(sys.argv[1], encodingutf-16) as f: text f.read() for m in PAT.finditer(text): txt m.group(2).replace(, ) if not txt or txt in seen: # 同一句话在多个对话框出现只留一条 continue seen.add(txt) out.append(#: %s %s\nmsgid %s\nmsgstr \n % (sys.argv[1], m.group(3), txt)) print(\n.join(out))这个脚本只处理单行文本多行拼接的LTEXT会漏够用就行真遇到再补正则。生成出来的片段不能直接当 pot 用缺文件头用msgcat合并python tools/rc2pot.py res/app.rc build/rc.pot msgcat --use-first locales/app.pot build/rc.pot -o locales/app.pot--use-first保证重复条目取第一个不会因为两个来源都抽到OK就报冲突。3.4 菜单重建DrawMenuBar 那行千万别省菜单是最容易「切了没反应」的地方因为CMenu是句柄资源不是窗口文本TranslateWindow那套对它无效。切换语言时必须整份重建void CMainFrame::SwitchLanguage(const CString strLang) { // 先重载翻译表再动界面顺序反了会用旧表翻新界面 CI18n::Instance().Reload(strLang); CMenu* pOld GetMenu(); if (pOld ! nullptr) pOld-DestroyMenu(); // 必须销毁否则句柄泄漏切十次漏十个 CMenu menuNew; menuNew.LoadMenu(IDR_MAINFRAME); SetMenu(menuNew); // 窗口接管句柄 menuNew.Detach(); // 不 Detach局部对象析构时会把菜单一起销毁 TranslateMenu(GetMenu()); // 自己实现深度优先递归子菜单 DrawMenuBar(); // 少了这句菜单栏保持旧样子不刷新 SetWindowText(_(某模拟项目X)); }三个坑都在这十几行里不DestroyMenu泄漏句柄不Detach会让局部CMenu析构时把刚挂上去的菜单销毁界面上直接没菜单栏不调DrawMenuBar数据变了但画面不更新调试时断点看菜单项文本是对的肉眼看到的还是中文最迷惑人。TranslateMenu的实现和TranslateWindow类似用GetMenuItemCountGetMenuString/ModifyMenu逐项处理遇到MF_POPUP标志就递归子菜单句柄。4. 语言包落地Poedit 出 PO、msgfmt 编 MO、运行时挂载工程改完界面文本都走翻译表了但表还是空的。这一章把.pot变成能加载的.mo再让程序在启动和切换时找到它。4.1 用 Poedit 从 POT 建 PO编码、复数与占位符Poedit 里「文件 → 新建」选locales/app.pot语言填Chinese (Simplified, China)保存到locales/zh_CN/LC_MESSAGES/app.po。项目设置里确认三件事源文本编码 UTF-8、目标语言zh_CN、复数形式nplurals1; plural0;。中文没有复数变化这一条写错不影响显示但msgfmt -c会警告。占位符是另一处必须盯的。代码里_(Found %d device(s))到了中文要写成「找到 %d 台设备」%d一个不能少、顺序不能乱。多个占位符时建议用%1$s、%2$d的带序号写法中文语序和英文不一致时能自由调换msgfmt -c也认这种格式。Poedit 的设置里有个「保存时自动编译 MO」但只能指定一个输出目录多语言场景下每次切语言都要改设置不如关掉统一走命令行编译。注意Poedit 免费版会把未翻译条目在保存时保留为msgstr 这是对的运行时查不到就回退原文。别为了让统计数字好看去填机器翻译界面上一半机翻比全英文更难读。4.2 msgfmt 批量编译与格式校验单个文件编译msgfmt -c -v --statistics \ --output-filelocales/zh_CN/LC_MESSAGES/app.mo \ locales/zh_CN/LC_MESSAGES/app.po-c做格式串校验%s数量对不上、%d类型冲突都会直接报 error 退出这是发布前最有用的一道闸。--statistics打印已翻译和未翻译条数接到 CI 里当门禁未翻译比例超过阈值就失败。--output-file后面必须是.mo手滑写成.po会把文本直接覆盖掉而且msgfmt不拦。多语言一次编完set -e # 任何一条失败立即中断别让半套语言包上线 for po in locales/*/LC_MESSAGES/*.po; do mo${po%.po}.mo msgfmt -c --statistics -o $mo $po echo OK $mo doneset -e是关键。没有它日文那个 po 报错中断后循环继续跑最后打包出来缺一个.mo测试环境才发现。编完顺手msgunfmt反编一个回来看看内容对不对msgunfmt locales/zh_CN/LC_MESSAGES/app.mo | head -40能看到 msgid / msgstr 成对出现就说明二进制结构没问题。4.3 运行时挂载路径查找顺序与 .mo 解析加载器要自己写二十来行比引libintl.dll干净。.mo文件结构很简单前 28 字节是文件头后面两张表分别存原始串和译文的偏移量。// 解析 .momagic(4) revision(4) count(4) origOff(4) transOff(4) hashSize(4) hashOff(4) bool CI18n::Load(const CString strMoPath) { CFile file; if (!file.Open(strMoPath, CFile::modeRead | CFile::shareDenyNone)) return false; // 文件不存在是最常见情况静默回退 const ULONGLONG ullLen file.GetLength(); if (ullLen 28 || ullLen 16 * 1024 * 1024) return false; // 大小异常直接拒绝防止读到脏文件 std::vectorBYTE buf(static_castsize_t(ullLen)); file.Read(buf.data(), static_castUINT(ullLen)); const BYTE* p buf.data(); if (*reinterpret_castconst DWORD*(p) ! 0x950412DE) return false; // 大端包是 0xDE120495这里不处理 const DWORD dwCount *reinterpret_castconst DWORD*(p 8); const DWORD dwOrigTab *reinterpret_castconst DWORD*(p 12); const DWORD dwTransTab *reinterpret_castconst DWORD*(p 16); m_map.clear(); for (DWORD i 1; i dwCount; i) // 0 号是元信息Project-Id-Version 等跳过 { const DWORD dwLenO *reinterpret_castconst DWORD*(p dwOrigTab i * 8); const DWORD dwPosO *reinterpret_castconst DWORD*(p dwOrigTab i * 8 4); const DWORD dwLenT *reinterpret_castconst DWORD*(p dwTransTab i * 8); const DWORD dwPosT *reinterpret_castconst DWORD*(p dwTransTab i * 8 4); // 边界检查不能省损坏的 .mo 会让这里直接越界读崩 if (dwPosO dwLenO ullLen || dwPosT dwLenT ullLen) continue; std::string strKey(reinterpret_castconst char*(p dwPosO), dwLenO); std::string strVal(reinterpret_castconst char*(p dwPosT), dwLenT); if (!strVal.empty()) // 空译文不入表查不到自然回退 m_map[strKey] strVal; } return !m_map.empty(); }查表时的转换是最容易写错的一步。std::string里存的是 UTF-8CString在 Unicode 构建下是 UTF-16中间必须显式走WideCharToMultiByte/MultiByteToWideChar并指定CP_UTF8。用CStringA或者CT2CA会把当前系统代码页简体中文下是 CP936当成 UTF-8key 一个都对不上断点看 map 里明明有数据界面就是不翻译。// 宽字符转 UTF-8唯一正确写法显式指定 CP_UTF8 static std::string ToUtf8(const CString s) { const int n ::WideCharToMultiByte(CP_UTF8, 0, s, s.GetLength(), nullptr, 0, nullptr, nullptr); std::string out(static_castsize_t(n), \0); ::WideCharToMultiByte(CP_UTF8, 0, s, s.GetLength(), out.data(), n, nullptr, nullptr); return out; } CString CI18n::Tr(const CString strSrc) const { auto it m_map.find(ToUtf8(strSrc)); if (it m_map.end()) return strSrc; // 没翻到就回退原文绝不返回空 const int n ::MultiByteToWideChar(CP_UTF8, 0, it-second.c_str(), static_castint(it-second.size()), nullptr, 0); CStringW w; ::MultiByteToWideChar(CP_UTF8, 0, it-second.c_str(), static_castint(it-second.size()), w.GetBuffer(n), n); w.ReleaseBuffer(n); return CString(w); }路径解析我自己定了个优先级exe 同级locales\tag\LC_MESSAGES\app.mo优先然后用户%APPDATA%下的同名目录允许用户自己丢语言包进去最后兜底en_US。语言标签要规范化注册表里存zh-CN、zh-Hans、zh_CN都可能统一转成下划线形式再拼路径转换表写死在一个函数里别散落各处。5. 排查清单多语言切换翻车的五个现场下面五条都是实际遇到过的按「现象 → 原因 → 解决」记遇到类似的直接对号入座。5.1 中文全变问号三处编码没对齐现象英文界面正常切到中文后对话框里一片???部分控件显示方块。原因三处编码任意一处不对都会这样——.rc存成 GBK 但rc.exe按 UTF-8 解析.po被某个编辑器另存成 GB2312msgfmt按 UTF-8 读进去得到非法字节源文件是 UTF-8 无 BOM 又没加/utf-8MSVC 按 GBK 读中文 msgid 从源头就烂了。解决本文还有配套的精品资源点击获取 
长河君 · 2026/11/6 10:12:58 · 阅读 1.2k MFC多语言切换实战：gettext PO/MO语言包与资源文本抽取
简介面向在 Visual Studio 2015 下开发全球化桌面软件的 MFC 开发者这份资源围绕「界面多语言切换」这一常见难题展开给出一套可直接编译运行的完整示例。包内共 28 个文件约 1.18MB包含 6 个头文件与 4 个 cpp 源文件承载语言切换核心逻辑2 个 po 与 2 个 mo 语言包配合 POEdit 演示翻译流程另有 rc、rc2 资源脚本、sln 与 vcxproj 工程文件、dll 与 lib 库以及 exe 可执行程序方便对照阅读与直接运行验证。资源从资源文件分语言组织、Gettext 翻译文件管理到 AfxSetResourceHandle 切换资源句柄、LoadString 更新界面文本再到长文本下的界面尺寸适配形成了较完整的实践路径可作为排查字符串未刷新、布局错位等问题的参考。目前已有 1388 人学习下载适合具备一定 MFC 基础、需要为产品补充国际化能力的中级开发者。1. MFC 多语言切换从一次 RC 复制两份的返工说起前年接手某模拟项目X 的 MFC 客户端做中英双语第一版方案很朴素复制一份 .rc把字符串挨个改一遍切语言时重新 LoadFrame。上线三周收到两类反馈模态对话框标题栏还是中文英文环境下设备型号后面的单位变成了方块。返工两天最后推倒重来改成 gettext 的 PO/MO 语言包路线界面文本全部从 .rc 里剥出来集中管理。MFC 多语言切换、界面文本抽取、Poedit 编辑、mo 语言包编译这套组合不新鲜但对编码和加载顺序特别敏感字符集差一个选项中文就是问号资源句柄换晚一步已经打开的对话框纹丝不动。这篇记录按我实际装下来的顺序走一遍从版本选型到验证收口照着做能跑通也能看懂每一步为什么这么配。2. 环境对齐VS 2022 的 MFC 组件、Poedit 3.4 与 gettext 0.21动手前先把四样东西备齐版本错了后面全是白工。这套环境不复杂麻烦的是几个组件名字长得像、装完才发现少一个。2.1 Visual Studio 的 MFC 组件与字符集选项VS 2022 建议 17.8 以上平台工具集 v143如果团队还锁在 VS 2019用 16.11 配 v142 也能跑但 C17 的std::string_view支持和 MFC 头文件的小修补有差异两边混着编译容易出怪问题。安装器里有两个勾选项名字很像工作负载「使用 C 的桌面开发」和单个组件「适用于最新 v143 生成工具的 C MFC (x86 和 x64)」。前者默认只装核心库afxwin.h根本不在里面很多人装完 VS 新建 MFC 项目报「无法打开 afxwin.h」就是漏了这个。稳妥做法是工作负载勾上后切到「单个组件」搜索 MFC把对应工具集那一项手动勾选。装完先确认三处工程属性缺一处后面都要返工位置配置项取值为什么配置属性 → 高级字符集使用 Unicode 字符集MO 里是 UTF-8 窄串最终要转宽字符上屏配置属性 → 常规使用 MFC在共享 DLL 中使用 MFC静态链接会让 exe 膨胀十几兆语言包没必要背这个C/C → 语言C 语言标准ISO C17 (/std:c17)加载器用std::map、std::string别用老标准硬扛字符集这一项是血泪经验。项目如果是从 VC6 或 VS2010 迁上来的很可能还是「使用多字节字符集」CString是CStringASetWindowText走的也是 ANSI 版本中文在某些系统区域设置下直接变问号。改成 Unicode 之后所有CString相关代码要跟着改一遍_T()包裹工作量不小但这是一次性成本越早改越省事。还有一处容易漏发布时共享 DLL 模式要带mfc140u.dll、vcruntime140.dll、msvcp140.dll这一套。要么在目标机装 VC 运行库要么把 DLL 放 exe 同目录。我们后来选的是随包分发省得用户机上版本冲突。2.2 Poedit 与 gettext 命令行装哪个、装在哪Poedit 装 3.4.x 就行免费版够用。它自带msgfmt.exe和msgcat.exe位置在C:\Program Files\Poedit\bin\。但注意——它不带xgettext。Poedit 内部有自己的抽取逻辑可命令行工具没暴露出来所以想从源码批量生成.pot还得单独装 gettext。gettext 用 0.21 的 Windows 二进制包gettext-tools和gettext-runtime两个压缩包解压到C:\tools\gettext\把bin加进系统 PATH。加完开一个新的 PowerShell 窗口验证老窗口 PATH 不会刷新# 三条命令都要能打印版本号缺一条就回去补装 C:\Program Files\Poedit\bin\msgfmt.exe --version xgettext --version msbuild -version如果嫌 gettext 包里的libintl-8.dll和项目其他依赖打架可以只把xgettext.exe和它依赖的libgettextpo拷到独立目录用绝对路径调用。我一般会把xgettext、msgfmt、msgmerge三个 exe 的路径写进项目的构建脚本变量里不依赖全局 PATH换机器时改一行就行。版本上有个参考对照都是实践证明能配合起来的组合组件版本用途备注Visual Studio2022 17.8 / 2019 16.11编译 MFC 工程必须含 MFC 单个组件Windows SDK10.0.19041 以上系统头文件VS 安装器自带即可Poedit3.4.x编辑 PO、预览翻译自带 msgfmt / msgcatgettext0.21xgettext 抽取、msgmerge 合并只用 tools 包runtime 可选不建议上 gettext 0.22 之后的开发版Windows 二进制包不全xgettext有时候链接不上libiconv。0.21 是老版本但稳。2.3 目录与编码约定UTF-8、LC_MESSAGES 与长路径这套东西出问题八成栽在编码和路径上装之前先把约定定死后面谁也别改。源码文件.cpp / .h统一存成UTF-8 with BOM同时在工程属性 C/C → 命令行里加/utf-8。两个都做不是多余BOM 让编辑器正确识别/utf-8让 MSVC 按 UTF-8 读源文件并把执行字符集设成 UTF-8。只做其中一个中文注释里的乱码依然会顺着预编译头污染下去。.po文件全程UTF-8 无 BOMPoedit 默认就是这个别手动改。.rc文件是另一回事VS 资源编辑器保存时按本地代码页走中文环境就是 GBK。稳妥做法是把 .rc 另存为「Unicode (UTF-16 LE)」VS 能正确识别rc.exe也不会抱怨。语言包目录用固定的三级结构跨平台工具链都认这个约定locales/ zh_CN/LC_MESSAGES/app.mo en_US/LC_MESSAGES/app.mo ja_JP/LC_MESSAGES/app.moLC_MESSAGES目录名全大写虽然 Windows 文件系统不区分大小写但你的构建脚本可能跑在别的系统上别给自己埋雷。最后一个坑长路径。exe 装在C:\Program Files\某模拟项目X\下时拼出来的语言包全路径很容易超过 260 字符CFile::Open直接失败还不报错返回 FALSE很多人不检查返回值。两个办法一是给 exe 加longPathAware清单二是把locales放在 exe 同级但控制嵌套层级。我一般直接在Load里加一句路径长度断言超过 240 就ASSERT出来开发期就能发现。3. 资源改造把界面文本从 .rc 里剥出来交给 gettext环境齐了接下来是真正花时间的部分把散落在对话框模板、字符串表、菜单资源里的文本变成 gettext 能抽取、Poedit 能翻译、运行时能查表的形式。3.1 资源模板只留英文运行时按控件回填第一件事是把.rc里所有可见文本改成英文。为什么不是清空因为设计器里得看见布局而且英文作为兜底语言语言包加载失败时界面至少还是可读的英文不会露出一片空白。对话框模板里每一行LTEXT 打开文件,IDC_STATIC,7,7,60,8都要改成英文。控件的ID 一个都不能动因为后面回填文本靠 ID 定位。菜单资源同理顶层菜单和子项的 ID 保持不变CAPTION和MENUITEM的文本改英文。改完还要处理字符串表。原来IDS_FILE_OPEN对应「打开(O)」现在值改英文Open。这一步看着机械但它是整个方案的地基地基是英文中文是「翻译」翻译丢了界面还能用。提示改造前先提交一次版本或者打个 tag。这一步改错很难靠 diff 回滚尤其是几百行的对话框模板。3.2 xgettext 抽取关键字、注释与 .pot 生成代码里所有需要翻译的地方统一用_()宏包起来非界面文本继续用_T()两者泾渭分明。_()的定义放在I18n.h// I18n.h —— 全工程唯一的翻译入口别在别处再定义第二个 #pragma once #include string #include map class CI18n { public: static CI18n Instance(); // strMoPath 传完整路径加载失败返回 false调用方决定用哪种兜底 bool Load(const CString strMoPath); // 查不到就原样返回绝不返回空串否则界面会出现大片空白 CString Tr(const CString strSrc) const; // 按语言标签重载内部会把 zh-CN / zh-Hans 规范成 zh_CN bool Reload(const CString strLangTag); private: std::mapstd::string, std::string m_map; // key 和 value 都存 UTF-8 }; // 界面文本用这个xgettext 认 _ 这个关键字 #define _(s) CI18n::Instance().Tr(_T(s))宏里套了_T()是为了让_(Open)直接产出CString省得调用处到处写转换。但要注意xgettext只认_()里的裸字符串字面量写成_(strText)这种运行时变量它抽不到——这一点在第 5 章会引发一个典型翻车这里先记住。抽取命令xgettext --languageC --from-codeUTF-8 \ --keyword_ \ --add-commentsI18N \ --package-name某模拟项目X --package-version1.0 \ -o locales/app.pot \ src/i18n/*.cpp src/ui/*.cpp src/ui/*.h参数逐个说--languageC决定解析器按 C 语法切分--from-codeUTF-8告诉它源文件是 UTF-8不写这一条中文 msgid 会变成乱码字节--keyword_声明_()括号里的内容是待翻译串如果代码里还用了N_()做延迟翻译再加一个--keywordN_--add-commentsI18N会保留源码里// I18N: 这里是按钮文字这类注释译者在 Poedit 里看得到上下文能省一半沟通成本。.pot是模板文件每次xgettext都会整个覆盖。所以不要直接翻译 .pot已有的翻译要用msgmerge合并进去# 把新模板合并进已有中文 PO--backupnone 不留 .po~ 备份文件 msgmerge --update --backupnone --no-fuzzy-matching \ locales/zh_CN/LC_MESSAGES/app.po locales/app.pot--no-fuzzy-matching是我个人的偏好自动 fuzzy 匹配有时候会把两句话强行凑一起译者一眼没看出来就上线了。宁可让它留空人工补。3.3 对话框文本回填一个递归函数解决八成控件模板里现在是英文代码里也不写死文本中间的桥梁是OnInitDialog里的统一回填。写一个递归函数遍历窗口和所有子控件把当前文本作为 key 去翻译表里查// 递归翻译窗口及其全部子控件找不到译文时保持原样 static void TranslateWindow(CWnd* pWnd) { CString strText; pWnd-GetWindowText(strText); if (!strText.IsEmpty()) { CString strNew CI18n::Instance().Tr(strText); if (strNew ! strText) pWnd-SetWindowText(strNew); } // GW_CHILD 拿第一个子窗口再靠 GW_HWNDNEXT 横向遍历兄弟 CWnd* pChild pWnd-GetWindow(GW_CHILD); while (pChild ! nullptr) { TranslateWindow(pChild); pChild pChild-GetNextWindow(GW_HWNDNEXT); } }逻辑很直白取当前窗口文本非空才查表查到不同才写回然后递归子控件。GW_CHILD只返回第一个子窗口必须配合GW_HWNDNEXT遍历同级链表漏了这一步界面上只有一个控件会被翻译。这个函数依赖一个前提.rc里的英文文本必须出现在.po的 msgid 里。xgettext抽不到资源文件所以得单独跑一个脚本把.rc里的控件文本抠出来# tools/rc2pot.py 从 .rc 里抽控件可见文本输出 pot 片段 import re, sys CTRL r(LTEXT|CTEXT|RTEXT|PUSHBUTTON|DEFPUSHBUTTON|CHECKBOX|RADIOBUTTON|GROUPBOX|CAPTION) PAT re.compile(CTRL r\s((?:[^]|)*)\s*,\s*([A-Za-z_]\w*), re.IGNORECASE) seen, out set(), [] # .rc 存的是 UTF-16LE编码参数别写错否则读出来全是乱码 with open(sys.argv[1], encodingutf-16) as f: text f.read() for m in PAT.finditer(text): txt m.group(2).replace(, ) if not txt or txt in seen: # 同一句话在多个对话框出现只留一条 continue seen.add(txt) out.append(#: %s %s\nmsgid %s\nmsgstr \n % (sys.argv[1], m.group(3), txt)) print(\n.join(out))这个脚本只处理单行文本多行拼接的LTEXT会漏够用就行真遇到再补正则。生成出来的片段不能直接当 pot 用缺文件头用msgcat合并python tools/rc2pot.py res/app.rc build/rc.pot msgcat --use-first locales/app.pot build/rc.pot -o locales/app.pot--use-first保证重复条目取第一个不会因为两个来源都抽到OK就报冲突。3.4 菜单重建DrawMenuBar 那行千万别省菜单是最容易「切了没反应」的地方因为CMenu是句柄资源不是窗口文本TranslateWindow那套对它无效。切换语言时必须整份重建void CMainFrame::SwitchLanguage(const CString strLang) { // 先重载翻译表再动界面顺序反了会用旧表翻新界面 CI18n::Instance().Reload(strLang); CMenu* pOld GetMenu(); if (pOld ! nullptr) pOld-DestroyMenu(); // 必须销毁否则句柄泄漏切十次漏十个 CMenu menuNew; menuNew.LoadMenu(IDR_MAINFRAME); SetMenu(menuNew); // 窗口接管句柄 menuNew.Detach(); // 不 Detach局部对象析构时会把菜单一起销毁 TranslateMenu(GetMenu()); // 自己实现深度优先递归子菜单 DrawMenuBar(); // 少了这句菜单栏保持旧样子不刷新 SetWindowText(_(某模拟项目X)); }三个坑都在这十几行里不DestroyMenu泄漏句柄不Detach会让局部CMenu析构时把刚挂上去的菜单销毁界面上直接没菜单栏不调DrawMenuBar数据变了但画面不更新调试时断点看菜单项文本是对的肉眼看到的还是中文最迷惑人。TranslateMenu的实现和TranslateWindow类似用GetMenuItemCountGetMenuString/ModifyMenu逐项处理遇到MF_POPUP标志就递归子菜单句柄。4. 语言包落地Poedit 出 PO、msgfmt 编 MO、运行时挂载工程改完界面文本都走翻译表了但表还是空的。这一章把.pot变成能加载的.mo再让程序在启动和切换时找到它。4.1 用 Poedit 从 POT 建 PO编码、复数与占位符Poedit 里「文件 → 新建」选locales/app.pot语言填Chinese (Simplified, China)保存到locales/zh_CN/LC_MESSAGES/app.po。项目设置里确认三件事源文本编码 UTF-8、目标语言zh_CN、复数形式nplurals1; plural0;。中文没有复数变化这一条写错不影响显示但msgfmt -c会警告。占位符是另一处必须盯的。代码里_(Found %d device(s))到了中文要写成「找到 %d 台设备」%d一个不能少、顺序不能乱。多个占位符时建议用%1$s、%2$d的带序号写法中文语序和英文不一致时能自由调换msgfmt -c也认这种格式。Poedit 的设置里有个「保存时自动编译 MO」但只能指定一个输出目录多语言场景下每次切语言都要改设置不如关掉统一走命令行编译。注意Poedit 免费版会把未翻译条目在保存时保留为msgstr 这是对的运行时查不到就回退原文。别为了让统计数字好看去填机器翻译界面上一半机翻比全英文更难读。4.2 msgfmt 批量编译与格式校验单个文件编译msgfmt -c -v --statistics \ --output-filelocales/zh_CN/LC_MESSAGES/app.mo \ locales/zh_CN/LC_MESSAGES/app.po-c做格式串校验%s数量对不上、%d类型冲突都会直接报 error 退出这是发布前最有用的一道闸。--statistics打印已翻译和未翻译条数接到 CI 里当门禁未翻译比例超过阈值就失败。--output-file后面必须是.mo手滑写成.po会把文本直接覆盖掉而且msgfmt不拦。多语言一次编完set -e # 任何一条失败立即中断别让半套语言包上线 for po in locales/*/LC_MESSAGES/*.po; do mo${po%.po}.mo msgfmt -c --statistics -o $mo $po echo OK $mo doneset -e是关键。没有它日文那个 po 报错中断后循环继续跑最后打包出来缺一个.mo测试环境才发现。编完顺手msgunfmt反编一个回来看看内容对不对msgunfmt locales/zh_CN/LC_MESSAGES/app.mo | head -40能看到 msgid / msgstr 成对出现就说明二进制结构没问题。4.3 运行时挂载路径查找顺序与 .mo 解析加载器要自己写二十来行比引libintl.dll干净。.mo文件结构很简单前 28 字节是文件头后面两张表分别存原始串和译文的偏移量。// 解析 .momagic(4) revision(4) count(4) origOff(4) transOff(4) hashSize(4) hashOff(4) bool CI18n::Load(const CString strMoPath) { CFile file; if (!file.Open(strMoPath, CFile::modeRead | CFile::shareDenyNone)) return false; // 文件不存在是最常见情况静默回退 const ULONGLONG ullLen file.GetLength(); if (ullLen 28 || ullLen 16 * 1024 * 1024) return false; // 大小异常直接拒绝防止读到脏文件 std::vectorBYTE buf(static_castsize_t(ullLen)); file.Read(buf.data(), static_castUINT(ullLen)); const BYTE* p buf.data(); if (*reinterpret_castconst DWORD*(p) ! 0x950412DE) return false; // 大端包是 0xDE120495这里不处理 const DWORD dwCount *reinterpret_castconst DWORD*(p 8); const DWORD dwOrigTab *reinterpret_castconst DWORD*(p 12); const DWORD dwTransTab *reinterpret_castconst DWORD*(p 16); m_map.clear(); for (DWORD i 1; i dwCount; i) // 0 号是元信息Project-Id-Version 等跳过 { const DWORD dwLenO *reinterpret_castconst DWORD*(p dwOrigTab i * 8); const DWORD dwPosO *reinterpret_castconst DWORD*(p dwOrigTab i * 8 4); const DWORD dwLenT *reinterpret_castconst DWORD*(p dwTransTab i * 8); const DWORD dwPosT *reinterpret_castconst DWORD*(p dwTransTab i * 8 4); // 边界检查不能省损坏的 .mo 会让这里直接越界读崩 if (dwPosO dwLenO ullLen || dwPosT dwLenT ullLen) continue; std::string strKey(reinterpret_castconst char*(p dwPosO), dwLenO); std::string strVal(reinterpret_castconst char*(p dwPosT), dwLenT); if (!strVal.empty()) // 空译文不入表查不到自然回退 m_map[strKey] strVal; } return !m_map.empty(); }查表时的转换是最容易写错的一步。std::string里存的是 UTF-8CString在 Unicode 构建下是 UTF-16中间必须显式走WideCharToMultiByte/MultiByteToWideChar并指定CP_UTF8。用CStringA或者CT2CA会把当前系统代码页简体中文下是 CP936当成 UTF-8key 一个都对不上断点看 map 里明明有数据界面就是不翻译。// 宽字符转 UTF-8唯一正确写法显式指定 CP_UTF8 static std::string ToUtf8(const CString s) { const int n ::WideCharToMultiByte(CP_UTF8, 0, s, s.GetLength(), nullptr, 0, nullptr, nullptr); std::string out(static_castsize_t(n), \0); ::WideCharToMultiByte(CP_UTF8, 0, s, s.GetLength(), out.data(), n, nullptr, nullptr); return out; } CString CI18n::Tr(const CString strSrc) const { auto it m_map.find(ToUtf8(strSrc)); if (it m_map.end()) return strSrc; // 没翻到就回退原文绝不返回空 const int n ::MultiByteToWideChar(CP_UTF8, 0, it-second.c_str(), static_castint(it-second.size()), nullptr, 0); CStringW w; ::MultiByteToWideChar(CP_UTF8, 0, it-second.c_str(), static_castint(it-second.size()), w.GetBuffer(n), n); w.ReleaseBuffer(n); return CString(w); }路径解析我自己定了个优先级exe 同级locales\tag\LC_MESSAGES\app.mo优先然后用户%APPDATA%下的同名目录允许用户自己丢语言包进去最后兜底en_US。语言标签要规范化注册表里存zh-CN、zh-Hans、zh_CN都可能统一转成下划线形式再拼路径转换表写死在一个函数里别散落各处。5. 排查清单多语言切换翻车的五个现场下面五条都是实际遇到过的按「现象 → 原因 → 解决」记遇到类似的直接对号入座。5.1 中文全变问号三处编码没对齐现象英文界面正常切到中文后对话框里一片???部分控件显示方块。原因三处编码任意一处不对都会这样——.rc存成 GBK 但rc.exe按 UTF-8 解析.po被某个编辑器另存成 GB2312msgfmt按 UTF-8 读进去得到非法字节源文件是 UTF-8 无 BOM 又没加/utf-8MSVC 按 GBK 读中文 msgid 从源头就烂了。解决本文还有配套的精品资源点击获取