feat(hardening): 内嵌产品配置 + 系统级状态 + 全量 i18n + 依赖治理 + 资料清理
update-client-hardening 四工作流合入(构建/静态检查已过): - 配置:不可变产品策略经 UpdateClientResources.cmake 归一化校验后 内嵌 qrc(URL/相对路径/主程序必须落 install_root/版本/UUID 格式, CMake override 写入前复验);可变机器状态迁系统级原生存储; 运行目录不再落可编辑 app_config.json。 - i18n:生产源全英文(no-Han 检查 41/41),中文进 translations/ zh_CN 目录;翻译加载收敛 Common/TranslationHelper 唯一入口; Bootstrap 补资源文件。 - 依赖:Qt/OpenSSL/架构/Perl 机器路径改 imported targets + UpdateClientDependencies.cmake,3rdparty 由父工程契约供给。 - 清理:旧 README/SDK README/3 个重复 PowerShell 打包脚本/PDF 提取 文本删除,canonical README + 5 份结构化英文文档替代;Launcher requireAdministrator manifest;统一 MSVC /utf-8 删运行时编码设置。
This commit is contained in:
@@ -0,0 +1,97 @@
|
||||
# 本地化维护
|
||||
|
||||
## 政策
|
||||
|
||||
英文是生产代码的源语言。用户可见的中文文本只能出现在本地化资源中。生产代码中的 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` 资源、文档、第三方代码、生成的文件和构建输出。排除项必须明确,以便新添加的生产目录默认被检查。
|
||||
|
||||
## 运行时验证
|
||||
|
||||
自动目录检查是必要的但不够的。发布验收必须至少检查以下内容:
|
||||
|
||||
* 首次注册和凭证错误;
|
||||
* 离线策略和强制更新信息;
|
||||
* 更新下载、验证和回滚失败;
|
||||
* 提升失败或取消;
|
||||
* 直接启动拒绝;以及
|
||||
* 引导程序替换失败。
|
||||
|
||||
请确认文本与实际对话框相符,并且切换操作系统区域设置不会改变协议行为或配置选择。
|
||||
Reference in New Issue
Block a user