Qt多语言国际化实战：Qt Linguist工具链与翻译加载全流程解析

前阵子要把一个 Qt Widgets 客户端改成中英双语，刚开始我想着简单：把所有按钮文字整理成一张 QMap，再根据当前语言查一遍。改到第三个窗口就放弃了——新加一个控件要记得往 map 里塞，对话框里的换行、快捷键、富文本标签全要手工处理，漏一项就是半个英文半个中文。后来老老实实用 Qt 自己那套翻译工具链，也就是大家常说的 Qt 语言家（Qt Linguist），配合 lupdate、lrelease，两天就把所有窗口拉通了。

这篇文章不打算做过多的概念铺垫，直接按我实际跑通一个多语言项目的折腾顺序来写：先在代码里埋好可翻译标记，再让 lupdate 把文本提取成 .ts，用 Qt Linguist 逐条翻译，最后由 lrelease 生成 .qm，程序启动时用 QTranslator 加载。适合正在接手 Qt 国际化、或者打算给现有项目补多语言支持的同学，不管你是 qmake 还是 CMake 都能对上号。

1. 为什么说 Qt Linguist 是 Qt 官方翻译“工位”

很多 Qt 开发者在做多语言时，第一反应都是自己写一套字典表或 ini 配置，我也是这么过来的。但等你真的把一个有三个主窗口、十几个对话框的中型项目跑起来，就会明白为什么 Qt 官方要单独立一套工具链来管翻译。Qt Linguist 不是给你“硬翻字符串”的编辑工具，而是整套国际化流程里的“翻译工位”，它前面有 lupdate 负责扫料，后面有 lrelease 负责把译文压成运行文件。

1.1 一套翻译链路里的三个角色

Qt 的这套方案拆开看，其实非常朴素：

lupdate 在 Windows 上位于 Qt 安装目录的 bin 下，比如我用的 Qt 5.15.2，路径就是 C:\Qt\5.15.2\mingw81_64\bin\lupdate.exe。如果你不想每次敲完整路径，把 Qt 的 bin 目录加进 PATH 会省事很多。注意一点：这三个工具是配套的，版本不要跨得太远。我见过有人用 Qt 5.12 的 lrelease 去编 Qt 5.15 的 ts 文件，虽然大多数时候能过，但遇到新语法或新属性时行为不一定对。

1.2 自己写字典表和这套方案差在哪

自写字典表不是不能用，小工具、两三个窗体的场景确实够用。问题出在维护成本上：源码里每多一个字符串，你就要手动记一笔；同一个文本在不同窗口可能还会因为语义不同需要不同的译文，字典表很难表达这种“上下文差异”。而 lupdate 每次扫描都是从代码里自动捞，漏一个 tr() 是代码问题，漏一条映射就成了数据问题，后者在运行时更难发现。

Qt 这套层级还有一个好处：翻译者通常不需要看代码。给专职翻译或兼职同学一个 .ts 文件，让他们用 Qt Linguist 打开就能干活，不用理解你的工程结构。这对我来说是决定性优势，因为合作对象不一定是 C++ 程序员。

2. 让 lupdate 能“看到”翻译文本：代码与构建配置

想被 lupdate 提取，字符串必须先被正确的“标记”包起来。这里不只是写个注释说“这句要翻译”，而是要调用 tr()、translate() 或 qsTr() 这类接口。有人会问：我界面上明明显示了英文/中文，为什么 ts 文件里是空的？十有八九就是字符串直接写成了 QString s = "Open"; 这种形式。

2.1 用 tr() 把需要翻译的字符串圈出来

在 QWidget 子类内部，最常见的写法是 tr("Open")。注意，tr() 是 QObject 的静态成员函数，如果你写的类没有继承 QObject，比如一个普通的数据处理类，就没有 tr() 可用。这时候有两种选择：把类继承 QObject 并加上 Q_OBJECT 宏，或者用 QCoreApplication::translate()。

我给你看一段我实际改过的代码。原来文件打开成功后，状态栏提示是：

cpp复制statusBar()->showMessage("Opened file: " + fileName);

这种文本 lupdate 完全不认识，而且源码里的英文到运行时才拼接，即使后续想套字典也难。改完是这样：

cpp复制statusBar()->showMessage(tr("Opened file: %1").arg(fileName));

这里有两个关键动作：给原字符串套上 tr()，把变量用 %1 占位符替换。直接拼接字符串是 Qt 多语言改造里最常见的坑，等会儿我会单开一节细说。

如果字符串来自 .ui 文件，其实不需要你在代码里再用 tr 包一遍。Qt Designer 中控件的 text 属性会由 uic 自动生成 QCoreApplication::translate("MainWindow", "Open", nullptr) 这样的调用，所以你在设计器里写的按钮文字天然就能被 lupdate 扫到。真正麻烦的是代码里动态创建的控件：

