feat(i18n): 完善 CLI 国际化帮助、运行时错误与校验机制 #75

muel · 2026-05-28T13:51:00+08:00

muel commented

2026-05-28 13:51:00 +08:00

本次合并请求面向 gitlink-cli 的 CLI 国际化能力建设，基于现有 Cobra command 与 shortcuts 架构，引入可维护、可校验、可测试的 i18n 基础设施。

本 PR 将语言解析接入 root command 构造流程，支持通过 --lang、GITLINK_LANG、config.lang、LC_ALL / LANG 解析显示语言；同时迁移部分 CLI help、flag usage、auth/config 用户级提示和运行时错误，并新增 locale 完整性校验、格式校验和代码 key 引用扫描。

本次改动聚焦 CLI 用户级文案国际化，不改变 JSON 输出结构、API 原始返回、debug log 或机器可解析输出。对未显式支持的 locale 统一回退到基准语言，避免错误匹配。

变更内容

1. 新增 i18n 基础设施

新增 internal/i18n localization package。
新增 Translator.T / Translator.Tf API。
支持 fallback 到基准语言，再 fallback 到 message key。
新增 locale loader、resolver、template args、validate 逻辑。
新增 en-US / zh-CN locale JSON。
保留 i18n.Default() 作为迁移期兼容入口，新代码推荐显式传入 translator。

2. 接入语言解析链路

root command 改为动态构造，支持在 help 文案生成前解析语言。
新增全局 --lang flag。
支持 GITLINK_LANG 环境变量。
支持 config.lang 配置项。
支持 LC_ALL / LANG 系统环境变量。
对显式指定但暂未支持的语言返回用户级错误。
对未显式支持的 locale 统一回退到基准语言，避免错误匹配。

3. 打通运行时 i18n 传播链

RuntimeContext 注入 *i18n.Translator。
shortcut 执行阶段可通过 ctx.Tr 使用本地化文案。
缺失必填参数错误已改为本地化输出。
shortcut 必填参数校验从 Cobra MarkFlagRequired 默认错误路径切换为运行期本地化校验。

4. 迁移部分用户级文案

root/core/shortcut help 文案本地化。
global flag usage 本地化。
auth login username/password/token prompt 本地化。
auth status 未登录提示、登录提示、本地 token 状态提示本地化。
auth logout 成功与失败提示本地化。
config init、config set、config get、config list 中部分用户级输出本地化。
version 输出模板接入 i18n。
保留配置字段名、JSON 字段名和机器可识别值不翻译。

5. 增强 locale 校验工具

go run ./internal/i18n/cmd/check 校验：
- key 完整性；
- 多 locale key 一致性；
- 空值；
- key 命名规则；
- template 参数一致性。
go run ./internal/i18n/cmd/check --fix 格式化 locale JSON。
go run ./internal/i18n/cmd/check --scan-code 扫描代码中的 i18n key 引用。
locale JSON 采用多行、2 空格缩进、key 稳定排序、文件末尾换行。

6. CI 接入

CI 已新增并保留以下验证：

go run ./internal/i18n/cmd/check
go run ./internal/i18n/cmd/check --scan-code
go test ./...

这保证 locale 完整性、代码 key 引用和 Go 测试都会在 PR 阶段自动检查。

7. 补充测试

新增和更新命令级测试，覆盖：

--lang zh-CN --help 输出中文 help；
GITLINK_LANG=zh-CN 输出中文 help；
--lang 优先级高于 config.lang；
暂未支持语言返回用户级错误；
shortcut 缺失必填参数时输出中文错误；
auth login --token 中文 prompt / token saved；
auth status 未��录中文提示；
config set 中文成功提示，并确认输出走 cmd.OutOrStdout()；
locale normalize / resolve / validate / template 行为。

8. 新增文档

新增 docs/i18n.md，说明：

i18n 设计目标；
应翻译内容；
不应翻译内容；
key 命名规则；
新增文案流程；
locale JSON 格式要求；
check 工具使用方式；
--scan-code 的变量命名约定；

