73 lines
2.2 KiB
Markdown
73 lines
2.2 KiB
Markdown
# 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:
|
|
|
|
```powershell
|
|
go run ./internal/i18n/cmd/check
|
|
go test ./...
|
|
git diff --check
|
|
```
|
|
|
|
The local Go toolchain used for validation is:
|
|
|
|
```text
|
|
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.
|