cpp复制QPushButton *btn = new QPushButton("Save", this);

这类必须改成 new QPushButton(tr("Save"), this)，否则翻译文件里永远缺这条。

2.2 在 pro / CMake 里声明翻译文件

写完了代码标记，还得让构建系统知道你要生成哪些语言的 ts。用 qmake 的话，在 .pro 文件里加一行即可：

pro复制TRANSLATIONS += i18n/myapp_zh_CN.ts \
                i18n/myapp_en.ts

变量名必须是 TRANSLATIONS，如果拼写成 TRANSLATION，lupdate 不会报错，但也不会处理。这个坑我踩过一次，检查了半小时才发现是少了个 s。i18n 目录需要提前创建，lupdate 不会自动帮你建目录。

用 CMake 的朋友，Qt 5 里一般用 qt5_create_translation 或 qt5_add_translation 来处理。类似这样：

cmake复制set(TS_FILES
    i18n/myapp_zh_CN.ts
    i18n/myapp_en.ts
)
qt5_create_translation(QM_FILES ${TS_FILES})

这样做有几个额外好处：lupdate 生成/更新 ts 会成为构建步骤的一部分，源码里的字符串变了会自动同步；生成的 qm 文件路径可以通过 QM_FILES 拿到。不过要注意，自动化虽然省事，但在团队协作里也会出现 lupdate 自动改 ts 导致的提交噪音，我一般还是习惯在发版前手动跑一次 lupdate。

2.3 手动执行 lupdate：看到提取结果才踏实

命令行更新最简单：

bash复制lupdate myapp.pro

如果只想更新某个 ts 文件：

bash复制lupdate -verbose myapp.pro

参数 -no-obsolete 可以顺手清掉源码里已经删掉的无用词条。加 -verbose 能看到扫描了哪些文件、提取了多少条文本，信息很有用。跑完以后，打开 ts 文件确认一下提取结果。如果你发现某条预期中的中文字符串没出现，问题一定出在代码里没用 tr()，而不是 lupdate 本身坏了。

3. Qt Linguist 里的实际操作：逐条翻译、占位符与验证

lupdate 之后，我们就拿到了一个充满待翻译条目的 ts 文件。此时可以把它丢给翻译人员，也可以在 Qt Creator 里通过菜单“工具 -> 外部 -> Qt 语言家 -> 更新翻译”快速打开。我更喜欢直接启动 Qt Linguist，后者界面更接近生产力工具。

3.1 TS 文件到底是什么

. ts 文件本身是 XML，手工打开能看到所有翻译单元。一个最简单条目长这样：

xml复制<context>
    <name>MainWindow</name>
    <message>
        <location filename="mainwindow.cpp" line="42"/>
        <source>Open</source>
        <translation type="unfinished"></translation>
    </message>
</context>

<context> 的 name 是类名，<source> 是源码里的原始文本，<translation> 里填目标语言译文。type="unfinished" 表示这条还没翻译，Qt Linguist 的条目列表里会把它标成黄色。搞清楚这个结构以后，你实际上可以直接手工编辑 XML 填译文，但对于动辄几百条的项目，谁那么干谁傻。

3.2 翻译工作区的核心用法

打开 ts 文件后，Qt Linguist 主窗口分几块：左侧是所有待翻译条目列表，中间是源文本和译文编辑区，下方是当前条目的上下文信息、以及一些警告提示。

操作流程非常固定：

• 鼠标点选左侧某一条，中间会显示源文本和该文本所在的 UI 上下文。
• 在译文编辑区输入对应语言文本。
• 如果该文本在别的窗口已经翻译过，Linguist 会在下方的翻译记忆里提示，直接 Ctrl+C、Ctrl+V 复用即可。
• 完成一条后，按 Ctrl+Return 标记为“已完成”并跳到下一条。

为什么会有“翻译完成”这种状态？因为 .ts 文件允许某些条目暂时不翻译。比如一个字符串在 v1.0 版本里是隐藏的，但代码已经写了，翻译人员可能选择不译。标记状态是一种项目管理手段，而不只是编辑器状态。

在翻译带占位符的字符串时，Linguist 会有明显提示。源文本里的 %1、%2 是运行时替换的变量位置，译文里必须也存在。而且占位符的顺序允许变化，因为不同语言的语序不一样。例如源文本是：

cpp复制tr("%1 files copied to %2")

中文可以译为“已将 %1 个文件复制到 %2”，如果某种语言的表达习惯是先说目标再说数量，也可以写成“%2 收到 %1 个文件”。Linguist 会在下方以小三角或警告图标提醒你“占位符数量不一致”，但不会强行禁止你保存。这里千万不要图省事跳过警告，运行时如果 %1 缺失，用户看到的就是裸的 %1 字样。