本次包含

Translator / locale resolver / fallback behavior。
--lang、GITLINK_LANG、config.lang、LC_ALL / LANG 语言解析。
root/core/shortcut help 文案本地化。
部分 auth/config prompt、success message、warning、runtime error 本地化。
locale JSON 格式校验。
i18n key 引用扫描并接入 CI。
命令级测试覆盖。
i18n 贡献和 review 文档。

本次不包含

JSON 字段名本地化。
API 原始返回内容本地化。
debug / developer log 本地化。
status enum / machine-readable value 本地化。
HTTP path / query / method 本地化。
所有 runtime 文案的全量迁移。
继续扩大 shortcut 输出文案迁移范围。

兼容性说明

本 PR 仅调整 CLI 用户级文案的国际化能力，不改变现有命令的数据协议和机器可解析输出：

不修改 JSON 字段名。
不翻译 API raw response。
不翻译 debug log。
不改变 HTTP path、query、method。
不修改 internal/output 的输出结构。
不引入新的第三方依赖。
不改变现有 API 调用语义。

测试结果

本地已执行：

go run ./internal/i18n/cmd/check
go run ./internal/i18n/cmd/check --scan-code
go test ./...

结果均通过。

手动验证

已手动验证：

go run . --lang zh-CN config set lang zh-CN
go run . --lang zh-CN --help
go run . --lang fr-FR --help

验证结果：

--lang zh-CN 可输出中文 help。
config set 中文成功提示可被输出捕获。
暂未支持语言会返回用户级错误。

