不用Qt Linguist！VSCode+命令行搞定Qt翻译文件(.ts/.qm)全流程

不用Qt Linguist！VSCode+命令行搞定Qt翻译文件(.ts/.qm)全流程

对于追求极致效率和工具链简洁的Qt开发者来说，Qt Linguist虽然功能完整，但有时显得过于“重型”。它需要单独安装、启动，界面切换也打断了在代码编辑器中的沉浸式工作流。如果你已经习惯了VSCode的轻快与强大，并且不畏惧命令行带来的掌控感，那么完全可以将翻译工作的全流程都整合到你熟悉的环境中。这篇文章，就是为你这样偏好轻量化、高效率的开发者准备的。我们将彻底抛开Qt Linguist，探索如何仅凭VSCode和几个简单的终端命令，优雅地完成从源代码标记、.ts文件编辑到.qm文件编译部署的完整国际化（i18n）流程。这不仅关乎工具切换，更是一种对工作流进行深度定制和效率提升的实践。

1. 理解Qt国际化流程的核心与文件本质

在动手替换工具之前，我们必须先厘清Qt国际化到底做了什么。很多人把tr()、.ts、.qm和Qt Linguist视为一个不可分割的整体，其实不然。Qt Linguist只是一个图形化编辑工具，而真正的魔法发生在背后的命令行工具和文件格式上。

整个流程可以简化为三个核心步骤：

1. 提取（Extract）：使用lupdate命令扫描你的项目源代码（.cpp,.h）和界面文件（.ui），找出所有被QObject::tr()或tr()宏包裹的字符串，并将它们收集到一个XML格式的.ts（Translation Source）文件中。
2. 翻译（Translate）：人类翻译者（或开发者自己）编辑这个.ts文件，为每个<source>标签提供对应的<translation>。
3. 发布（Release）：使用lrelease命令将人类可读的.ts（XML文本）文件编译成机器高效的.qm（Qt Message）二进制文件，供运行时动态加载。

关键在于，步骤1和3完全由命令行工具lupdate和lrelease驱动，它们通常随Qt安装包一起提供，与Qt Linguist无关。步骤2——编辑XML文件——任何文本编辑器都能胜任。这就是我们脱离Qt Linguist的理论基础。

.ts文件本质上是一个结构清晰的XML文件。理解它的结构，是用纯文本编辑器高效编辑的前提。一个典型的条目如下：

<message> <location filename="mainwindow.cpp" line="42"/> <source>&File</source> <translation type="unfinished"></translation> </message>

• <location>: 指出了字符串在源码中的位置，方便上下文参考，但对最终翻译结果无影响。
• <source>: 就是你在代码中写的tr(“&File”)。
• <translation>: 这里填写翻译结果，如“文件(&F)”。type="unfinished"属性表示尚未翻译（在Qt Linguist中显示为问号）。翻译完成后，这个属性会被移除。

2. 项目配置与字符串提取（lupdate实战）

首先，我们需要告诉Qt哪些文件需要被扫描。这通过在项目文件（.pro）中添加翻译相关的变量来实现。这与是否使用Qt Linguist无关，是标准配置。

在你的.pro文件中，确保添加如下行：

# 指定生成的.ts文件列表。通常按语言代码命名。 TRANSLATIONS += myapp_zh_CN.ts \ myapp_zh_TW.ts \ myapp_ja_JP.ts # 可选：指定源代码的编码，确保非ASCII字符正确处理 CODECFORTR = UTF-8

注意：TEMPLATE的类型（如app、lib）会影响一些默认行为，但只要你的项目能正常编译，lupdate通常都能正确工作，无需过分纠结于此。

配置好后，就可以进行第一次字符串提取。打开终端（VSCode内置的终端就非常好用），导航到你的项目目录（即.pro文件所在目录）。

基础提取命令：

lupdate your_project.pro

这条命令会读取.pro文件中的SOURCES、HEADERS、FORMS等变量，找到所有文件，并根据TRANSLATIONS变量生成或更新对应的.ts文件。

更灵活的命令行用法：

• 指定源文件：如果你不想依赖.pro文件，可以直接指定源文件。

  lupdate main.cpp widget.cpp widget.ui -ts myapp_zh_CN.ts

• 递归扫描目录：

  lupdate -recursive . -ts myapp_zh_CN.ts

• 排除某些文件或目录：

  lupdate your_project.pro -no-obsolete # 移除源代码中已不存在的过时翻译条目

执行成功后，你会在项目目录下看到myapp_zh_CN.ts等文件。用VSCode打开它，你会看到所有待翻译的字符串列表。

3. 在VSCode中高效编辑.ts文件

现在来到了核心环节：在VSCode中替代Qt Linguist进行翻译工作。纯文本编辑的挑战在于如何高效地定位未翻译项、填写翻译并标记完成。我们可以通过一些VSCode的特性组合来达到甚至超越GUI工具的体验。