3.3 把翻译记忆和短语书用起来

项目大到一定程度，很多公共文本会反复出现。“确定”“取消”“浏览...”这类高频词，纯靠手打效率很低。Qt Linguist 内置了短语书（Phrase Book）和翻译记忆（Translation Memory）。短语书适合团队统一术语，比如规定所有窗口的“OK”按钮都翻译成“确定”，就别在“好”“知道了”之间反复横跳。

短语书的基本用法是：先建立一本 Phrase Book，录入源文本和标准译文，再在翻译时通过菜单调用“使用短语书条目”。翻译记忆则更像输入法的记忆功能，你翻译过一条“Save As”，下个上下文再出现“Save As”，它会自动建议之前的译文。我合作过的翻译人员最喜欢这个功能，因为 Qt 项目里同一个文案在不同上下文出现三五十次是很正常的事。

4. 加载 .qm 并实现在线切换

翻译完成后，千万记得要发布。很多人把 ts 文件拷到程序目录下，然后问为什么运行时界面没变。原因很简单：程序运行时读取的不是 .ts，而是 lrelease 生成的 .qm。这一步在 Qt Linguist 里可以直接操作：菜单“文件 -> Release”，会基于当前 ts 生成同名 qm 文件。

4.1 lrelease 到底做了什么

用命令行更直观：

bash复制lrelease myapp.pro

或者在 Linux/macOS 下单独处理指定文件：

bash复制lrelease i18n/myapp_zh_CN.ts

运行后会在相同目录生成 myapp_zh_CN.qm。qm 是把 xml 里的源文本、译文、上下文关系压缩过的二进制格式，体积比 ts 小一个量级。一个五十万字符的 ts 压下来可能只有一两百 KB，非常适合塞进资源文件或随安装包分发。

4.2 QTranslator 加载翻译文件

运行时加载需要用到 QTranslator，这是一段非常典型的过程：

cpp复制#include <QTranslator>
#include <QCoreApplication>

QTranslator translator;
if (translator.load(":/i18n/myapp_zh_CN.qm")) {
    qApp->installTranslator(&translator);
}

.load() 的第一个参数可以是路径、qrc 路径，也可以是文件名。如果你传入 :/i18n/myapp_zh_CN.qm，它会去资源文件里找。如果 qm 放在 exe 同目录，我建议用：

cpp复制QString qmFile = QCoreApplication::applicationDirPath() + "/translations/myapp_zh_CN.qm";

不要用 QDir::currentPath()，因为从不同工作目录启动程序时，当前目录不一定等于 exe 所在目录。我用 applicationDirPath 踩过的坑是最少的。

要支持运行时切换语言，单纯的加载还不够，因为你得先卸载旧的翻译器。常规做法是先把翻译器存成成员变量或全局指针：

cpp复制void switchLanguage(const QString &locale)
{
    static QTranslator *translator = nullptr;
    if (translator) {
        qApp->removeTranslator(translator);
        delete translator;
        translator = nullptr;
    }

    translator = new QTranslator(qApp);
    QString qmFile = QString(":/i18n/myapp_%1.qm").arg(locale);
    if (!translator->load(qmFile)) {
        delete translator;
        translator = nullptr;
        return;
    }

    qApp->installTranslator(translator);
}

调用时传 "zh_CN" 还是 "en"，取决于 qrc 里 qm 的文件名。如果你想根据系统语言自动选择，可以先取 QLocale::system().name()，比如在中文系统上它通常返回 "zh_CN"，然后拼文件名。

4.3 切换语言后界面为什么没变

新手最容易在这里卡住：翻译器装了，代码也调了，窗口上的文字却纹丝不动。原因在于 installTranslator() 只通知 Qt 事件系统“翻译环境变了”，并不会自动把每个控件的文本重新赋值。那些由 uic 生成的界面，每个窗口里都有一个 retranslateUi() 函数，需要你主动调用。

在 MainWindow 里，重写 changeEvent() 是干净的做法：

cpp复制void MainWindow::changeEvent(QEvent *event)
{
    if (event->type() == QEvent::LanguageChange) {
        ui->retranslateUi(this);
        // 如果是代码手动创建的控件或动态设置的文本，也需要在这里重新赋一遍
        customLabel->setText(tr("Version"));
    }
    QMainWindow::changeEvent(event);
}

为什么用 changeEvent 而不是自己通知？因为 Qt 在安装/卸载翻译器时，会向所有顶层窗口发送 LanguageChange 事件。你只要重写了这个事件，就不需要自己写一套广播机制。每个有界面的类都按这个模式处理，窗口数再多也稳定。

