Qt 國際化與本地化完整解決方案

在全球化的今天，軟件支持多語言和本地化（Internationalization & Localization，簡稱i18n & l10n）已成為基本需求。Qt提供了一套完整的解決方案，幫助開發者輕松實現應用程序的國際化支持。本文將從原理到實踐，詳細介紹Qt國際化與本地化的實現方法。

一、基本概念

國際化（Internationalization, i18n）：設計和編寫應用程序，使其無需修改代碼即可支持多種語言和地區。
本地化（Localization, l10n）：根據特定語言和地區的需求，對應用程序進行適配（如翻譯文本、調整日期格式、貨幣符號等）。
Qt術語：
- 源文本（Source Text）：代碼中直接編寫的原始文本（通常是英文）。
- 翻譯文件（.ts）：包含源文本及其翻譯的XML文件。
- QM文件（.qm）：編譯后的二進制翻譯文件，由.ts文件生成。
- QTranslator：Qt中負責加載和應用翻譯的類。

二、國際化實現步驟

1. 標記需要翻譯的文本

使用QObject::tr()或QT_TRANSLATE_NOOP()宏標記需要翻譯的文本：

// 簡單文本
label->setText(tr("歡迎使用我的應用"));// 帶參數的文本
QString message = tr("已選擇 %1 項").arg(selectedCount);// 上下文相關的文本（用于區分相同文本在不同上下文中的翻譯）
QString title = QT_TRANSLATE_NOOP("DialogTitle", "設置");
dialog->setWindowTitle(qApp->translate("DialogTitle", title));// 菜單和工具欄文本
fileMenu->setTitle(tr("文件"));

2. 創建翻譯文件（.ts）

使用lupdate工具掃描源代碼，提取需要翻譯的文本并生成.ts文件：

# 語法
lupdate your_project.pro -ts translations/zh_CN.ts translations/en_US.ts# 示例（假設項目文件為myapp.pro）
lupdate myapp.pro -ts translations/zh_CN.ts translations/en_US.ts

.pro文件需包含所有源代碼和UI文件路徑：

SOURCES += main.cpp \mainwindow.cpp \dialog.cppTRANSLATIONS += translations/zh_CN.ts \translations/en_US.ts

3. 翻譯文本

使用Qt Linguist工具打開.ts文件進行翻譯：

linguist translations/zh_CN.ts

Qt Linguist提供直觀的界面，顯示源文本和待翻譯文本。
翻譯完成后保存.ts文件。

4. 編譯翻譯文件（生成.qm）

使用lrelease工具將.ts文件編譯為二進制.qm文件：

# 語法
lrelease translations/zh_CN.ts translations/en_US.ts# 或直接從.pro文件生成所有翻譯
lrelease myapp.pro

5. 在應用程序中加載翻譯

在應用程序啟動時加載所需的翻譯文件：

#include <QApplication>
#include <QTranslator>
#include <QLocale>int main(int argc, char *argv[])
{QApplication a(argc, argv);// 創建翻譯器QTranslator translator;// 根據系統語言加載對應的翻譯文件QString locale = QLocale::system().name(); // 例如："zh_CN"if (translator.load(":/translations/app_" + locale)) {a.installTranslator(&translator);}// 或強制指定語言// if (translator.load(":/translations/app_zh_CN")) {//     a.installTranslator(&translator);// }// 顯示主窗口MainWindow w;w.show();return a.exec();
}

三、高級技巧

1. 動態切換語言

允許用戶在運行時切換語言，無需重啟應用程序：

