QML 国际化（i18n）实现思路
2025-8-25
| 2025-8-27
Words 4845Read Time≈ 13 min
type
status
date
slug
summary
tags
category
icon
password
QML 国际化（i18n）实现思路标记需要翻译的字符串生成翻译源文件（TS 文件）翻译借助 AI 翻译工具术语处理翻译准确性HTTP 接口处理用户界面布局适配参考文档

QML 国际化（i18n）实现思路

page icon
Qml 国际化翻译实现思路？
好的，QML 的国际化（i18n）实现思路非常清晰，主要依赖于 Qt 框架本身提供的国际化机制。其核心思想是：在 QML 中使用特定的函数标记所有需要翻译的字符串，然后利用 Qt 的工具生成翻译文件，由翻译人员填写译文，最后在程序中根据系统语言或用户选择加载对应的翻译文件。
以下是详细的实现思路和步骤：
核心思路
  1. 标记可翻译字符串：在 QML 文件中，将所有需要翻译的文本用 qsTr()、qsTranslate() 等函数包裹起来。
  1. 生成翻译源文件 (TS)：使用 lupdate 工具扫描项目源代码，提取所有被标记的字符串，生成 .ts 文件（XML 格式）。
  1. 翻译：由翻译人员使用 Qt Linguist 工具或文本编辑器打开 .ts 文件，填写对应的译文。
  1. 编译翻译文件 (QM)：使用 lrelease 工具将翻译好的 .ts 文件编译成高效的二进制 .qm 文件，供程序运行时使用。
  1. 加载翻译文件：在 C++ 的 main 函数中，使用 QTranslator 根据当前语言环境或用户设置，加载对应的 .qm 文件。
  1. 动态切换语言（可选）：通过改变配置、发出信号、重启应用或动态重置界面等方式实现运行时语言切换。
