docs: propose Brazilian Portuguese (pt-BR) localization

Summary

I would like to propose adding an official Brazilian Portuguese (pt-BR) localization to the Kimi Code CLI documentation.

Before preparing a large pull request, I would like to align with the maintainers on the expected scope, directory structure, launch strategy, and long-term maintenance model.

I have already prepared the following materials locally:

• an initial technical impact assessment;
• a Brazilian Portuguese terminology glossary;
• a pilot translation of docs/en/guides/sessions.md;
• a maintenance and synchronization plan.

No localization files have been submitted yet. I would prefer to confirm the direction first.

Motivation

Kimi Code CLI serves both experienced developers and less technical AI users. Providing documentation in Brazilian Portuguese would make installation, configuration, permissions, sessions, MCP, plugins, and other core concepts more accessible to Portuguese-speaking users.

The goal is not only to translate the current pages, but to establish a localization process that can remain accurate as the project evolves.

Proposed locale structure

The proposed locale would follow the existing mirrored documentation structure:

docs/
├── en/
├── zh/
└── pt-br/

Suggested locale configuration:

'pt-br': {
  label: 'Português (Brasil)',
  lang: 'pt-BR',
  link: '/pt-br/',
  title: 'Documentação do Kimi Code CLI',
  description: 'Documentação do Kimi Code CLI em português brasileiro',
}

The English documentation under docs/en/ would be the canonical source for the Brazilian Portuguese translation.

Paths, filenames, heading structure, code blocks, commands, flags, configuration fields, and internal links would remain mirrored across locales.

Technical impact

The localization appears to be isolated to the VitePress documentation site and should not require changes to the CLI runtime or package behavior.

The main integration points would be:

• adding the pt-br locale to docs/.vitepress/config.ts;
• adding mirrored navigation and sidebar entries;
• creating the docs/pt-br/ documentation tree;
• updating docs/index.md with a Portuguese language option;
• updating locale detection and fallback behavior;
• validating local search, links, anchors, and generated LLM documentation output;
• optionally adding a Portuguese documentation link to the root README.md.

The root language selector currently redirects English browser locales to /en/ and all other locale values to /zh/. A three-locale implementation could use the following behavior:

pt-*           → /pt-br/
zh-*           → /zh/
all other      → /en/

Pilot translation

I prepared docs/en/guides/sessions.md as the initial pilot.

This page was selected because it exercises several important localization decisions without requiring the full documentation set:

• sessions and context terminology;
• commands such as /sessions, /compact, /fork, and /export;
• flags and file paths;
• VitePress warning and tip blocks;
• security guidance;
• internal relative links;
• literal product behavior versus translated explanations.

The pilot preserves the source page structure and all technical details.

I can provide the full translation in a small draft PR or in this issue after the maintainers confirm the preferred review format.

Terminology approach

I have also prepared an initial pt-BR glossary to keep terminology consistent across pages.

Examples of the current decisions:

English	Proposed pt-BR
agent	agente
main agent	agente principal
subagent	subagente
session	sessão
context	contexto
context compression	compactação do contexto
tool call	chamada de ferramenta
approval request	solicitação de aprovação
slash command	comando de barra
built-in tool	ferramenta integrada
working directory	diretório de trabalho

Official names and technical identifiers would remain unchanged, including:

• Kimi Code CLI;
• Kimi Code for VS Code;
• Agent Skills;
• Skill;
• MCP;
• OAuth;
• JSON and JSONL;
• commands, flags, paths, field names, and environment variables.

Literal interface labels would not be silently translated when the product interface still displays them in English. The documentation could show the original label followed by a Portuguese explanation when necessary.

Maintenance proposal

I am willing to act as the initial pt-BR maintainer and point of contact.

The proposed process is:

1. Treat docs/en/ as the canonical source.
2. Update the corresponding docs/pt-br/ page in the same PR when practical.
3. Otherwise, submit a small synchronization PR linked to the source change.
4. Prioritize security, authentication, installation, configuration, and behavioral changes.
5. Batch minor editorial updates when they do not affect user instructions.
6. Update the terminology glossary whenever a new product term appears.
7. Run the VitePress build and review links, navigation, and rendering before each PR.
8. Document the synchronization status so additional Brazilian Portuguese contributors can help.

Machine-assisted translation may be used as a first pass, but every change would receive human review for meaning, terminology, and technical correctness.

The process should not depend permanently on a single contributor. The maintenance notes and glossary would be documented so other reviewers can participate.

Changelog policy

The release changelog requires a separate decision because it is updated after releases and already contains a substantial history.

Possible approaches:

1. translate the complete release history;
2. translate only releases published after the pt-BR locale is accepted;
3. keep the changelog in English and link to the canonical page.

My initial recommendation would be option 2: translate new releases from the date the localization becomes official, while allowing older entries to be translated gradually without blocking the initial launch.

I am happy to follow whichever policy best fits the project's release workflow.

Suggested rollout

To avoid opening a large pull request before alignment, I suggest the following sequence:

1. Review and approve the locale structure and terminology approach.
2. Review the pilot sessions.md translation.
3. Decide whether the first implementation should be:
   • a complete mirrored locale;
   • a smaller initial set of pages with an explicit translation status;
   • or a complete locale excluding historical release notes.
4. Submit the implementation in focused, reviewable pull requests.
5. Establish the synchronization tracker and maintenance process.

My preference is to start with the pilot review and let the maintainers choose the desired initial publication scope.

Questions for maintainers

1. Would an official Brazilian Portuguese localization be welcome in this repository?
2. Is docs/pt-br/ the preferred directory name, or would you prefer another locale slug?
3. Should a new locale be complete before it is added to the public language selector?
4. What changelog policy would you prefer for a new localization?
5. Should docs/customization/datasource.md be included in the mirrored locale even though it is not currently listed in the sidebar?
6. Would you prefer the glossary and pilot translation in a draft PR, as attachments to this issue, or in another format?

I am happy to adapt the proposal, terminology, and maintenance process to the project's preferred conventions.

Review docs/.vitepress/config.ts, docs/index.md, and the existing docs/en/ structure first, then inspect the pilot source at docs/en/guides/sessions.md. Run the VitePress build to understand validation needs. Done means maintainers have chosen the locale structure, rollout scope, changelog policy, and review format before implementation begins.