3.1 必备的VSCode扩展与配置

首先，安装以下扩展来获得更好的XML/翻译文件编辑体验：

1. XML： 由Red Hat提供。提供XML语法高亮、标签自动闭合、格式化和验证功能，是处理.ts文件的基础。
2. Qt for Python： 虽然主要面向PyQt/PySide，但其对tr()字符串的识别和高亮有时对纯C++项目也有参考价值。
3. Search and Replace或多光标编辑技巧： 用于批量操作。

接下来，进行关键配置。在VSCode的settings.json中，添加针对.ts文件的特定设置：

{ "[typescript]": { // 注意：.ts也关联到TypeScript，我们需要排除它 "editor.formatOnSave": false }, "[xml]": { "editor.formatOnSave": true, "editor.defaultFormatter": "redhat.vscode-xml" }, "files.associations": { "*.ts": "xml" // 将.ts文件强制关联为XML语言模式，避免被识别为TypeScript } }

3.2 翻译工作流技巧

在VSCode中打开一个.ts文件后，你可以采用以下策略：

1. 利用“问题”面板和搜索快速定位：未翻译的条目其<translation>标签是空的或带有type="unfinished"。你可以使用VSCode强大的搜索功能（Ctrl+Shift+F）：

• 搜索正则表达式：<translation type="unfinished">\s*</translation>或<translation></translation>，可以列出所有未完成项。
• 直接搜索type="unfinished"也能达到类似效果。

2. 使用“折叠”功能管理视图：XML扩展支持根据标签折叠。你可以折叠所有已完成的<message>块（即<translation>内有内容且无unfinished属性的），让屏幕集中显示未完成的条目，极大减少视觉干扰。

3. 批量处理与多光标：如果有一系列类似的、简单的字符串需要翻译（例如按钮“OK”、“Cancel”、“Save”），你可以：

• 用搜索找到它们。
• 使用Alt+Click在多行<translation>标签内创建多个光标。
• 同时输入翻译内容，效率极高。

4. 利用代码片段（Snippet）加速输入：对于常见的翻译模式，可以创建自定义代码片段。例如，创建一个插入完整<message>结构的片段，或者一个快速将<translation>标记为完成的片段（即删除type="unfinished"）。

一个翻译前后的对比示例：

翻译前：

<message> <location filename="loginDialog.cpp" line="128"/> <source>Login failed. Please check your credentials.</source> <translation type="unfinished"></translation> </message>

翻译后：

<message> <location filename="loginDialog.cpp" line="128"/> <source>Login failed. Please check your credentials.</source> <translation>登录失败，请检查您的凭据。</translation> </message>

注意type="unfinished"属性被移除了，这等同于在Qt Linguist中打了勾。

3.3 处理特殊情况

• 含占位符的字符串： 代码中tr(“File %1 of %2”).arg(current).arg(total)，在.ts文件中<source>就是“File %1 of %2”。翻译时务必保留%1、%2等占位符及其顺序，例如译为“第 %1 个文件，共 %2 个”。
• 复数形式： Qt支持复数处理，会在.ts文件中生成<numerusform>标签。你需要为每种复数形式提供翻译。中文通常不区分复数，但格式仍需遵守。
• 非QObject类的翻译： 对于没有继承QObject的类（如工具类），需要在类声明中使用Q_DECLARE_TR_FUNCTIONS(MyClass)宏，然后才能使用MyClass::tr()。lupdate同样可以提取这些字符串。

4. 编译与集成：从.ts到.qm再到应用程序

翻译编辑完成后，需要将文本格式的.ts编译成二进制格式的.qm文件，这个过程由lrelease命令完成。

4.1 基础编译命令

在项目根目录的终端中执行：

# 编译单个.ts文件 lrelease myapp_zh_CN.ts # 编译多个.ts文件 lrelease myapp_zh_CN.ts myapp_zh_TW.ts # 使用通配符编译所有.ts文件（最常用） lrelease *.ts # 指定输出.qm文件的路径 lrelease myapp_zh_CN.ts -qm ../build/translations/myapp_zh_CN.qm # 直接针对.pro文件编译，它会自动处理TRANSLATIONS变量中的所有文件 lrelease myproject.pro

执行后，会生成同名的.qm文件（除非用-qm指定了路径）。.qm文件体积小、加载快，是最终随应用程序发布或动态加载的文件。

4.2 自动化脚本集成

为了提高效率，尤其是需要在每次构建后更新翻译时，将lupdate和lrelease集成到你的构建脚本或IDE构建步骤中是明智之举。

一个简单的Bash脚本示例 (update_translations.sh):

#!/bin/bash set -e # 遇到错误即停止 PROJECT_FILE="myproject.pro" TRANSLATION_DIR="translations" echo "Step 1: Updating .ts files from source code..." lupdate $PROJECT_FILE echo "Step 2: Compiling .ts files to .qm files..." cd $TRANSLATION_DIR lrelease *.ts cd .. echo "Translation files updated and compiled successfully."

集成到CMake项目中（如果你使用CMake构建Qt项目）：虽然Qt官方推荐在.pro文件中管理翻译，但CMake也可以通过find_program找到lupdate和lrelease，并创建自定义目标。

# 查找工具 find_program(LUPDATE_EXECUTABLE lupdate) find_program(LRELEASE_EXECUTABLE lrelease) # 定义翻译源文件 set(TS_FILES translations/myapp_zh_CN.ts translations/myapp_en.ts ) # 添加一个自定义目标来更新翻译 add_custom_target(update_translations COMMAND ${LUPDATE_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR} -ts ${TS_FILES} WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR} COMMENT "Updating translation sources..." ) # 添加一个自定义命令，在构建后编译翻译 add_custom_command(OUTPUT ${QM_FILES} # QM_FILES是.ts对应的.qm文件列表 COMMAND ${LRELEASE_EXECUTABLE} ${TS_FILES} DEPENDS ${TS_FILES} WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/translations COMMENT "Compiling translation files..." ) # 然后让你的主目标依赖于这个自定义命令的输出

4.3 在应用程序中动态加载.qm文件

生成.qm文件后，需要在应用程序启动或切换语言时加载它们。以下是一个健壮的加载器函数示例：

#include <QApplication> #include <QTranslator> #include <QDir> #include <QDebug> bool loadTranslation(const QString &locale) { QTranslator *translator = new QTranslator(qApp); // 由QApplication管理生命周期 QString qmFile = QString(":/translations/myapp_%1.qm").arg(locale); // 如果放在资源文件中 // 或者从文件系统加载 // QString qmFile = QDir::applicationDirPath() + "/translations/myapp_" + locale + ".qm"; if (translator->load(qmFile)) { qApp->installTranslator(translator); qDebug() << "Loaded translation:" << qmFile; return true; } else { qWarning() << "Failed to load translation:" << qmFile; delete translator; // 加载失败，需要清理 return false; } } // 在main函数中或语言切换槽中调用 int main(int argc, char *argv[]) { QApplication a(argc, argv); // 设置默认语言，例如从配置文件读取 QString locale = "zh_CN"; loadTranslation(locale); MainWindow w; w.show(); return a.exec(); }

关于界面动态刷新：安装新的QTranslator后，所有通过tr()获取的字符串会自动更新，但UI文件（.ui）中通过QTranslator管理的字符串不会自动刷新。你需要为每一个可能动态切换语言的窗口重写changeEvent或event函数：

// 在主窗口头文件中 protected: void changeEvent(QEvent *event) override; // 在主窗口实现文件中 void MainWindow::changeEvent(QEvent *event) { if (event->type() == QEvent::LanguageChange) { ui->retranslateUi(this); // 关键！重新翻译UI // 也可以在这里手动更新非UI文件创建的控件文本 // customLabel->setText(tr("Custom Text")); } QMainWindow::changeEvent(event); // 调用基类处理 }

确保每个窗口都进行了类似处理，否则当语言切换时，该窗口的界面文字将不会改变。

5. 进阶技巧与故障排查

掌握了基本流程后，一些进阶技巧能让你处理更复杂的场景。

5.1 处理大型项目与模块化翻译

对于由多个子项目或模块组成的大型应用，可以为每个模块维护独立的.ts文件，最后再合并或分别加载。

方法一：独立.pro文件管理。为每个子库或模块创建自己的.pro文件，并配置独立的TRANSLATIONS。分别运行lupdate和lrelease，在主程序中按需加载多个.qm文件。

方法二：使用lupdate的-pro参数合并。创建一个“总控”的.pro文件，用include()引入各个子模块的.pro文件，然后对这个总控文件运行lupdate，可以生成一个统一的.ts文件。

5.2 常见问题与排查表

5.3 版本控制协作建议

.ts文件是XML文本，非常适合用Git等版本控制系统进行管理。在团队协作翻译时，建议：

• 将.ts文件纳入版本控制。
• 不要将.qm文件纳入版本控制，因为它们是从.ts编译生成的二进制文件，应该在构建过程中生成。
• 在.gitignore中添加*.qm。
• 翻译者只需更新.ts文件并提交，CI/CD系统可以在构建时自动执行lrelease命令生成.qm文件并打包。

最后，这套VSCode+命令行的组合拳打下来，你会发现对Qt国际化的理解更深了，因为每一步都是显式、可控的。它剥离了GUI工具的抽象层，让你直接与核心流程和文件对话。刚开始可能会觉得没有Qt Linguist的“翻译完成度”进度条有点不习惯，但用熟了搜索、折叠和多光标，你的翻译效率很可能不降反升。更重要的是，你的开发环境变得更纯粹、更个人化，所有工作都在一个编辑器里完成，这种流畅感才是效率型开发者真正的追求。