78 lines
2.7 KiB
Markdown
78 lines
2.7 KiB
Markdown
# GitLink CLI i18n Guide
|
|
|
|
## Goals
|
|
|
|
GitLink CLI localizes human-facing command-line text while keeping machine-readable output stable. The i18n layer is infrastructure, not a place to store every string in the project.
|
|
|
|
## Translate
|
|
|
|
- Cobra command `Short`, `Long`, and human-facing examples.
|
|
- Flag usage text.
|
|
- User-facing errors.
|
|
- Interactive prompts.
|
|
- Success messages.
|
|
- Warnings.
|
|
- Confirmation messages.
|
|
- Table column labels when the output is meant for humans.
|
|
|
|
## Do Not Translate
|
|
|
|
- JSON field names.
|
|
- Raw API response bodies.
|
|
- Debug logs and developer diagnostics.
|
|
- Machine-readable status enum values.
|
|
- HTTP methods, paths, query keys, and payload field names.
|
|
- Long-form README documentation.
|
|
- Test assertion descriptions.
|
|
|
|
## Key Names
|
|
|
|
Use stable, descriptive keys:
|
|
|
|
- `cmd.*` for command help.
|
|
- `flag.*` for flag usage.
|
|
- `error.*` for user-facing errors.
|
|
- `prompt.*` for interactive input prompts.
|
|
- `success.*` for successful user-facing operations.
|
|
- `warning.*` for warnings.
|
|
- `confirm.*` for confirmation prompts.
|
|
- `table.*` for human table headers.
|
|
|
|
Do not invent numbered keys such as `msg001`. Prefer names that describe ownership and intent, for example `error.missing_required_flag`.
|
|
|
|
## Adding Text
|
|
|
|
1. Add the key to `internal/i18n/locales/en-US.json`.
|
|
2. Add the same key to every other locale, including `zh-CN.json`.
|
|
3. Keep placeholders identical across locales, for example `{name}`.
|
|
4. Use `tr.T("key")` or `tr.Tf("key", i18n.Args{...})`.
|
|
5. Run:
|
|
|
|
```powershell
|
|
go run ./internal/i18n/cmd/check
|
|
go test ./...
|
|
```
|
|
|
|
Use `go run ./internal/i18n/cmd/check --fix` to format locale JSON.
|
|
|
|
Use `go run ./internal/i18n/cmd/check --scan-code` before opening a PR. The scanner is intentionally lightweight:
|
|
|
|
- Name command-construction translators `tr` when calling `tr.T(...)` or `tr.Tf(...)`.
|
|
- Use `ctx.Tr.T(...)` or `ctx.Tr.Tf(...)` in runtime shortcut code.
|
|
- Avoid calling translator methods through other variable names such as `translator.T(...)`; the current scan may not detect them.
|
|
- Do not add new `i18n.Default().T(...)` or `i18n.Default().Tf(...)` usages.
|
|
|
|
## Runtime Access
|
|
|
|
Command construction receives `*i18n.Translator` from `NewRootCmd`. Shortcut execution receives the same translator through `RuntimeContext.Tr`.
|
|
|
|
New command code should receive a translator explicitly. `i18n.Default()` exists only as a legacy migration fallback and should not be used for new command paths.
|
|
|
|
## Review Checklist
|
|
|
|
- Locale JSON is sorted and formatted with two spaces.
|
|
- Every locale has the same keys as `en-US`.
|
|
- Template placeholders match across locales.
|
|
- New command/runtime text uses i18n only when it is human-facing.
|
|
- JSON output, API raw responses, debug logs, and machine-readable values are unchanged.
|