> ## Documentation Index
> Fetch the complete documentation index at: https://chatcli.edilsonfreitas.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Internationalization (i18n)

> ChatCLI supports multiple languages with automatic detection and intelligent fallback.

ChatCLI was designed to be global. The user interface, including menus, hints, and status messages, is fully internationalized.

## Supported Languages

| Language | Code | Status |
| - | - | - |
| **Portuguese (Brazil)** | `pt-BR` | Complete |
| **English** | `en` | Complete (default fallback) |

***

## Automatic Detection

The language is automatically detected from system environment variables, in the following priority order:

| Priority | Variable | Example |
| - | - | - |
| 1 (highest) | `CHATCLI_LANG` | `pt-BR` |
| 2 | `LANG` | `pt_BR.UTF-8` |
| 3 | `LC_ALL` | `pt_BR.UTF-8` |

If no variable is set or the language is not supported, the interface will be displayed in **English** by default.

***

## Force a Language

To force a specific language, set `CHATCLI_LANG` in the `.env` file or in the environment:

```bash theme={"system"}
# No .env
CHATCLI_LANG=pt-BR

# Ou via export
export CHATCLI_LANG=en
```

***

## Coverage

The i18n system holds **1925 translation keys** covering all user-facing strings (parity across `en.json`, `en-US.json`, and `pt-BR.json`). Every new user-facing string introduced in code goes through `i18n.T()` wrapping — a **mandatory rule** for any command handler, `prompt.Suggest` autocomplete entry, or user-visible error message.

<Info>
  As of the April 2026 i18n sweep, every slash command (`/hooks`, `/mcp`, `/worktree`, `/cost`, `/channel`, `/websearch`, `/config` + subsections, `/skill`, `/agent`, `/memory`, `/session`, `/switch`, `/context`, `/auth`, `/plugin`) and the CLI autocomplete are 100% routed through `i18n.T`. Hardcoded PT/EN strings inside `fmt.Println` or `colorize(...)` count as a conformance bug.
</Info>

## What Is Translated

* Interactive menus and prompts
* Status and progress messages (including history-compactor pipeline phases: trim, summarize, emergency)
* Command help (`/help`)
* Error messages and warnings
* Agent mode UI (execution plan, actions)
* Coder mode feedback
* Pre-flight and payload-recovery messages (413/WAF/EOF) with specific labels per failure type
* Server and remote connection messages
* Session, context, and plugin commands
* K8s Watcher and Operator notifications

### Main namespaces

| Key prefix | Scope |
| :- | :- |
| `welcome.*`, `help.*` | Onboarding, welcome, help |
| `agent.*` | Agent mode, turns, action plan |
| `agent.microcompact.*` | Progressive compaction of old tool results (no LLM) |
| `agent.preflight.*` | Proactive history-size vs proxy-cap warnings |
| `agent.recovery.*` | Context overflow + proxy 413/WAF/EOF recovery |
| `coder.*` | Coder mode, cards, policy decisions |
| `compact.*` | `/compact` command (manual and guided) |
| `compact.status.*` | Live feedback during each compaction pipeline phase |
| `context.*` | `/context attach`, `/context show`, etc. |
| `cmd.*` | Legacy CLI command keys (`/auth`, `/connect`, `/switch`, ...) |
| `cmd.core.*` | `/session fork` and similar under the core `command_handler` |
| `cfg.*` | Hierarchical `/config` — section titles, kv labels, placeholders (`cfg.val.*`, `cfg.kv.*`, `cfg.sub.*`, `cfg.panorama.*`, `cfg.section.*`, `cfg.msg.*`) |
| `hooks.cmd.*` / `mcp.cmd.*` / `wt.cmd.*` / `cost.cmd.*` / `chan.cmd.*` | One namespace per manager slash-command (`/hooks`, `/mcp`, `/worktree`, `/cost`, `/channel`) |
| `skill.cmd.*` / `persona.cmd.*` / `mem.cmd.*` | `skill_handler`, `persona_handler`, `memory_command` handlers |
| `sw.cmd.*` / `sess.cmd.*` / `ctx.cmd.*` | Fills in `cli_llm` (`handleSwitchCommand`), `cli_session`, `context_handler` |
| `ws.cmd.*` | `/websearch` command (status, list, provider, reset) |
| `complete.*` | Autocomplete descriptions — `complete.root.*` for top-level slash commands, `complete.{connect,watch,context,session,plugin,agent,skill,switch,auth,generic}.*` for sub/flags |
| `llm.*` | Streaming, provider errors |
| `server.*` | Server mode and authentication |

### Special pattern for AI instructions

The `ai.response_language` key is a meta-instruction **written in English** across all locales (including pt-BR), which **tells the AI to respond in the user's language**. Intentional: LLMs follow English instructions with much higher fidelity, so the prompt that asks for "respond in pt-BR" is itself in English. The response content, of course, comes out in pt-BR.

This instruction is appended to the system prompt across all three modes (`chat`, `agent`, `coder`), together with a `[ACTIVE MODE: ...]` block that tells the AI which mode it's operating in. See `cli/prompts.go` and `cli/cli_llm.go`.

<Info>
  AI responses are in the language you use in the conversation — i18n controls both the **ChatCLI interface** and the **meta-prompt that instructs the AI**. The actual content the LLM generates depends on the model following the instruction (which 4.x models do very well).
</Info>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.