# i18n Guide

AIOSON CLI supports localization through message dictionaries and a decoupled interaction language system.

## How it works

### CLI localization
- Dictionaries are stored in `src/i18n/messages/`.
- `src/i18n/index.js` resolves locale and fallback behavior.
- Commands use translation keys instead of hardcoded strings.
- The CLI locale is controlled by `--locale=<lang>` or `AIOS_LITE_LOCALE` env var.

### Agent interaction language (decoupled)
Agent instruction files are maintained in **canonical English** only. The interaction language is decoupled from the agent prompts:

- `conversation_language` in `.aioson/context/project.context.md` tells agents which language to use for **interaction and output** with the user.
- Agent **prompts and reasoning instructions** remain in English to ensure consistency and reduce drift across locales.
- `locale:apply` updates the agent files to reflect the chosen interaction language, but does **not** translate the core reasoning prompts.

This architecture (introduced in v1.7.3+) replaces the previous "localized agent packs" system. Localized agent packs in `.aioson/locales/<locale>/agents/` were removed in favor of a single canonical source + interaction-language metadata.

## Runtime selection
- CLI option: `--locale=en|pt-BR|es|fr`
- Env var: `AIOS_LITE_LOCALE=en|pt-BR|es|fr`
- Default: `en`

Built-in CLI locales:
- `en`
- `pt-BR`
- `es`
- `fr`

Resolution behavior:
- `pt-BR`, `pt_br`, and `pt` resolve to `pt-BR` dictionary.
- `es-MX` and other `es-*` variants resolve to `es`.
- `fr-CA` and other `fr-*` variants resolve to `fr`.
- Unknown locales fall back to `en`.

## Apply interaction language to agents

```bash
# Use language from project.context.md
aioson locale:apply

# Or force a locale
aioson locale:apply --lang=pt-BR
```

## Add a new CLI locale
1. Run `aioson i18n:add <locale>`.
2. Replace English strings in `src/i18n/messages/<locale>.js`.
3. Add tests for locale resolution and fallback behavior.