// MainWindow.h
class MainWindow : public QMainWindow {Q_OBJECT
public:MainWindow(QWidget *parent = nullptr);private slots:void changeLanguage(const QString &locale);private:QTranslator *appTranslator;
};// MainWindow.cpp
MainWindow::MainWindow(QWidget *parent) : QMainWindow(parent) {appTranslator = new QTranslator(this);// 創建語言菜單QMenu *languageMenu = menuBar()->addMenu(tr("語言"));QActionGroup *langGroup = new QActionGroup(this);QAction *chineseAction = langGroup->addAction("中文");chineseAction->setCheckable(true);connect(chineseAction, &QAction::triggered, this, [this](){changeLanguage("zh_CN");});QAction *englishAction = langGroup->addAction("English");englishAction->setCheckable(true);connect(englishAction, &QAction::triggered, this, [this](){changeLanguage("en_US");});languageMenu->addActions(langGroup->actions());// 根據當前語言設置默認選中項QString currentLocale = QLocale::system().name();if (currentLocale.startsWith("zh")) {chineseAction->setChecked(true);} else {englishAction->setChecked(true);}
}void MainWindow::changeLanguage(const QString &locale) {// 移除當前翻譯器qApp->removeTranslator(appTranslator);// 加載新的翻譯器if (appTranslator->load(":/translations/app_" + locale)) {qApp->installTranslator(appTranslator);// 刷新UI以應用新翻譯retranslateUi();}
}void MainWindow::retranslateUi() {// 重新設置所有UI元素的文本setWindowTitle(tr("主窗口"));fileMenu->setTitle(tr("文件"));editMenu->setTitle(tr("編輯"));// ...
}

2. 處理復數形式

不同語言對復數的規則不同（如英語有單復數，中文無），使用tr()的復數形式：

// 英語示例
QString text = tr("%n 個文件已刪除", "", fileCount);// .ts文件中會生成兩個翻譯項：單數和復數形式

3. 翻譯UI文件（.ui）

Qt Designer中創建的UI文件會自動被lupdate處理，但需確保：

在Qt Designer中使用tr()標記文本；
或在.pro文件中添加FORMS部分：
```
FORMS += mainwindow.ui \dialog.ui
```

4. 翻譯動態生成的文本

對于運行時動態生成的文本（如日志、錯誤信息），確保使用tr()：

void showErrorMessage(const QString &errorCode) {QString message = tr("錯誤: %1 - 無法加載文件").arg(errorCode);QMessageBox::critical(this, tr("錯誤"), message);
}

5. 處理上下文（Context）

使用QT_TRANSLATE_NOOP為文本指定上下文，避免翻譯歧義：

// 在不同上下文中使用相同的文本
QString title1 = QT_TRANSLATE_NOOP("MainWindow", "設置");
QString title2 = QT_TRANSLATE_NOOP("PreferencesDialog", "設置");// 在翻譯時會區分這兩個文本

四、本地化（l10n）實現

1. 數字、日期和時間格式化

使用QLocale進行本地化格式處理：

// 獲取當前區域設置
QLocale locale = QLocale::system();// 格式化日期
QDate date = QDate::currentDate();
QString formattedDate = locale.toString(date, QLocale::LongFormat);// 格式化貨幣
double amount = 1234.56;
QString formattedCurrency = locale.toCurrencyString(amount);// 顯示
dateLabel->setText(formattedDate);
priceLabel->setText(formattedCurrency);

2. 調整布局方向

對于從右到左（RTL）的語言（如阿拉伯語、希伯來語），Qt支持自動調整布局：

// 根據當前語言設置布局方向
if (locale.textDirection() == Qt::RightToLeft) {mainLayout->setDirection(QBoxLayout::RightToLeft);
} else {mainLayout->setDirection(QBoxLayout::LeftToRight);
}

3. 字體和排版支持

確保應用程序支持所有目標語言的字體：

// 設置支持多語言的字體
QFont font("Arial Unicode MS");
qApp->setFont(font);

五、項目管理與工具鏈

1. 自動化構建流程

將國際化步驟集成到項目構建流程中：

# 在.pro文件中添加自定義構建步驟
# 自動更新翻譯文件
lupdate.target = lupdate
lupdate.depends = FORMS SOURCES
lupdate.commands = lupdate $$PWD -ts $$TRANSLATIONS
QMAKE_EXTRA_TARGETS += lupdate# 自動編譯翻譯文件
lrelease.target = lrelease
lrelease.depends = $$TRANSLATIONS
lrelease.commands = lrelease $$PWD
QMAKE_EXTRA_TARGETS += lrelease

2. 版本控制

將.ts文件（翻譯源文件）納入版本控制；
不要將.qm文件（編譯后的二進制文件）納入版本控制，因為它們可以隨時從.ts生成。

