# 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.
