# 本地化维护

## 政策

英文是生产代码的源语言。用户可见的中文文本只能出现在本地化资源中。生产代码中的 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` 资源、文档、第三方代码、生成的文件和构建输出。排除项必须明确，以便新添加的生产目录默认被检查。

## 运行时验证

自动目录检查是必要的但不够的。发布验收必须至少检查以下内容：

*   首次注册和凭证错误；
*   离线策略和强制更新信息；
*   更新下载、验证和回滚失败；
*   提升失败或取消；
*   直接启动拒绝；以及
*   引导程序替换失败。

请确认文本与实际对话框相符，并且切换操作系统区域设置不会改变协议行为或配置选择。