# QmlTran

**Repository Path**: kid-kid/qml-tran

## Basic Information

- **Project Name**: QmlTran
- **Description**: QtQuick6之QML实现界面多语言翻译

- **Primary Language**: C++
- **License**: LGPL-2.1
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-26
- **Last Updated**: 2026-01-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README


# QtQuick6之QML实现界面多语言翻译


---

基于 Qt 官方文档中的 [Qt Linguist 手册](https://doc.qt.io/qt-6//qtlinguist-index.html)  示例   **[Localized Clock with Runtime Language Switch](https://doc.qt.io/qt-6/qtlinguist-localizedclock-switchlocale-example.html)** ，提供一个 **完整、可编译、可运行的 CMake 项目** 。

![1769409258902](image/readme/1769409258902.png)

✅ 运行时点击按钮切换语言（中/英）
✅ 使用 QML + C++ 架构
✅ 基于 Qt 6

---



最终效果，点击不同的按钮切换为不同语言：

![1769408182833](image/readme/1769408182833.png)


---

## 📁 项目结构

```
📦QmlTran
├── CMakeLists.txt
├── main.cpp
├── translatormanager.h
├── translatormanager.cpp
├── Main.qml
```

---

## 🔧 1. 添加翻译文件

这里添加了一个中文的一个英文的。

![1769397718060](image/readme/1769397718060.png)

添加文件后无需手动修改CMakeLists，Qt会自动添加到CMakeLists中

![1769397840302](image/readme/1769397840302.png)

---

## 🧠 2. 更新并发布翻译文件

默认添加的.ts文件是空的，需要先将qml中的文件通过 `cmake --build . --target update_translations`命令更新一下把要转换的文字导入到.ts文件中。

### ①更新翻译文件

在项目可执行程序目录下运行下面这条命令，以更新翻译文件：

```cmake
cmake --build . --target update_translations
```

![1769407304702](image/readme/1769407304702.png)

在命令行中可以看到更新了文件。



### ②增加翻译并发布翻译文件

✅更新.ts翻译文件

![1769407731321](image/readme/1769407731321.png)


✅发文翻译文件

![1769407858934](image/readme/1769407858934.png)


### ③添加翻译文件到工程

将最终的翻译文件添加到工程中

![1769408045501](image/readme/1769408045501.png)





## 🧠 3. 添加翻译类

translatormanager翻译类基于 Qt 官方文档中的 **[Localized Clock with Runtime Language Switch](https://doc.qt.io/qt-6/qtlinguist-localizedclock-switchlocale-example.html)** 示例，只修改了其中翻译文件的路径：

![1769408361227](image/readme/1769408361227.png)


**translatormanager.cpp**

```cpp
// Copyright (C) 2025 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause

#include "translatormanager.h"

#include <QGuiApplication>

using namespace Qt::Literals::StringLiterals;

TranslatorManager::TranslatorManager(QQmlEngine &engine) : m_engine(engine) { }

TranslatorManager *TranslatorManager::create(QQmlEngine *engine, QJSEngine *)
{
    return new TranslatorManager(*engine);
}

void TranslatorManager::switchLanguage(const QString &lang)
{
    QLocale locale(lang);
    QLocale::setDefault(locale);
        qDebug() << "Actual locale name:" << locale.name(); // 添加这行调试
    qApp->removeTranslator(&m_translator); // not necessary from Qt 6.10
    // if (m_translator.load(locale, "clock"_L1, "_"_L1, ":/i18n"_L1)) {
    if (m_translator.load(locale, "QmlTran"_L1, "_"_L1, ""_L1)
        && qApp->installTranslator(&m_translator)) {
        m_engine.retranslate();
    } else {
        qWarning("Could not load translation to %s!", qPrintable(locale.name()));
    }
}

```

**translatormanager.h**

```
// Copyright (C) 2025 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause

#ifndef TRANSLATORMANAGER_H
#define TRANSLATORMANAGER_H

#include <QQmlEngine>
#include <QTranslator>

class TranslatorManager : public QObject
{
    Q_OBJECT
    QML_SINGLETON
    QML_ELEMENT
public:
    explicit TranslatorManager(QQmlEngine &engine);

    static TranslatorManager *create(QQmlEngine *engine, QJSEngine *);
    Q_INVOKABLE void switchLanguage(const QString &lang);

private:
    QTranslator m_translator;
    QQmlEngine &m_engine;
};
#endif // TRANSLATORMANAGER_H

```

🧠🧠🧠只需要将translatormanager工具类添加到工程中即可在QML前端使用，无需在Main.cpp中引用，因为translatormanager语言管理类型中使用了**QML_SINGLETON**和**QML_ELEMENT** 自动将当前类注册为单例类在qml

中可以直接使用。

---

## 🖥️ 4. QML 前端：使用翻译类


![1769408452905](image/readme/1769408452905.png)


另外，也可以在界面加载的时候直接读取翻译文件：

![1769408555731](image/readme/1769408555731.png)



```cpp
//main.cpp
#include <QGuiApplication>
#include <QQmlApplicationEngine>
#include <QTranslator>
#include <QDebug>
int main(int argc, char *argv[])
{
    QGuiApplication app(argc, argv);

    QTranslator qtr;

    if(!qtr.load("./QmlTran/QmlTran_en_US.qm"))
    {
        qDebug("install error");
    }

    app.installTranslator(&qtr);

    QQmlApplicationEngine engine;
    QObject::connect(
        &engine,
        &QQmlApplicationEngine::objectCreationFailed,
        &app,
        []() { QCoreApplication::exit(-1); },
        Qt::QueuedConnection);
    engine.loadFromModule("QmlTran", "Main");

    return app.exec();
}


```



```qml
//Main.qml
import QtQuick
import QtQuick.Controls

Window {
    width: 640
    height: 480
    visible: true
    title: qsTr("Hello World")

    Label {
        id: label
        x: 90
        y: 111
        width: 124
        height: 63
        text: qsTr("english")
        horizontalAlignment: Text.AlignHCenter
        verticalAlignment: Text.AlignVCenter
        font.pointSize: 20
        font.bold: true
    }

    Label {
        id: label1
        x: 381
        y: 111
        width: 124
        height: 63
        text: qsTr("chinese")
        horizontalAlignment: Text.AlignHCenter
        verticalAlignment: Text.AlignVCenter
        font.pointSize: 20
        font.bold: true
    }

    Button {
        id: button
        x: 393
        y: 285
        text: qsTr("Chinese")
        onClicked:{
            console.log("Chinese")
            TranslatorManager.switchLanguage("zh")
        }
    }

    Button {
        id: button1
        x: 102
        y: 285
        text: qsTr("english")
        onClicked:{
            console.log("english")
            TranslatorManager.switchLanguage("en")
        }
    }
}

```

---

---



## 📌 总结


基于 Qt 官方文档中的 **[Localized Clock with Runtime Language Switch](https://doc.qt.io/qt-6/qtlinguist-localizedclock-switchlocale-example.html)** 示例，提供一个 **完整、可编译、可运行的 CMake 项目** 。

> 🔗 完整代码结构与逻辑与 [Qt 官方 localizedclock-switchlocale](https://doc.qt.io/qt-6//qtlinguist-localizedclock-switchlocale-example.html) 一致，但更简洁、独立、易集成。

你可以在此基础上轻松扩展更多语言（如 `fr`, `ja`, `de`）！