docs: add multilanguage support design spec

Author: Cerdore

docs/superpowers/specs/2026-04-04-multilanguage-support-design.md

@@ -0,0 +1,257 @@
+# Multilanguage Support Design
+
+Date: 2026-04-04
+Repo: `gdb-cli`
+Issue: `#1 [Feature] add multilanguage support`
+
+## Goal
+
+Add first-version multilanguage support for:
+
+- Runtime CLI help and user-facing messages
+- JSON response messages, hints, warnings, and suggestions generated by `gdb-cli`
+- Repository README files
+
+The first supported languages are:
+
+- `en`
+- `zh-CN`
+- `ru`
+
+## Non-Goals
+
+This first version does not include:
+
+- Full translation of raw GDB error text returned by GDB itself
+- Automatic translation workflows for README files
+- External localization tooling such as `gettext`, `.po`, or `.mo`
+- Translation of internal test comments or developer-only notes
+
+## Design Summary
+
+The implementation uses a lightweight runtime i18n layer plus static multi-file README documents.
+
+- Runtime strings are translated through a centralized Python i18n module.
+- English is the source and fallback language.
+- Locale resolution is deterministic and tolerant of alias formats such as `zh_CN` or `ru_RU`.
+- README localization is handled as separate files in the repository root, following the pattern used in `cmux`.
+
+This keeps runtime internationalization and documentation localization decoupled. That reduces implementation cost, avoids introducing a build-time translation pipeline, and matches the current size of the project.
+
+## Approach Comparison
+
+### Recommended: lightweight i18n module
+
+Use a small runtime translation layer that provides locale detection, key lookup, parameter interpolation, and English fallback.
+
+Why this is the recommended approach:
+
+- It fits the current CLI project size.
+- It keeps translation behavior centralized.
+- It avoids the operational overhead of `gettext`.
+- It is compatible with future expansion if more languages or more commands are added.
+
+### Alternative 1: `language.py` constants only
+
+This would be fast to start but would likely degrade into large unstructured dictionaries spread across modules. It also tends to push locale detection, interpolation, and fallback behavior out to call sites.
+
+### Alternative 2: `gettext`
+
+This would be more standard for large mature applications, but it is heavier than needed for the current repository. It also does not solve README localization by itself, so it adds complexity without enough payoff in this first iteration.
+
+## Architecture
+
+### Runtime i18n module
+
+Add a new module at `src/gdb_cli/i18n.py`.
+
+Responsibilities:
+
+- Resolve the active locale
+- Normalize locale identifiers
+- Expose a translation function such as `t(key, **params)`
+- Fall back to English when a translation is missing
+- Keep translation behavior independent from command logic
+
+Expected locale precedence:
+
+1. Explicit process override through environment variable `GDB_CLI_LANG`
+2. System locale detection
+3. Default to `en`
+
+Future CLI flags such as `--lang` are intentionally deferred. The first version should not expand the command surface unless needed.
+
+### Translation catalog layout
+
+Store message catalogs in a dedicated module, for example:
+
+- `src/gdb_cli/messages.py`
+
+or a locale package, for example:
+
+- `src/gdb_cli/locales/en.py`
+- `src/gdb_cli/locales/zh_cn.py`
+- `src/gdb_cli/locales/ru.py`
+
+The preferred implementation is a locale package because it scales better once message count grows.
+
+Each language file contains the same stable keys. Example key families:
+
+- `cli.group.help`
+- `cli.load.binary_help`
+- `cli.load.core_help`
+- `cli.error.session_not_found`
+- `errors.ptrace_denied.suggestion`
+- `env_check.gdb_below_minimum`
+
+Keys are stable identifiers; user-facing text lives only in catalogs.
+
+### README localization
+
+Add root-level README files:
+
+- `README.md` for English
+- `README.zh-CN.md` for Simplified Chinese
+- `README.ru.md` for Russian
+
+Each README includes a language switcher near the top. The current language is rendered as plain text; other languages are links.
+
+README files are maintained manually. They should preserve:
+
+- Equivalent installation instructions
+- Equivalent command examples
+- Equivalent feature descriptions
+
+Small phrasing differences are acceptable, but technical meaning must stay aligned.
+
+## Data Flow
+
+### Runtime translation flow
+
+1. Process starts and imports CLI modules.
+2. Runtime i18n resolves the locale using environment or system settings.
+3. CLI help text, user-facing messages, and error wrappers call `t(key, **params)`.
+4. The translator looks up the key in the active locale catalog.
+5. If the key is missing, it looks up the same key in the English catalog.
+6. If interpolation parameters are provided, they are formatted into the translated string.
+7. The resulting text is returned to the caller and emitted through Click or JSON output.
+
+### README selection flow
+
+There is no runtime logic. Users select the README by following links at the top of the root document.
+
+## Locale Normalization Rules
+
+The i18n layer must normalize common locale spellings into the supported set.
+
+Examples:
+
+- `en`, `en_US`, `en-US` -> `en`
+- `zh`, `zh_CN`, `zh-CN`, `zh_Hans_CN` -> `zh-CN`
+- `ru`, `ru_RU`, `ru-RU` -> `ru`
+
+If a locale cannot be mapped to a supported language, use `en`.
+
+This rule is required to keep behavior stable across shells, CI, and different operating systems.
+
+## Scope of Runtime Translation
+
+The first version should translate all user-facing strings produced directly by this project in the CLI layer and high-value supporting modules.
+
+Priority targets:
+
+- Click command group help text
+- Click option help text
+- Click command docstrings shown in help output
+- CLI-generated `message`, `error`, `details`, `hint`, `warning`, and `suggestion` fields
+- Environment check guidance and actionable suggestions
+
+Deferred targets:
+
+- Free-form GDB-originated message bodies
+- Arbitrary strings returned directly from GDB internals when there is no stable local wrapper
+
+For deferred targets, wrap the message in translated outer context where possible, but preserve the original dynamic payload.
+
+## Error Handling
+
+The i18n implementation must fail safely.
+
+- Missing translation key must not crash CLI execution.
+- Missing translation key falls back to English.
+- Missing interpolation parameter should surface as a development error in tests, not silently produce malformed user text.
+- Unsupported locale should resolve to English.
+
+This keeps internationalization from becoming a reliability risk.
+
+## Testing Strategy
+
+Add targeted tests for the i18n behavior and key CLI integration points.
+
+Required coverage:
+
+- Locale normalization for English, Chinese, and Russian aliases
+- Locale fallback to English for unsupported locales
+- Translation lookup for the three supported languages
+- English fallback when a key is missing in a non-English catalog
+- CLI help output under different locales
+- Representative error and suggestion text under different locales
+
+The goal is not exhaustive snapshot coverage for every command in the first pass. The goal is to verify the translation mechanism and enough representative commands to prevent regressions.
+
+## Migration Strategy
+
+The rollout should be incremental.
+
+1. Introduce the i18n module and translation catalogs.
+2. Convert central CLI entry points and shared error helpers.
+3. Convert `env_check.py` suggestions and warnings.
+4. Add Russian README and update language switchers in all README files.
+5. Add or update tests to lock behavior.
+
+This sequence keeps the integration safe and reviewable.
+
+## Risks And Mitigations
+
+### Risk: Click help strings are evaluated early
+
+Mitigation:
+Design the translation helper so help text can be resolved safely at import time, or define a small helper pattern that Click decorators can consume consistently.
+
+### Risk: Message catalogs drift across languages
+
+Mitigation:
+Add tests that compare key sets across `en`, `zh-CN`, and `ru`.
+
+### Risk: Partial translation creates mixed-language output
+
+Mitigation:
+Use English fallback consistently and prioritize shared wrappers first, especially CLI-level errors and suggestions.
+
+### Risk: README content diverges over time
+
+Mitigation:
+Keep the README structure aligned and treat English as the source document for future updates.
+
+## Open Decisions Resolved
+
+The following decisions are fixed for the first implementation:
+
+- Use a lightweight runtime i18n layer, not `gettext`
+- Support `en`, `zh-CN`, and `ru`
+- Localize runtime CLI text and JSON user-facing hints
+- Localize README files using multiple root-level Markdown files
+- Use English as the fallback language
+
+## Acceptance Criteria
+
+The feature is complete when all of the following are true:
+
+- The CLI resolves locale from environment or system locale
+- Unsupported locales fall back to English
+- Core CLI help and major user-facing messages appear in English, Simplified Chinese, and Russian
+- JSON suggestions and hints generated by local code are translated for the supported languages
+- Root README language switchers include English, Simplified Chinese, and Russian
+- `README.ru.md` exists and mirrors the current README structure at a practical first-version level
+- Tests cover locale normalization, fallback, and representative translated CLI outputs
+