gitlink-cli/docs/i18n-project-summary.md

GitLink CLI i18n Infrastructure Summary

Project Scope

This work introduces a maintainable localization infrastructure for GitLink CLI. It turns user-facing command help and flag descriptions into validated locale resources while keeping machine-readable outputs stable.

Completed Capabilities

• Added internal/i18n as a dedicated localization package.
• Embedded locale JSON files with go:embed.
• Added Translator with T and Tf APIs.
• Added fallback behavior from selected locale to en-US, then to the message key.
• Added locale resolution from --lang, GITLINK_LANG, config.lang, LC_ALL, and LANG.
• Added locale normalization and matching for common inputs such as zh_CN, zh-Hans-CN, zh, and en.
• Added simple {name} template rendering for parameterized messages.
• Added go run ./internal/i18n/cmd/check to validate key completeness, empty messages, key naming, and template argument consistency.
• Added GitHub Actions test workflow for i18n validation and Go tests.

CLI Integration

• Reworked root command construction from package-level static initialization to NewRootCmd(opts, tr).
• Added global --lang flag.
• Added lang support to the config model.
• Localized root command help, global flags, version help/output, and shortcut group descriptions.
• Localized command and flag help for:
  • api
  • auth
  • config
  • repo
  • issue
  • pr
  • branch
  • release
  • org
  • user
  • search
  • ci
  • webhook

Deliberate Non-Goals

The migration intentionally does not localize:

• JSON field names
• API response bodies
• raw API errors returned by the server
• debug diagnostics
• internal developer-only error context

This keeps scripted usage stable while improving human-facing CLI experience.

Validation

The implementation has been validated with:

go run ./internal/i18n/cmd/check
go test ./...
git diff --check

The local Go toolchain used for validation is:

E:\tools\go-sdk\go1.26.1\go\bin\go.exe

Follow-Up Work

• Migrate selected runtime success/error messages where they are clearly user-facing.
• Consider a stricter scanner for new hardcoded help text.
• Add contributor documentation for adding a new locale.