97 lines
5.3 KiB
Markdown
97 lines
5.3 KiB
Markdown
|
# 本地化维护
|
|||
|
|
|
|||
|
|
## 政策
|
|||
|
|
|
|||
|
|
英文是生产代码的源语言。用户可见的中文文本只能出现在本地化资源中。生产代码中的 C、C++、头文件和 CMake 文件不得在消息、注释、目标标签或诊断信息中包含汉字。
|
|||
|
|
|
|||
|
|
协议字段、JSON 键、命令行开关、日志标识符、错误代码和文件格式标记是稳定的接口，不应进行翻译。
|
|||
|
|
|
|||
|
|
## Qt 应用程序
|
|||
|
|
|
|||
|
|
`Launcher`、`Updater` 以及 `MainApp` 集成示例使用 Qt 翻译。
|
|||
|
|
|
|||
|
|
* 在 `QObject` 子类中使用 `tr()`，当该类提供预期的翻译上下文时。
|
|||
|
|
* 在自由函数、静态辅助函数和入口点代码中使用 `QCoreApplication::translate("StableContext", "English source")`。
|
|||
|
|
* 保持上下文名称稳定。重命名上下文会使现有的翻译条目失效。
|
|||
|
|
* 使用英文源文本作为回退语言。
|
|||
|
|
* 保持简体中文翻译目录作为已提交的 `.ts` 源文件。
|
|||
|
|
* 通过 CMake 将 `.ts` 编译为 `.qm`，并将编译后的目录嵌入到 qrc 中。
|
|||
|
|
* 安装不可松动、用户可替换的翻译文件，当构建合同需要嵌入式 UI 资源时。
|
|||
|
|
* 仅在 `Common/TranslationHelper` 中保留 qrc 目录路径。应用程序入口点不得构造其他资源路径或加载第二个翻译器。
|
|||
|
|
* 在构建 UI 对象或格式化启动错误之前初始化 `TranslationHelper`。它仅在匹配的语言环境时安装嵌入式目录；其他语言环境使用英文源文本。
|
|||
|
|
* `TranslationHelper` 还会从部署的运行时 `translations/` 目录加载 Qt 的匹配基础目录，以便标准对话框按钮使用相同语言环境。这是独立的 Qt 运行时目录，不是替代应用程序目录路径。
|
|||
|
|
|
|||
|
|
不要仅仅为了满足扫描而将字符串放在翻译调用中。每个用户可见的消息都需要在目录中有一个条目，并且需要经过审核的翻译。
|
|||
|
|
|
|||
|
|
## 引导启动
|
|||
|
|
|
|||
|
|
`Bootstrap` 仍然独立于 Qt。在 Windows 上，可本地化的 UI 文本应放在 Win32 `STRINGTABLE` 资源中，并通过资源标识符加载。英语是默认的资源语言。
|
|||
|
|
|
|||
|
|
其他支持的平台必须使用等效的平台资源机制或经过审核的资源表。不要重新引入源语言条件语句或硬编码的本地化字面量。
|
|||
|
|
|
|||
|
|
机器可读的诊断信息可以保持为稳定的英文文本。任何在对话框中显示的文本都是用户可见的，必须使用资源表。
|
|||
|
|
|
|||
|
|
## 添加或修改文本
|
|||
|
|
|
|||
|
|
1. 编写简洁的英文源字符串。
|
|||
|
|
2. 选择一个现有的稳定上下文或添加一个名称明确的上下文。
|
|||
|
|
3. 在每次翻译中保留占位符，如 `%1`、`%2`、换行符和标记。
|
|||
|
|
4. 通过 CMake 管理的提取步骤更新翻译目录。
|
|||
|
|
5. 翻译并审阅已更改的条目。
|
|||
|
|
6. 构建嵌入式翻译资源。
|
|||
|
|
7. 启用英文备用和简体中文界面路径。
|
|||
|
|
8. 运行无汉字的源语检查。
|
|||
|
|
|
|||
|
|
避免通过连接翻译片段来构建句子。词序和复数规则因语言而异。翻译完整的信息，并通过占位符传递可变内容。
|
|||
|
|
|
|||
|
|
## 错误来源
|
|||
|
|
|
|||
|
|
错误跨越多个边界，需要不同的处理方式：
|
|||
|
|
|
|||
|
|
| 源文本 | 处理方式 |
|
|||
|
|
| --- | --- |
|
|||
|
|
| 本地用户界面决策 | 翻译完整的用户可见消息。 |
|
|||
|
|
| 本地技术诊断 | 保持稳定的英文细节，并将其封装在翻译后的用户可见摘要中。 |
|
|||
|
|
| 服务器错误代码 | 将稳定的代码映射到本地翻译后的消息；不要将协议 JSON 作为主要用户界面显示。 |
|
|||
|
|
| 操作系统错误 | 保留原生细节以供诊断，并提供一个翻译后的行动导向摘要。 |
|
|||
|
|
| 仅记录事件 | 除非也展示给用户，否则保持英文稳定。 |
|
|||
|
|
|
|||
|
|
不要将本地化文本作为错误代码或事务状态发送回服务器。
|
|||
|
|
|
|||
|
|
在迁移过程中，旧的服务器响应可能仍需要匹配翻译后的短语。请重用 `TranslationHelper` 已拥有的目录；不要为分类加载第二个目录。当该 API 可用时，用稳定的服务器错误代码替换文本匹配。
|
|||
|
|
|
|||
|
|
## 目录和资源审核
|
|||
|
|
|
|||
|
|
在合并 i18n 变更之前，请确认：
|
|||
|
|
|
|||
|
|
* 每个修改过的用户可见源字符串都出现在目录中；
|
|||
|
|
* 主启动/更新流程中没有未完成的条目；
|
|||
|
|
* 占位符在源字符串和翻译之间完全匹配；
|
|||
|
|
* 加速器标记和富文本标记保持有效；
|
|||
|
|
* the `.qm` 输出被嵌入到每个使用它的应用程序中；
|
|||
|
|
* 启动、提升、更新、回滚和致命错误对话框都已涵盖；
|
|||
|
|
* 不可用的语言环境会回退到英文，且不显示空白文本；
|
|||
|
|
* 生成的 `.qm` 路径不依赖于开发者的开发工作站。
|
|||
|
|
|
|||
|
|
## 源代码扫描范围
|
|||
|
|
|
|||
|
|
自动的源代码检查应包括生产代码：
|
|||
|
|
|
|||
|
|
* `*.c`, `*.cc`, `*.cpp`，以及 `*.h`；
|
|||
|
|
* `CMakeLists.txt` 和 `*.cmake`；和
|
|||
|
|
* 平台源资源，除已批准的本地化表之外。
|
|||
|
|
|
|||
|
|
它应排除翻译目录、已批准的 `STRINGTABLE` 资源、文档、第三方代码、生成的文件和构建输出。排除项必须明确，以便新添加的生产目录默认被检查。
|
|||
|
|
|
|||
|
|
## 运行时验证
|
|||
|
|
|
|||
|
|
自动目录检查是必要的但不够的。发布验收必须至少检查以下内容：
|
|||
|
|
|
|||
|
|
* 首次注册和凭证错误；
|
|||
|
|
* 离线策略和强制更新信息；
|
|||
|
|
* 更新下载、验证和回滚失败；
|
|||
|
|
* 提升失败或取消；
|
|||
|
|
* 直接启动拒绝；以及
|
|||
|
|
* 引导程序替换失败。
|
|||
|
|
|
|||
|
|
请确认文本与实际对话框相符，并且切换操作系统区域设置不会改变协议行为或配置选择。
|