本次合并请求面向 `gitlink-cli` 的 CLI 国际化能力建设，基于现有 Cobra command 与 shortcuts 架构，引入可维护、可校验、可测试的 i18n 基础设施。本 PR 将语言解析接入 root command 构造流程，支持通过 `--lang`、`GITLINK_LANG`、`config.lang`、`LC_ALL` / `LANG` 解析显示语言；同时迁移部分 CLI help、flag usage、auth/config 用户级提示和运行时错误，并新增 locale 完整性校验、格式校验和代码 key 引用扫描。本次改动聚焦 CLI 用户级文案国际化，不改变 JSON 输出结构、API 原始返回、debug log 或机器可解析输出。对未显式支持的 locale 统一回退到基准语言，避免错误匹配。 ## 相关 Issue 暂无关联 Issue。 ## 变更内容 ### 1. 新增 i18n 基础设施 * 新增 `internal/i18n` localization package。 * 新增 `Translator.T` / `Translator.Tf` API。 * 支持 fallback 到基准语言，再 fallback 到 message key。 * 新增 locale loader、resolver、template args、validate 逻辑。 * 新增 `en-US` / `zh-CN` locale JSON。 * 保留 `i18n.Default()` 作为迁移期兼容入口，新代码推荐显式传入 translator。 ### 2. 接入语言解析链路 * root command 改为动态构造，支持在 help 文案生成前解析语言。 * 新增全局 `--lang` flag。 * 支持 `GITLINK_LANG` 环境变量。 * 支持 `config.lang` 配置项。 * 支持 `LC_ALL` / `LANG` 系统环境变量。 * 对显式指定但暂未支持的语言返回用户级错误。 * 对未显式支持的 locale 统一回退到基准语言，避免错误匹配。 ### 3. 打通运行时 i18n 传播链 * `RuntimeContext` 注入 `*i18n.Translator`。 * shortcut 执行阶段可通过 `ctx.Tr` 使用本地化文案。 * 缺失必填参数错误已改为本地化输出。 * shortcut 必填参数校验从 Cobra `MarkFlagRequired` 默认错误路径切换为运行期本地化校验。 ### 4. 迁移部分用户级文案 * root/core/shortcut help 文案本地化。 * global flag usage 本地化。 * `auth login` username/password/token prompt 本地化。 * `auth status` 未登录提示、登录提示、本地 token 状态提示本地化。 * `auth logout` 成功与失败提示本地化。 * `config init`、`config set`、`config get`、`config list` 中部分用户级输出本地化。 * `version` 输出模板接入 i18n。 * 保留配置字段名、JSON 字段名和机器可识别值不翻译。 ### 5. 增强 locale 校验工具 * `go run ./internal/i18n/cmd/check` 校验： * key 完整性； * 多 locale key 一致性； * 空值； * key 命名规则； * template 参数一致性。 * `go run ./internal/i18n/cmd/check --fix` 格式化 locale JSON。 * `go run ./internal/i18n/cmd/check --scan-code` 扫描代码中的 i18n key 引用。 * locale JSON 采用多行、2 空格缩进、key 稳定排序、文件末尾换行。 ### 6. CI 接入 CI 已新增并保留以下验证： ```bash go run ./internal/i18n/cmd/check go run ./internal/i18n/cmd/check --scan-code go test ./... ``` 这保证 locale 完整性、代码 key 引用和 Go 测试都会在 PR 阶段自动检查。 ### 7. 补充测试新增和更新命令级测试，覆盖： * `--lang zh-CN --help` 输出中文 help； * `GITLINK_LANG=zh-CN` 输出中文 help； * `--lang` 优先级高于 `config.lang`； * 暂未支持语言返回用户级错误； * shortcut 缺失必填参数时输出中文错误； * `auth login --token` 中文 prompt / token saved； * `auth status` 未��录中文提示； * `config set` 中文成功提示，并确认输出走 `cmd.OutOrStdout()`； * locale normalize / resolve / validate / template 行为。 ### 8. 新增文档新增 `docs/i18n.md`，说明： * i18n 设计目标； * 应翻译内容； * 不应翻译内容； * key 命名规则； * 新增文案流程； * locale JSON 格式要求； * check 工具使用方式； * `--scan-code` 的变量命名约定； ## 本次包含 * Translator / locale resolver / fallback behavior。 * `--lang`、`GITLINK_LANG`、`config.lang`、`LC_ALL` / `LANG` 语言解析。 * root/core/shortcut help 文案本地化。 * 部分 auth/config prompt、success message、warning、runtime error 本地化。 * locale JSON 格式校验。 * i18n key 引用扫描并接入 CI。 * 命令级测试覆盖。 * i18n 贡献和 review 文档。 ## 本次不包含 * JSON 字段名本地化。 * API 原始返回内容本地化。 * debug / developer log 本地化。 * status enum / machine-readable value 本地化。 * HTTP path / query / method 本地化。 * 所有 runtime 文案的全量迁移。 * 继续扩大 shortcut 输出文案迁移范围。 ## 兼容性说明本 PR 仅调整 CLI 用户级文案的国际化能力，不改变现有命令的数据协议和机器可解析输出： * 不修改 JSON 字段名。 * 不翻译 API raw response。 * 不翻译 debug log。 * 不改变 HTTP path、query、method。 * 不修改 `internal/output` 的输出结构。 * 不引入新的第三方依赖。 * 不改变现有 API 调用语义。 ## 测试结果本地已执行： ```bash go run ./internal/i18n/cmd/check go run ./internal/i18n/cmd/check --scan-code go test ./... ``` 结果均通过。 ## 手动验证已手动验证： ```bash go run . --lang zh-CN config set lang zh-CN go run . --lang zh-CN --help go run . --lang fr-FR --help ``` 验证结果： * `--lang zh-CN` 可输出中文 help。 * `config set` 中文成功提示可被输出捕获。 * 暂未支持语言会返回用户级错误。

muel added 7 commits 2026-05-28 13:51:01 +08:00

6b2d29e5f7 feat(issue): add batch maintenance shortcuts

8ad6cd65c2 chore: remove test residue file

29401c83e5 feat(i18n): add localization infrastructure

9f0c63d2fb feat(i18n): complete cli localization foundation

ceede4ea59 test(i18n): close auth config validation gaps

351b874045 docs(i18n): clarify locale fallback wording

85011dc659 docs(i18n): remove process-specific review wording

wbtiger closed this pull request

2026-06-02 22:59:08 +08:00