使用 PyQt 实现国际化功能 —— 完整教程

许久没有更新了。在这篇博客文章中，将介绍如何使用 PyQt 内置的国际化机制实现应用程序的多语言支持。整个过程主要分为以下几个部分：

  1. 项目环境及国际化简介
  2. 配置项目文件（.pro）
  3. 在代码中使用 tr() 函数
  4. 使用外部工具 lupdate 和 lrelease 提取和生成翻译文件
  5. 使用 Qt Linguist 进行翻译

1. 项目环境及国际化简介

首先需要确保你已经安装了 PyQt 和 Qt Linguist 工具包。PyQt 提供了内置的国际化支持功能，主要通过 tr() 函数来标记需要翻译的文本。

环境要求：

  • Python 3.x
  • PyQt5 或 PySide6
  • Qt 开发工具（其中包含 Qt Linguist、lupdate、lrelease 等工具）

2. 配置项目文件 (.pro)

在 Qt 项目中，使用 .pro 文件可以定义翻译相关的配置。在这里，你需要在 .pro 文件中添加 TRANSLATIONS 变量来声明翻译文件（通常为 .ts 文件）。当然命名方式可以为你的项目名称加上.pro的后缀即可。

示例 .pro 文件内容：

1
2
3
4
5
SOURCES += NetEasePlayer.py \
           view/SettingInterface.py \

TRANSLATIONS += resource/i18n/NetEasePlayer.zh_CN.ts \
        resource/i18n/NetEasePlayer.zh_HK.ts

3. 在代码中使用 tr() 函数

在你的 PyQt 应用中，所有需要翻译的字符串都应该通过

self.tr()

函数来包裹。对于 Python 项目，通常在类中调用 self.tr("需要翻译的内容")。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
from PyQt5.QtWidgets import QLabel

class MainWindow(QtWidgets.QMainWindow):
    def __init__(self):
        super(MainWindow, self).__init__()
        self.setWindowTitle(self.tr("我的国际化程序"))
        self.label = QLabel(self.tr("欢迎使用国际化功能"))
        self.setCentralWidget(label)

if __name__ == '__main__':
    import sys
    app = QtWidgets.QApplication(sys.argv)
    window = MainWindow()
    window.show()
    sys.exit(app.exec_())

4. 使用外部工具 lupdate 和 lrelease

Qt 提供两个外部工具用于国际化流程：

  • lupdate

    ：扫描项目代码和 .pro 文件，提取 tr() 函数标记的所有待翻译文本，并生成或更新 .ts 文件。

  • lrelease

    ：将 .ts 文件编译成二进制的 .qm 文件，供运行时加载使用。

当翻译内容已经被self.tr()包裹后，可以调用lupdate程序先根据.pro文件设置的项目代码路径进行扫描提取需要翻译的文本内容，接着会在TRANSLATIONS中设置的路径生成对应需要的语言版本，上述实例中给出了翻译为简体中文和繁体中文的路径。lrelease的使用后面继续讲。接下来讲解如何在Pycharm或者其他IDE中配置外部工具lupdate,方便我们的使用。

4.1. 配置外部工具

首先需要找到安装的PyQt中的可执行文件pylupdate5.exe，此文件一般位于你的conda目录的虚拟环境中，可以配合Everything搜索一下。配置的方式按照我给的配图中设置即可。使用方法即是对.pro文件进行调用即可。

pERQvQS.md.png

同理可以找到在该目录中的lrelease.exe,配置方法截图给上。但是这个外部工具的调用需要等我们对翻译文件使用Qt Linguist 进行翻译之后再调用的。因此暂时不着急介绍使用的步骤位置。

pERlpZj.md.png

配置好这些之后，找到linguist.exe，这个文件是QT的翻译程序，如果找不到可以先到网上下载。

5. 使用 Qt Linguist 进行翻译

Qt Linguist

是 Qt 提供的图形化翻译工具，可以方便地对 `.ts` 文件中的内容进行翻译。启动 Qt Linguist 后，打开生成的 `.ts` 文件，依次翻译其中的字符串，然后保存。 > **使用 Qt Linguist 的步骤说明：** > > 1. 打开 Qt Linguist 应用程序。 > 2. 通过“文件”菜单打开刚才生成的 `.ts` 文件（例如：`translations/myapp_zh_CN.ts`）。 > 3. 在主界面中选择待翻译的条目，输入翻译内容。这里是需要自己配置翻译的内容的，因为不同的英文名称在不同领域的翻译不同，因此需要自己配置翻译。只需要对识别到的翻译内容一一翻译后选择勾选已经翻译即可。 > 4. 保存翻译后，关闭 Qt Linguist。 > > **示例截图：** > > pERllJx.md.png 完成翻译后，记得使用 lrelease 工具将更新后的 `.ts` 文件转换为 `.qm` 文件，以便在运行时加载使用。这就需要用到刚配置好的lrelease 外部工具进行更新。更新后的目录如下。 pERlQF1.png 这一切配置好之后就可以在代码层面实现翻译功能了。 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
if __name__ == '__main__':
    QApplication.setHighDpiScaleFactorRoundingPolicy(
        Qt.HighDpiScaleFactorRoundingPolicy.PassThrough)
    QApplication.setAttribute(Qt.AA_EnableHighDpiScaling)
    QApplication.setAttribute(Qt.AA_UseHighDpiPixmaps)

    app = QApplication(sys.argv)
    locale = cfg.get(cfg.language).value
    translator = FluentTranslator(locale)
    NetEaseTranslator = QTranslator()
    NetEaseTranslator.load(locale, "NetEasePlayer", ".", "./resource/i18n")

    app.installTranslator(translator)
    app.installTranslator(NetEaseTranslator)
    demo = Window()
    demo.show()
    sys.exit(app.exec_())

这段代码展示了如何在 PyQt 应用中实现国际化支持，尤其是结合了 QFluentWidgets 的翻译组件。通过读取用户配置中的语言设置，将当前的语言环境赋值给 locale 变量。这个步骤非常关键，因为根据不同的语言环境，后续加载相应语言的翻译文件，保证应用的界面文字能够按照用户的偏好显示。

接着实例化两个翻译器对象：一个是由 QFluentWidgets 提供的 FluentTranslator，另一个是 Qt 自带的 QTranslator。使用QFluentWidgets 的翻译器来处理其内置组件的翻译，而应用自身的翻译则通过 QTranslator 对象来加载。，通过调用其 load 方法，将指定目录下根据当前语言环境命名的翻译文件加载进来。这样做确保了无论是第三方组件还是应用自定义部分，所有文本均能够被正确翻译。通过调用 app.installTranslator 方法，先后将 QFluentWidgets 的翻译器和应用自身的翻译器添加到应用中。安装翻译器后，所有通过 tr() 标记的文本在显示时都会查找相应的翻译文件，根据当前语言环境显示出不同的语言。这样设计的原因在于使得国际化工作透明而高效，不需要在代码的其他部分反复调整，仅仅通过翻译文件的切换即可改变程序的显示语言。

这里不再展示如何将用户的偏好设置加入到界面中，有多种设计思路，这里就交给读者自由发挥了。