【Qt】国际化（中英文翻译）——Qt语言家(Linguist)和QTranslator类的简单使用（内含完整源码）

先展示下效果

一、前言

本文代码测试环境：

二、操作步骤

2.1 新建一个 Qt Widgets 工程

新建工程，比较基础，不再具体演示。

2.2 在项目文件(.pro 文件)中添加添加如下代码

TRANSLATIONS += \
    tr_toEnglish.ts     # 其它语言转换为英文
    tr_toChinese.ts     # 其它语言转换为中文

在 Qt 的 .pro 文件中，TRANSLATIONS 是一个用于指定项目需要处理的翻译文件（.ts 文件）的变量。它的作用是告诉 Qt 的构建工具（如 qmake、lupdate 和 lrelease）哪些翻译文件需要被处理。

2.3 添加控件

为了方便演示，我们添加两个 QLabel、一个 QComboBox控件。其中一个 QLabel 让她显示一句英文。如下图所示：

2.4 “更新翻译”

按照下图步骤操作，会生成两个.ts 文件，从名字可以看出这两个.ts 文件就是.pro 中的那个两个文件。

更新成功会输出类似以下内容 （ps:由于我已经点击过“更新翻译”，所以我这里显示 0 个更新，明白怎么回事就好） 。

2.5 使用Linguist(Qt 语言家)生成.qm 文件

2.5.1 打开Linguist

注意Linguist要使用和自己项目对应的版本。比如我的项目使用的“构建套件”是 MSVC2022，则我这里也要使用 MSVC2022 版本的Linguist。如下图所示。

2.5.2 打开.ts文件

建议一次只选择一个.ts文件，翻译完一个再说另一个。

2.5.3 添加翻译

按照下图操作：

2.5.4 点击发布，生成.qm 文件

另一个.ts 文件也是如此操作，重复本章节的 2\ 3\ 4\ 步骤就好了。这样两个.ts文件就会生成两个.qm文件了。

2.6 将生成的.qm文件添加为资源文件

按照下图操作：

2.7 在代码中使用翻译家QTranslator加载.qm资源文件，进行中英文切换

MainWindow.h源码如下：

#ifndef MAINWINDOW_H
#define MAINWINDOW_H

#include <QMainWindow>
#include <QTranslator>  // 翻译家

QT_BEGIN_NAMESPACE
namespace Ui {
class CMainWindow;
}
QT_END_NAMESPACE

class CMainWindow : public QMainWindow
{
    Q_OBJECT

public:
    CMainWindow(QWidget *parent = nullptr);
    ~CMainWindow();


protected:
    void changeEvent(QEvent *event) override;

private slots:
    void on_comboBox_currentIndexChanged(int index);

private:
    Ui::CMainWindow *ui;

    QTranslator m_qTrans;
};
#endif // MAINWINDOW_H

MainWindow.cpp源码如下：

#include "MainWindow.h"
#include "ui_MainWindow.h"

// 构造函数：初始化主窗口
CMainWindow::CMainWindow(QWidget *parent)
    : QMainWindow(parent)  // 调用父类QMainWindow的构造函数
    , ui(new Ui::CMainWindow)  // 初始化UI对象
{
    ui->setupUi(this);  // 加载UI布局，创建界面元素
}

// 析构函数：释放资源
CMainWindow::~CMainWindow()
{
    delete ui;  // 释放UI对象占用的内存
}

/**
 * @brief 重写QWidget的changeEvent方法，处理窗口的各种变化事件
 * @param event 事件对象，包含事件类型和相关信息
 *
 * 说明：
 * changeEvent是Qt框架提供的虚函数，用于处理窗口的"变化事件"，包括：
 * 1. 语言切换（QEvent::LanguageChange）
 * 2. 样式变化（QEvent::StyleChange）
 * 3. 字体变化（QEvent::FontChange）等
 *
 * 这里主要用于处理语言切换事件，当程序语言发生变化时，更新UI上的文本
 */
void CMainWindow::changeEvent(QEvent *event)
{
    // 先调用父类的changeEvent，确保基础事件处理正常
    QWidget::changeEvent(event);

    // 根据事件类型进行不同处理
    switch (event->type())
    {
    case QEvent::LanguageChange:
        // 当事件类型为"语言变化"时，重新翻译UI
        // retranslateUi会根据当前安装的翻译器，更新所有UI元素的文本
        ui->retranslateUi(this);
        break;
    default:
        // 其他类型事件不做额外处理
        break;
    }
}

/**
 * @brief 组合框（下拉框）选中项变化时的槽函数
 * @param index 选中项的索引（0为中文，1为英文）
 *
 * 功能：根据选中的索引加载对应的翻译文件，并安装翻译器
 * 安装翻译器后，Qt会自动发送QEvent::LanguageChange事件，触发上面的changeEvent方法
 * @note
 * - QTranslator::load()方法的返回值被标记为[[nodiscard]]属性，必须处理返回值，
 * 否则编译器会报警告：“C4834: 放弃具有 [[nodiscard]] 属性的函数的返回值”
 */
void CMainWindow::on_comboBox_currentIndexChanged(int index)
{
    bool loadSuccess = false; // 用于接收load()的返回值
    if (0 == index)
    {
        qDebug() << "下标为0，切换为中文";
        // 加载中文翻译文件
        loadSuccess = m_qTrans.load(":/trans/tr_toChinese.qm");
    }
    else
    {
        qDebug() << "下标为1，切换为英文";
        // 加载英文翻译文件
        loadSuccess = m_qTrans.load(":/trans/tr_toEnglish.qm");
    }

    // 检查加载结果
    if (!loadSuccess)
    {
        qWarning() << "翻译文件加载失败！请检查文件路径是否正确";
        return; // 加载失败则不安装翻译器
    }

    // 安装翻译器到应用程序，使翻译生效
    qApp->installTranslator(&m_qTrans);	
    // qApp 是 Qt 提供的全局宏，指向唯一的 QApplication 实例
}

代码关键说明：

1. changeEvent的作用：
   它是 Qt 框架用于处理 “窗口状态变化” 的事件回调函数，当窗口的某些基础属性（如语言、样式、字体等）发生变化时，Qt 会自动调用这个函数。

2. 语言切换的完整流程：
   2.1 用户在下拉框选择语言（触发on_comboBox_currentIndexChanged）
   2.2 程序加载对应的翻译文件并通过installTranslator安装
   2.3 安装翻译器后，Qt 会自动向所有窗口发送QEvent::LanguageChange事件
   2.4 窗口的changeEvent捕获到这个事件，调用ui->retranslateUi(this)更新所有 UI 文本（按钮、标签等的文字）

3. retranslateUi方法的作用：
   这个函数是 Qt 的 uic 工具自动生成的（在 ui_MainWindow.h 中），它会根据当前翻译器，重新设置所有 UI 元素的文本内容，实现界面文字的动态切换。
   

名词解释：
uic：即User Interface Compiler，是一个用于将.ui文件转换为C++代码的工具

三、可能遇到的问题：

3.1 Qt Creator “工具 -> 外部” 没有“语言家”菜单项

参考：

• Qt createor 的外部工具没有语言家菜单项
• https://blog.csdn.net/weixin_44733606/article/details/144618164
• Qt Creator添加外部工具

如果还是不行，不要使用链接中说的那些符号什么的。（比如：%{CurrentDocument:Project:QT_INSTALL_BINS}\lupdate），直接写绝对路径。

比如我本地环境 lupdate.exe的绝对路径是：C:\Qt\6.9.1\msvc2022_64\bin\lupdate.exe

其实就是添加外部工具：