根本原因是qtranslator加载路径错误或未在qapplication构造后、show()前安装，必须显式调用installtranslator()且检查返回值；tr()仅对qobject子类成员函数内调用有效；切换语言需手动调用retranslateui()或重写changeevent；源码须utf-8无bom，字体需支持unicode。
Qt Linguist 生成的 .qm 文件不生效，程序仍显示源码字符串
根本原因通常是 QTranslator 加载路径错误或未在 QApplication 构造后、show() 前完成安装。Qt 不会自动查找或加载 .qm，必须显式调用 installTranslator()。
-
.qm文件必须放在运行时可访问路径（如:/translations/zh_CN.qm或./translations/zh_CN.qm），不能只放在源码目录里 - 资源文件（
.qrc）中需声明translations/前缀，且QTranslator::load()的路径参数要与之匹配（例如":/translations/zh_CN"） - 必须在
QApplication实例创建之后、任何界面控件初始化之前调用installTranslator()，否则已创建的控件不会重译 - 检查
QTranslator::load()返回值——返回false表示路径错、格式错或语言不匹配，别忽略它
tr() 不起作用：哪些字符串能被 lupdate 提取
tr() 只对类成员函数内、继承自 QObject 的类中定义的字符串生效；裸函数、全局变量、非 QObject 类里的 tr() 调用会被 lupdate 忽略，也不会翻译。
- 确保类声明含
Q_OBJECT宏，且使用 moc 编译（CMake 中启用set_property(SOURCE xxx.cpp PROPERTY AUTOMOC ON)） -
tr("Save")可以，但QObject::tr("Save")或QCoreApplication::translate("Context", "Save")需手动加CONTEXT注释才能被提取 - 动态拼接字符串（如
tr("File ") + name + tr(" not found")）会导致上下文割裂，建议改用tr("File %1 not found").arg(name) - 中文等无复数的语言也要写
tr("item")和tr("items")两行，否则切换英文时单复数逻辑失效
切换语言时界面不刷新，按钮/菜单文字不变
Qt 不会自动重绘所有控件来响应语言变更，retranslateUi() 是必需的手动步骤，尤其对 Qt Designer 生成的界面。
- 在 UI 类（如
Ui_MainWindow）中，Designer 自动生成的setupUi()会绑定一次文本，切换语言后必须显式调用retranslateUi(this) - 若用纯代码构建界面，需自己重写
changeEvent(QEvent* e)，当e->type() == QEvent::LanguageChange时更新所有控件文本 - 自定义控件若含文本，也得重写
changeEvent()并调用父类实现，否则它们永远卡在初始语言 - 注意：调用
retranslateUi()前，确保新QTranslator已安装且旧的已removeTranslator()，否则可能混用两种语言
中文乱码、特殊字符显示为方块或问号
根源是源码文件编码与 lupdate 解析不一致，或运行时字体不支持 Unicode 字符集。
- 所有
.cpp和.h文件必须保存为 UTF-8 无 BOM 格式（VS Code / Qt Creator 默认支持，记事本容易存成 GBK） -
lupdate默认按系统 locale 解析源码，Windows 上可能误判为 GBK；强制指定用lupdate -codec UTF-8 - Qt 6 默认使用 UTF-8，但 Qt 5 需在
main()开头加QTextCodec::setCodecForLocale(QTextCodec::codecForName("UTF-8"))（仅 Qt 5） - 确保界面使用的字体（如
QFont）支持中文，比如"SimSun"、"Noto Sans CJK SC"，默认"Sans Serif"在某些系统上会 fallback 失败
Qt 国际化真正的难点不在配置，而在“时机”——QTranslator 安装顺序、retranslateUi() 触发时机、tr() 调用上下文，三者错一个，就卡在某个环节不动。很多人反复检查 .qm 文件是否存在，却忘了 installTranslator() 是在 QApplication 构造之后才有效的。
C++免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 C++ 的入门与实战技巧！