5. 发布与复盘：我踩过的翻译文件坑

多语言改造不是“跑起来就结束了”，真正费时间的是排查漏翻和维护后续新增字符串。我把这两年遇到过的典型问题列出来，看完应该能帮你省下不少调试时间。

5.1 字符串拼接是最常见的漏翻元凶

很多人写代码时习惯把句子劈成几段拼起来：

cpp复制QString msg = "File " + name + " not found, please check the path.";

这种写法 lupdate 无法稳定提取，即使你把它拆成三段分别翻译，译文也很难组织成通顺的目标语言。正确的写法是保留一个带占位符的完整句子：

cpp复制QString msg = tr("File %1 not found, please check the path.").arg(name);

如果项目里这种写法已经泛滥，想快速判断哪里漏了，可以在 lupdate 后打开 ts，搜源码里的常见英文词，比如 “File”、“Error”。凡是搜得到、却被拆成碎片的，基本都要重写。

5.2 占位符和富文本不是普通文字

对话框、帮助信息里经常会出现 HTML 标签。比如：

cpp复制tr("<b>Warning:</b> The file will be deleted.")

Linguist 在翻译时，<b>、</b> 这类标签必须原样保留在译文里。我曾经把 <b> 当成普通英文顺手删了，运行结果整个界面字体风格都对不上，后来才意识到是标签被翻译者清理了。Qt Linguist 在翻译富文本时会把源文本的标签突出显示，如果译文里缺失标签，下方通常会有警告。

至于 %n 复数占位符，是另一个麻烦。英文有单复数，中文则没有严格的名词复数变化。Qt 的复数机制允许翻译者针对不同数量区间写不同翻译。例如源文本：

cpp复制tr("%n file(s) downloaded")

英文需要在 Linguist 里填写单数 “1 file downloaded” 和复数 “%n files downloaded”，中文则只有 “已下载 %n 个文件”。如果你不做复数处理，某些语言环境下运行时可能只显示源字符串或者套用错误的复数形式。

5.3 加载路径、资源文件和 Qt 自带文本的处理

发布程序时，qm 是“运行时依赖”，不是开发期工具。用 qrc 把 qm 打进 exe 是最不容易出问题的方式，尤其适合 Windows 单文件分发。缺点是每次重新生成 qm 后都要记得编译资源，忘了就又是旧译文。如果你把 qm 作为外部文件随安装包分发，路径上请无条件使用 applicationDirPath()，别给用户留手动改目录的机会。

还有一个很隐蔽的问题：QMessageBox 里的标准按钮 “OK”“Cancel”“Yes” 这些文本，其实属于 Qt 自己的翻译文件。你只加载了自己项目的 qm，是翻不动这些标准按钮的。Qt 安装目录的 translations 子目录里通常有 qtbase_zh_CN.qm 这类文件，里面就是 Qt 内置对话框和标准按钮的译文。想要按钮变成中文，还得加载这个 qtbase 翻译文件。我通常会把需要的 qtbase qm 一起打进 qrc：

cpp复制static QTranslator *qtTranslator = new QTranslator(qApp);
if (qtTranslator->load(":/i18n/qtbase_zh_CN.qm"))
    qApp->installTranslator(qtTranslator);

要特别注意加载顺序。一般先加载 Qt 自己的，再加载项目的，否则后加载的覆盖逻辑会乱。这个顺序问题在英文界面切换成中文时尤其明显，标准按钮和自定义按钮文本经常会不同步。

5.4 如何系统性地排查漏翻

漏翻是常态，与其靠肉眼反复测，不如做个系统检查。lupdate 完成之后，在 Qt Linguist 左侧筛选“未翻译”和“未完成”条目，这是一个最基础的查漏动作。另外，ts 文件里 <translation type="unfinished"></translation> 的数量就是一个可量化的指标，你可以在提交代码前固定检查这个数。

我自己常用的一个排漏翻技巧是：在代码里故意使用一条“肯定没有翻译”的占位文案，比如把某个临时按钮设成 tr("__TEST_NO_TRANSLATION__")，然后整体过一遍语言切换，看这个特殊文案是否原样显示。如果它能正确显示，说明翻译加载链路是通的；如果显示的不是这段文案，那问题多半出在信号槽或事件没触发，而不是哪条漏翻了。检查链路和检查漏翻其实是两件事，别把它们混在一起排查。

多语言改完以后，我还会专门把所有界面语言切换到“源语言”跑一版，把所有新增的代码文本临时替换成醒目的字符串，比如 “LANG_MISS|文件名|”，发给测试同学过一遍。凡是界面上出现这个前缀的，就是漏掉的待翻译文本。这个办法虽然笨，但很可靠，比对着代码清单一项项核对高效得多。