Gitlink
/
gitlink-cli
0
0
Fork 49
Code Issues Pull Requests 11 Packages Projects Releases 10 Wiki Activity

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

Merged
wbtiger merged 2 commits from muel/gitlink-cli:feat/i18n-cli-foundation-clean into master 2026-06-02 22:02:28 +08:00
Conversation 0 Commits 2 Files Changed 41 +2310 -327
muel commented 2026-06-01 18:12:19 +08:00
Contributor
Copy Link

本次合并请求面向 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。
  • 支持 locale → fallback language → 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 中部分用户级输出本地化。
  • api 相关 help / flag usage 接入 i18n。
  • 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 的变量命名约定；
  • PR review 注意事项。

本次包含

  • Translator / locale resolver / fallback behavior。
  • --lang、GITLINK_LANG、config.lang、LC_ALL / LANG 语言解析。
  • root/core/shortcut help 文案本地化。
  • 部分 auth/config/api 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 build .
go vet ./...

go test ./... 在当前 Windows 本地环境下仍有 auth 相关测试失败。对比当前上游 master 后确认，该失败同样存在于上游基线，主要涉及 Windows 下 auth 存储路径 / 终端输入兼容行为，不是本 PR 新增 i18n 代码导致。

最终以平台 CI 环境结果为准。

手动验证

已手动验证：

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

验证结果：

  • --lang zh-CN 可输出中文 help。
  • --lang en-US 可输出英文 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。 * 支持 locale → fallback language → 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` 中部分用户级输出本地化。 * `api` 相关 help / flag usage 接入 i18n。 * `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` 的变量命名约定； * PR review 注意事项。 ## 本次包含 * Translator / locale resolver / fallback behavior。 * `--lang`、`GITLINK_LANG`、`config.lang`、`LC_ALL` / `LANG` 语言解析。 * root/core/shortcut help 文案本地化。 * 部分 auth/config/api 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 build . go vet ./... ``` `go test ./...` 在当前 Windows 本地环境下仍有 auth 相关测试失败。对比当前上游 `master` 后确认，该失败同样存在于上游基线，主要涉及 Windows 下 auth 存储路径 / 终端输入兼容行为，不是本 PR 新增 i18n 代码导致。 最终以平台 CI 环境结果为准。 ## 手动验证 已手动验证： ```bash go run . --lang zh-CN --help go run . --lang en-US --help go run . --lang fr-FR --help go run . --lang zh-CN config set lang zh-CN ``` 验证结果： * `--lang zh-CN` 可输出中文 help。 * `--lang en-US` 可输出英文 help。 * 暂未支持语言会返回用户级错误。 * `config set` 中文成功提示可被输出捕获。
muel added 1 commit 2026-06-01 18:12:20 +08:00
muel added 1 commit 2026-06-02 15:16:31 +08:00
wbtiger merged commit dec8c10a1b into master 2026-06-02 22:02:28 +08:00
Sign in to join this conversation.
Reviewers
No reviewers
Labels
Clear labels
No items
No Label
Milestone
Clear milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
No Assignees
1 Participants
Notifications
Due Date
The due date is invalid or out of range. Please use the format 'yyyy-mm-dd'.

No due date set.

Dependencies

No dependencies set.

Reference: Gitlink/gitlink-cli#95
No description provided.
Delete Branch "muel/gitlink-cli:feat/i18n-cli-foundation-clean"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?