翻译失效与动态刷新)
1. 为什么中英文切换在 Qt 项目里总翻车
做过带多语言需求的桌面端项目的人，大概都有过这种体验：界面用 Designer 拖出来的控件，翻译文件一加载，文字刷刷全变了，心里美滋滋；结果一切换到纯代码new出来的按钮、动态生成的菜单项、运行时才拼出来的提示语，立马原形毕露——中文还是中文，英文还是英文，纹丝不动。这个坑我踩过不止一次，后来才彻底搞明白：Qt 的翻译机制不是"自动扫描界面"，而是"按翻译上下文和源文本精确匹配"，凡是没被tr()包起来、或者tr()的上下文对不上的字符串，翻译文件里根本就不会有它的条目，自然也就切不了。
这篇内容就围绕"Qt 语言家（Qt Linguist）实现中英文切换"这件事，重点解决纯代码添加部件的翻译失效问题。所谓 Qt 语言家，指的是 Qt 自带的一整套本地化工具链：lupdate负责从源码里提取待翻译字符串生成.ts文件，Qt Linguist是图形化的翻译编辑器，lrelease把.ts编译成运行时加载的.qm文件，最后程序里用QTranslator把.qm装进去。这套流程本身不复杂，难的是纯代码场景下的几个细节：tr()到底该写在哪个类里、动态创建的部件怎么在切换语言后刷新、retranslateUi这种 Designer 自动生成的东西纯代码项目里没有该怎么办。
适合读这篇的人：正在做 Qt Widgets 桌面项目、需要中英文（或多语言）切换、并且界面里有大量代码动态创建部件的开发者。不管你是刚接触 Qt 本地化的新手，还是被"Designer 能切、代码不能切"折磨过的老手，下面这套从原理到实操再到排坑的完整方案，应该都能直接抄作业。
2. 先搞懂 Qt 翻译的底层逻辑，不然白折腾
2.1 tr() 不是函数调用那么简单，它带着"上下文"
很多人以为tr("确定")就是把"确定"翻译成"OK"，其实远不止。tr()是QObject提供的一个静态函数（准确说是通过Q_OBJECT宏和元对象系统生成的），它调用时隐含了两个关键信息：上下文（context）和源文本（source text）。上下文默认就是调用tr()的那个类的类名。
举个例子，你在MainWindow类里写tr("确定")，那么这条翻译记录在.ts文件里长这样：
<context> <name>MainWindow</name> <message> <source>确定</source> <translation>OK</translation> </message> </context>而如果你在MyDialog类里也写了tr("确定")，那就是另一条独立记录，上下文是MyDialog。同一个"确定"，在不同类里是两条互不相干的翻译条目。这就是为什么有时候你明明翻译了，运行时却没生效——lupdate提取时的上下文，和你运行时查找的上下文对不上。
提示：如果某个字符串你想跨类共用一份翻译，可以用
QCoreApplication::translate("GlobalContext", "确定")显式指定上下文，或者用QT_TR_NOOP/QT_TRANSLATE_NOOP宏先标记、后翻译。
2.2 纯代码部件为什么容易漏翻
Designer 生成的.ui文件在编译时会被uic转成 C++ 代码，里面所有可见文本都会被自动包上tr()，而且上下文统一是那个界面类。所以 Designer 的翻译"天生就对"。
纯代码就不一样了。你手写button->setText("开始")，这个"开始"就是个普通字符串字面量，lupdate扫描源码时根本不会把它当成待翻译文本，.ts文件里没有它，.qm里自然也没有，切换语言时它当然不变。解决办法只有一个：所有需要翻译的用户可见字符串，必须显式用tr()或QCoreApplication::translate()包起来。
这里有个隐蔽的坑：tr()只能在有Q_OBJECT宏的QObject派生类里用。如果你在一个普通工具类、命名空间函数、或者 lambda 里直接写tr()，编译可能过（因为可能继承了某个带 tr 的基类），但上下文会乱，或者干脆编译不过。这种场景就得用QObject::tr()或QCoreApplication::translate()并显式给上下文。
2.3 语言切换的本质：卸载旧翻译器、装新翻译器、重刷界面
运行时切换语言，核心就三步：
- 把旧的
QTranslator从QApplication上removeTranslator()卸下来； load()新的.qm文件并installTranslator()装上去；- 手动触发界面刷新——因为已经创建好的部件不会自动重新读取文本。
第三步是纯代码项目最容易忽略的。Designer 项目里，uic生成的类会有一个retranslateUi()函数，Qt 在收到QEvent::LanguageChange事件时会自动调用它重设所有文本。但纯代码项目没有这个函数，你得自己写一个等价的"重新设置所有文本"的方法，并在changeEvent()里捕获LanguageChange事件来调用它。
3. 完整实操：从零搭一套可切换的中英文方案
3.1 工程准备与 .pro 配置
假设我们有一个纯代码的 Widgets 项目，主窗口里有一个标签、一个按钮、一个动态生成的菜单。先在.pro文件里声明翻译文件：
QT += core gui widgets TARGET = LangDemo TEMPLATE = app SOURCES += main.cpp mainwindow.cpp HEADERS += mainwindow.h # 声明翻译文件，lrelease 会自动处理 TRANSLATIONS += lang_zh_CN.ts \ lang_en_US.tsTRANSLATIONS这一行很关键，它告诉lupdate要生成哪些.ts文件。命名建议用lang_语言_地区.ts的规范格式，方便后续按 locale 自动匹配。
3.2 用 tr() 正确包裹纯代码字符串
先看主窗口头文件，重点是继承QWidget并带Q_OBJECT：
// mainwindow.h #ifndef MAINWINDOW_H #define MAINWINDOW_H #include <QWidget> #include <QLabel> #include <QPushButton> #include <QMenuBar> class MainWindow : public QWidget { Q_OBJECT public: explicit MainWindow(QWidget *parent = nullptr); protected: // 捕获语言切换事件 void changeEvent(QEvent *event) override; private: void retranslateUi(); // 自己实现的"重刷文本" void createMenus(); // 动态创建菜单 QLabel *m_label; QPushButton *m_button; QMenu *m_fileMenu; QAction *m_openAction; }; #endif注意retranslateUi()是我们自己声明的，不是 Designer 生成的。所有需要翻译的文本设置都集中放在这个函数里，切换语言时重新调一次即可。
实现文件：
// mainwindow.cpp #include "mainwindow.h" #include <QVBoxLayout> #include <QEvent> #include <QApplication> #include <QTranslator> MainWindow::MainWindow(QWidget *parent) : QWidget(parent) { auto *layout = new QVBoxLayout(this); m_label = new QLabel(this); m_button = new QPushButton(this); layout->addWidget(m_label); layout->addWidget(m_button); createMenus(); retranslateUi(); // 首次设置文本 } void MainWindow::createMenus() { auto *bar = new QMenuBar(this); m_fileMenu = bar->addMenu(QString()); // 文本留空，交给 retranslateUi m_openAction = m_fileMenu->addAction(QString()); m_openAction->setObjectName("openAction"); } void MainWindow::retranslateUi() { setWindowTitle(tr("语言切换演示")); m_label->setText(tr("这是一个纯代码创建的标签")); m_button->setText(tr("点击我")); m_fileMenu->setTitle(tr("文件")); m_openAction->setText(tr("打开")); } void MainWindow::changeEvent(QEvent *event) { if (event->type() == QEvent::LanguageChange) { retranslateUi(); // 语言变了，重刷所有文本 } QWidget::changeEvent(event); }这里有几个关键点值得展开说。第一，createMenus()里创建菜单和动作时，文本故意传空字符串，真正的文本全部放到retranslateUi()里设置。这样做的好处是文本设置只有一处，不会出现"创建时设一遍、切换时又设一遍"的重复和遗漏。第二，changeEvent()里必须调用父类的changeEvent()，否则可能影响其他事件的正常处理。第三，retranslateUi()里所有字符串都用tr()包裹，上下文就是MainWindow。
3.3 生成 .ts 文件并翻译
配置好之后，在项目目录执行：
lupdate LangDemo.pro这会生成lang_zh_CN.ts和lang_en_US.ts。用 Qt Linguist 打开，你会看到MainWindow上下文下的所有条目。把lang_en_US.ts里的翻译填上：
| 源文本 | 英文翻译 |
|---|---|
| 语言切换演示 | Language Switch Demo |
| 这是一个纯代码创建的标签 | This is a label created in pure code |
| 点击我 | Click Me |
| 文件 | File |
| 打开 | Open |
翻译完保存，再执行：
lrelease LangDemo.pro生成.qm文件。.qm是二进制格式，体积小、加载快，是运行时真正用的文件。.ts是 XML 文本，只用于编辑和版本管理。
注意：每次改了源码里的
tr()字符串，都要重新跑一遍lupdate，否则.ts里不会有新条目。建议把lupdate和lrelease写进构建脚本，避免手动遗漏。
3.4 运行时加载与切换
主函数里先加载默认语言：
// main.cpp #include "mainwindow.h" #include <QApplication> #include <QTranslator> #include <QLocale> int main(int argc, char *argv[]) { QApplication app(argc, argv); QTranslator translator; // 根据系统 locale 自动加载对应 qm QString locale = QLocale::system().name(); // 如 zh_CN if (translator.load("lang_" + locale, ":/translations")) { app.installTranslator(&translator); } MainWindow w; w.show(); return app.exec(); }切换语言的逻辑，通常放在一个菜单动作或按钮里：
void MainWindow::switchLanguage(const QString &lang) { // 1. 卸载旧翻译器 qApp->removeTranslator(&m_translator); // 2. 加载新翻译器 if (m_translator.load("lang_" + lang, ":/translations")) { qApp->installTranslator(&m_translator); } // 3. installTranslator 会自动给所有顶层窗口发 LanguageChange 事件， // 我们的 changeEvent 会捕获并调用 retranslateUi }m_translator需要作为成员变量，不能是局部变量——局部变量出了作用域就析构了，翻译器一没，翻译立刻失效。这是新手常犯的错误，我当年也栽过。
4. 动态部件与运行时字符串的进阶处理
4.1 动态创建的部件怎么跟着切
上面retranslateUi()能生效的前提是：部件的指针被保存下来了。如果你在某个函数里临时new一个QLabel加进布局，指针没存，切换语言时你根本找不到它，自然没法重设文本。
所以纯代码项目里，凡是需要翻译的动态部件，指针都要用成员变量或容器保存。如果部件数量不定（比如根据配置动态生成一堆），可以用QList<QLabel*>之类的容器存起来，retranslateUi()里遍历重设：
void MainWindow::retranslateUi() { for (int i = 0; i < m_dynamicLabels.size(); ++i) { m_dynamicLabels[i]->setText(tr("动态项 %1").arg(i + 1)); } }这里tr("动态项 %1")里的%1是占位符，翻译时英文写成Dynamic Item %1即可，arg()会在翻译后替换。占位符一定要放在tr()里面，别写成tr("动态项") + QString::number(i)，那样翻译文件里只有"动态项"，数字拼接逻辑是死的，英文语序一变就乱套。
4.2 运行时拼接的字符串怎么翻译
有些文本是运行时才拼出来的，比如状态栏提示"已加载 5 个文件"。这种要用带占位符的tr()：
statusBar()->showMessage(tr("已加载 %1 个文件").arg(count));翻译文件里对应条目是Loaded %1 files。这样语序、单复数（虽然 Qt 的tr不直接处理单复数，但可以用tr(..., ..., n)的三参数形式）都能灵活处理。
还有一种情况是字符串在非 QObject 类里。比如一个纯数据类要返回可翻译的提示，可以用QCoreApplication::translate()：
QString msg = QCoreApplication::translate("DataModule", "数据校验失败");上下文显式写成"DataModule"，lupdate也能正确提取（前提是它认识这个函数调用，lupdate对translate是有识别的）。
4.3 用 QT_TR_NOOP 处理静态数组
有时候你有一组固定的字符串放在静态数组里，比如：
static const char *const colors[] = { QT_TR_NOOP("红色"), QT_TR_NOOP("绿色"), QT_TR_NOOP("蓝色") };QT_TR_NOOP的作用是"标记但不翻译"——它让lupdate知道这些字符串需要提取，但运行时不会立即翻译。真正用的时候再手动翻：
label->setText(tr(colors[i]));这样既保证了lupdate能提取到，又保证了运行时按当前语言翻译。如果直接写tr("红色")放在静态初始化里，可能因为初始化时机早于翻译器安装而失效，QT_TR_NOOP就是解决这个时机问题的。
5. 常见问题排查速查表
纯代码中英文切换的坑，翻来覆去就那么几个。我把实际项目中遇到的高频问题整理成表，方便对照排查。
| 现象 | 可能原因 | 排查与解决 |
|---|---|---|
| Designer 能切，代码部件不变 | 字符串没用tr()包裹 | 检查所有setText/setTitle，确认参数是tr(...) |
| 翻译文件里有条目，运行时不生效 | 上下文不匹配 | 确认tr()所在类与.ts里<name>一致 |
| 切换后部分文本变了部分没变 | 没实现retranslateUi或没捕获LanguageChange | 检查changeEvent是否处理了QEvent::LanguageChange |
| 切换语言后程序崩溃 | 翻译器是局部变量，已析构 | 把QTranslator改成成员变量或全局变量 |
| 新加的字符串翻译不出来 | 没重新跑lupdate | 改完源码重新lupdate+lrelease |
| 占位符翻译后错位 | 占位符写在tr()外面 | 把%1等占位符放进tr()内部 |
| 中文显示成乱码 | 源文件编码或.ts编码问题 | 源码统一 UTF-8，.ts保存为 UTF-8 |
| 菜单/工具栏文本不刷新 | 菜单动作文本没在retranslateUi里重设 | 把QAction::setText也纳入重刷逻辑 |
除了表里这些，还有两个经验性的坑值得单独说。
第一个是默认语言的处理。很多项目默认语言是中文，源码里写的也是中文，那么中文其实不需要翻译文件——tr()找不到翻译时原样返回源文本，正好就是中文。这种情况下只需要一个英文.qm。但要注意，如果系统 locale 是英文，程序启动时就得加载英文翻译器，否则会显示中文源文本。所以启动时的 locale 判断逻辑要写对。
第二个是翻译文件的加载路径。开发时用相对路径没问题，打包发布后路径变了，load()就失败。稳妥做法是把.qm放进 Qt 资源文件（.qrc）里，用:/translations/lang_en_US这种资源路径加载，跟可执行文件走，不会丢。
<!-- resources.qrc --> <RCC> <qresource prefix="/translations"> <file>lang_zh_CN.qm</file> <file>lang_en_US.qm</file> </qresource> </RCC>提示：
.qm是编译产物，一般不入版本库，但入资源文件的话就得保证构建时先生成.qm再编译资源。可以在.pro里加自定义构建步骤，或者干脆把生成的.qm也纳入管理，看团队习惯。
6. 我踩过的坑和几条实用心得
说几个文档里不太会写、但实际项目里特别容易中招的点。
关于tr()的上下文继承。如果你的类继承链比较深，比如MyButton : public QPushButton，在MyButton里写tr("确定")，上下文是MyButton而不是QPushButton。这本身没问题，但如果你在基类里写了tr()，子类实例化后调用的是基类的方法，上下文还是基类。理解这一点，排查上下文不匹配时能省很多时间。
关于 lambda 里的翻译。在 lambda 里直接写tr()通常编译不过，因为 lambda 不是类的成员函数。解决办法是用QObject::tr()或者捕获this后调this->tr()。但更推荐的做法是：lambda 里不要直接写死文本，而是调用一个专门的翻译函数，把文本集中管理。
关于翻译的粒度。不要把整句话拆成单词分别翻译再拼接，比如tr("已") + tr("加载") + tr("文件")，这种在英文里语序完全对不上。永远以完整的句子或短语为单位翻译，需要变量就用占位符。
关于测试。切换语言后，别只看主界面，菜单、右键菜单、状态栏、对话框、工具提示（tooltip）都要过一遍。这些地方最容易漏。我一般会写一个简单的遍历测试：切换语言后，递归遍历所有子部件，打印它们的文本，肉眼扫一遍有没有漏网的中文。
关于翻译文件的版本管理。.ts是文本，适合入版本库，方便追踪翻译变更。.qm是二进制，每次构建都重新生成，不入库。团队协作时，.ts的冲突要小心处理，最好约定谁负责哪个模块的翻译，减少同时编辑同一个文件。
最后分享一个提高效率的小技巧：在retranslateUi()里，把同一类部件的文本设置按顺序排列，和界面上的视觉顺序保持一致。这样以后加新部件时，照着位置就能找到该在哪加一行，不容易漏。这个习惯坚持下来，纯代码项目的多语言维护成本会低很多。
整套方案跑通之后，你会发现纯代码的中英文切换其实和 Designer 一样可靠，关键就是把tr()用对、把retranslateUi()写全、把LanguageChange事件接住。剩下的就是耐心和细致了。