详细步骤
1. 在 QML 中标记字符串
使用 qsTr() 函数包裹任何需要翻译的字符串。
  • 基本用法：
    • 带注释的翻译：为翻译人员提供上下文。
      • 包含变量（复数形式）：使用 qsTr() 的参数化字符串。
          • 对于更复杂的复数处理（如不同语言复数规则不同），可以使用 qsTrId() 配合 .pro 文件中的 TRANSLATIONS 部分来定义复数形式，但这稍微复杂一些，qsTr() 配合 .arg() 能满足大部分需求。
      2. 配置项目文件 (.pro)
      在 Qt 项目文件 (.pro) 中，需要添加 lupdate 和 lrelease 工具所需的配置。
      3. 生成和更新 TS 文件
      使用 Qt 命令行工具或 Qt Creator 来生成 .ts 文件。
      • 命令行方式：
          • 这会在 translations/ 目录下生成（或更新）定义的 .ts 文件。
      • Qt Creator 方式：
          1. 打开菜单 Tools -> External -> Linguist -> Update Translations (lupdate)。
          1. 同样会生成或更新 .ts 文件。
      4. 翻译 - 使用 Qt Linguist
      1. 打开 Qt Linguist 工具。
      1. File -> Open，选择生成的 .ts 文件（如 myapp_zh_CN.ts）。
      1. 在界面中，你会看到所有提取出来的字符串（Source text）和上下文（Context，通常是 QML 组件名）。
      1. 在下方的翻译区域填写译文（Translation）。
      1. 翻译完一个后，点击绿色勾号标记为“已完成”。
      1. 保存文件。
      5. 编译 QM 文件
      翻译完成后，需要将 .ts 文件编译成更紧凑、运行时加载更快的 .qm 文件。
      • 命令行方式：
          • 这会在 .ts 文件同级目录下生成同名的 .qm 文件。
      • Qt Creator 方式：
          1. 打开菜单 Tools -> External -> Linguist -> Release Translations (lrelease)。
      6. 在应用程序中加载翻译器
      这是最关键的一步，在 C++ 的 main.cpp 中完成。
      重要：确保 .qm 文件被加入 Qt 的资源系统 (.qrc)，否则程序可能找不到它。
      7. 动态切换语言（高级）
      实现运行时切换语言比较复杂，因为需要刷新所有已显示的文本。常见思路是：
      1. 将语言设置保存到 QSettings 或其它配置中。
      1. 发射一个全局信号（例如通过一个 LanguageManager 单例），通知所有界面语言已变更。
      1. 在 QML 中，所有需要翻译的文本都应该绑定到一个属性上，当收到语言改变信号时，触发这个属性的重新计算（通常通过 qsTr() 的上下文 retranslate() 实现，但 QML 没有内置此功能）。
      1. 一个更简单但粗暴的方法是：退出当前界面并重新创建，或者甚至重启整个应用程序，让 main.cpp 根据新的设置重新加载翻译器。
      一个常见的折中方案是提示用户重启应用以使语言更改生效。
      总结与最佳实践
      步骤
      工具/函数
      输入
      输出
      责任人
      1. 标记
      qsTr("text")
      QML 代码
      -
      开发者
      2. 提取
      lupdate
      .pro, 源代码
      .ts 文件
      开发者
      3. 翻译
      Qt Linguist
      .ts 文件
      翻译后的 .ts 文件
      翻译者
      4. 编译
      lrelease
      .ts 文件
      .qm 文件
      开发者/构建系统
      5. 加载
      QTranslator
      .qm 文件
      翻译后的 UI
      应用程序
      • 尽早并经常进行：在开发初期就引入国际化，避免后期重构。
      • 避免拼接字符串："Hello " + username 很难翻译，应使用 qsTr("Hello %1").arg(username)。
      • 提供上下文注释：使用 //: 帮助翻译者理解文本的用法。
      • 测试所有语言：确保 UI 在不同语言下布局依然正常，某些语言的文本可能更长。
      • 将 .ts 文件纳入版本控制，但编译生成的 .qm 文件通常不需要。
      按照这个思路，你就可以系统化地实现 QML 应用的国际化了。
      依赖 QT 框架提供的国际化机制，通常遵循以下基本流程：
      • 标记需要翻译的字符串：在代码中使用 QT 提供的翻译宏（如 tr()）标识所有需要本地化的文本；
      • 生成翻译源文件（TS 文件）：使用 QT 工具（如 lupdate）提取代码中的可翻译文本，生成 TS 文件；
      • 进行翻译：在 TS 文件中填写对应语言的译文；
      • 动态切换语言：在应用程序中实现运行时语言切换功能，通过加载相应的 QM 文件实现。
      上述流程主要适用于应用程序中内置的静态文本。此外，还需综合考虑以下方面的国际化处理：
      • HTTP 接口返回的数据；
      • 本地存储的持久化数据；
      • 用户界面布局适配。

      标记需要翻译的字符串

      比如我们项目默认使用中文，需要国际化支持英文，需要先提取出需要翻译的中文文本。
      • qml 文件，使用 qsTr("{中文文本}")
      • cpp 文件，使用 QObject::tr("{中文文本}")
      对于已经迭代较久的项目，逐条手动查找修改显然是一项枯燥且低效的体力劳动。其实，VS Code 的正则替换就能一键搞定；再不济，写个 Python 脚本也能批量处理。
      这种方式可快速提取项目中大部分中文文本，像 .qml 文件中 property var name: "xxx" ，.cpp 文件中夹杂使用的中文等需单独处理。

      生成翻译源文件（TS 文件）

      QT Creator → Build → Run CMake，后即可生成对应的 app_zh_CN.ts、app_en_US.ts 文件，每次编译都会增量更新 .ts 文件（已经翻译的部分不会被重置）。
      💭注: app_zh_CN.ts 其中，zh 表示语言代码，CN 表示地区代码。
      .ts 文件本质是 xml 文件，示例如下：

      翻译

      这一步主要是在 TS 文件中填写对应语言的译文。

      借助 AI 翻译工具

      可以编写 Python 脚本，调用 DeepSeek Api 进行翻译：
      翻译后的 app_en_US.ts 文件如下：

      术语处理

      应用软件术语、人名、地名等翻译需要特殊处理，一些专有名词、软件术语可以参考 Human Interface Guidelines、Microsoft 术语 和开源应用软件里面的中英文翻译文件（例如 GitHub 上 Telegram）等。
      英文术语
      中文术语
      Human Interface Guidelines
      人机界面指南
      Camera Control
      相机控制
      Gestures
      手势
      Designing for games
      针对游戏设计
      Immersive experiences
      沉浸式体验
      Controls
      控件
      App icons
      App 图标
      Featured
      精选
      Designing for visionOS
      针对 visionOS 设计
      Accessibility
      辅助功能
      SF Symbols
      SF 符号
      Typography
      排版
      Writing
      书写
      Game controls
      游戏控件
      Topics
      主题
      Getting started
      入门
      Foundations
      基础
      Patterns
      模式
      Components
      组件
      Inputs
      输入
      Technologies
      技术
      基于 DeepSeek 实现国际化翻译 Python 脚本，添加专有词汇翻译（如 "美的" → "MD"）的处理。
      page icon
      基于 DeepSeek 实现国际化翻译并添加专有词汇翻译（如 "美的" → "MD"）的系统，可采用以下实现思路？
      1. 构建专有词汇表
      • 格式：JSON/YAML 键值对（支持正则表达式）
        • 特性：
          • 支持大小写敏感/不敏感配置
          • 支持词组匹配（如 "智能家居" → "SmartHome"）
          • 支持上下文规则（特定场景下启用不同翻译）
        2. 预处理流程
        3. 集成 DeepSeek 翻译
        4. 边界情况处理
        • 冲突解决：
          • 当多个词汇重叠时（如 "华为云" vs "华为"），采用最长匹配优先原则
          • 使用特殊标记避免误替换：{{美的}} → MD（可选）
        • 语言适配：
          • 为不同语言创建独立词汇表（glossary_en.json, glossary_es.json）
          • 自动处理复数/时态变化（如 "device" → "devices"）
        性能优化策略
        1. 缓存机制：
            • 对高频词汇建立翻译缓存（LRU Cache）
            • 缓存预处理后的中间文本
        1. 异步处理：
          1. 增量更新：
              • 词汇表热加载（无需重启服务）
              • 版本控制（A/B测试不同词汇表效果）
          测试翻译后的 app_en_US.ts 文件如下：

          翻译准确性

          常规翻译软件（包含 ai 云翻译）都是直译，与本地化实际用语差异较大（比如 Wi-Fi、wifi 、还是 WIFI，返回是 back 还是 return)，还是需要人工校验。
          使用本地化校验工具
          一些本地化在线编辑工具可以帮助进行翻译校验，把翻译文件转化为工具支持的文件格式，通过人工校验后在转回。
          fig.1 本地化校验工具
          fig.1 本地化校验工具
          使用脚本导出 excel 表格
          也可以把 .ts 文件直接导出为 excel 表格，在人工校验后，在转回 .ts 文件。
          .ts 文件导出 excel 表格的 Python 脚本：
          导出的表格如下：
          fig.2 ts 文件解析并导出为 excel 文件示例
          fig.2 ts 文件解析并导出为 excel 文件示例
          在人功校验翻译后，再通过脚本更新 .ts 文件，Python 脚本如下：

          HTTP 接口处理

          • Http 接口请求时支持多语言
              • 一般有两种处理方式：
              1. 云端接口请求时 header 添加目标的语言，响应的数据结构保持一致。
                1. 云端接口请求，需要翻译的字段添加多语言的枚举。
              • 图片资源上面不带有文字

              用户界面布局适配

              • 通用处理
                • 英文翻译尽量简短
                • 使用容器约束（绝对布局修改为相对布局）
                • 调整字号大小

                参考文档

                 
                Qt 基础
              • 开发
                • 建站之初团队的五大障碍
                Loading...
                Catalog
                0%