3. 團隊協作

使用翻譯記憶工具（如Qt Linguist）提高翻譯效率；
為翻譯人員提供清晰的上下文和術語表；
定期合并翻譯更新，避免沖突。

六、常見問題與解決方案

1. 翻譯未生效

原因：未正確加載翻譯文件，或文本未被正確標記為可翻譯。
解決方案：
- 確保.qm文件存在且路徑正確；
- 使用tr()標記所有需要翻譯的文本；
- 檢查lupdate是否正確提取了文本。

2. 動態UI元素不更新

原因：語言切換時未重新設置動態生成的UI元素文本。
解決方案：
- 在語言切換時調用自定義的retranslateUi()函數；
- 為動態創建的UI元素提供更新文本的方法。

3. 復數形式翻譯錯誤

原因：不同語言的復數規則復雜，翻譯時未正確處理。
解決方案：
- 在.ts文件中仔細設置每個復數形式的翻譯；
- 使用Qt Linguist的預覽功能測試復數翻譯。

4. 性能問題

原因：大量翻譯文件導致加載緩慢。
解決方案：
- 按需加載翻譯文件，而非一次性加載所有；
- 使用QTranslator::load()的重載版本指定具體翻譯項。

七、完整示例

以下是一個完整的多語言Qt應用程序示例，支持運行時語言切換：

// main.cpp
#include <QApplication>
#include <QTranslator>
#include <QLocale>
#include "mainwindow.h"int main(int argc, char *argv[])
{QApplication a(argc, argv);// 加載系統默認翻譯QTranslator systemTranslator;if (systemTranslator.load("qt_" + QLocale::system().name(),QLibraryInfo::location(QLibraryInfo::TranslationsPath))) {a.installTranslator(&systemTranslator);}// 加載應用程序翻譯QTranslator appTranslator;if (appTranslator.load(":/translations/app_" + QLocale::system().name())) {a.installTranslator(&appTranslator);}MainWindow w;w.show();return a.exec();
}// mainwindow.h
#ifndef MAINWINDOW_H
#define MAINWINDOW_H#include <QMainWindow>
#include <QTranslator>QT_BEGIN_NAMESPACE
namespace Ui { class MainWindow; }
QT_END_NAMESPACEclass MainWindow : public QMainWindow
{Q_OBJECTpublic:MainWindow(QWidget *parent = nullptr);~MainWindow();protected:void changeEvent(QEvent *event) override;private slots:void on_actionChinese_triggered();void on_actionEnglish_triggered();private:Ui::MainWindow *ui;QTranslator *appTranslator;void retranslateUi();void loadTranslation(const QString &locale);
};#endif // MAINWINDOW_H// mainwindow.cpp
#include "mainwindow.h"
#include "ui_mainwindow.h"MainWindow::MainWindow(QWidget *parent): QMainWindow(parent), ui(new Ui::MainWindow)
{ui->setupUi(this);appTranslator = new QTranslator(this);// 根據系統語言設置默認語言QString currentLocale = QLocale::system().name();if (currentLocale.startsWith("zh")) {ui->actionChinese->setChecked(true);} else {ui->actionEnglish->setChecked(true);}
}MainWindow::~MainWindow()
{delete ui;
}void MainWindow::changeEvent(QEvent *event)
{if (event->type() == QEvent::LanguageChange) {retranslateUi();}QMainWindow::changeEvent(event);
}void MainWindow::retranslateUi()
{ui->retranslateUi(this);setWindowTitle(tr("多語言示例"));
}void MainWindow::loadTranslation(const QString &locale)
{// 移除當前翻譯器qApp->removeTranslator(appTranslator);// 加載新的翻譯器if (appTranslator->load(":/translations/app_" + locale)) {qApp->installTranslator(appTranslator);}
}void MainWindow::on_actionChinese_triggered()
{loadTranslation("zh_CN");ui->actionChinese->setChecked(true);ui->actionEnglish->setChecked(false);
}void MainWindow::on_actionEnglish_triggered()
{loadTranslation("en_US");ui->actionEnglish->setChecked(true);ui->actionChinese->setChecked(false);
}