gitlink-cli/docs/i18n.md

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:

   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.