Internacionalização¶

O CodexSpec oferece suporte a múltiplos idiomas por meio de tradução dinâmica por LLM e fornece documentação multilíngue para o GitHub Pages.

Tradução de templates de comando¶

Como funciona¶

Templates únicos em inglês: todos os templates de comando permanecem em inglês
Configuração de idioma: o projeto especifica o idioma de saída preferido
Tradução dinâmica: o Claude traduz o conteúdo em tempo de execução

Dimensões de idioma¶

O CodexSpec divide o idioma em quatro dimensões configuráveis de forma independente. output é a base; as demais a sobrescrevem e recaem sobre ela (e depois sobre en) quando não definidas.

Dimensão	Chave do `config.yml`	Definir no init	Definir depois	Controla	Recai sobre
Saída (base)	`output`	`--lang`	`config --set-lang`	base para as outras três	`en`
Interação	`interaction`	`--interaction-lang`	`config --set-interaction-lang`	diálogo com o LLM + saída do CLI	output → `en`
Documento	`document`	`--document-lang`	`config --set-document-lang`	spec/plan/tasks gerados	output → `en`
Commit	`commit`	`--commit-lang`	`config --set-commit-lang`	mensagens de commit do git	output → `en`
Templates	`templates`	—	—	origem dos templates de comando (sempre `en`)	—

Definindo o idioma¶

Durante a inicialização¶

# Saída em chinês (define a base de output)
codexspec init my-project --lang zh-CN

# Totalmente não interativo: base em zh-CN, mensagens de commit em inglês
codexspec init my-project --lang zh-CN --commit-lang en

# Definir cada dimensão explicitamente (scriptável, sem prompts)
codexspec init my-project \
  --interaction-lang zh-CN --document-lang en --commit-lang en

A primeira execução do init em um TTY sem --lang (e sem as três flags de dimensão) solicita um idioma base; em um ambiente não-TTY (CI/scripts) o padrão é en. Executar o init novamente preserva qualquer chave de idioma que você não tenha especificado.

Após a inicialização¶

# Ver a configuração atual
codexspec config

# Alterar uma única dimensão
codexspec config --set-lang zh-CN
codexspec config --set-interaction-lang zh-CN
codexspec config --set-document-lang en
codexspec config --set-commit-lang en

# Alternar workflow.auto_next (a flag isolada alterna; ou passe on/off explicitamente)
codexspec config --auto-next

# Listar os idiomas suportados
codexspec config --list-langs

Arquivo de configuração¶

.codexspec/config.yml:

version: "1.0"

language:
  output: "zh-CN"        # Idioma base; os três abaixo recaem sobre ele, depois sobre "en"
  interaction: "zh-CN"   # Diálogo com o LLM + saída do CLI codexspec (opcional → padrão: output)
  document: "en"         # Requisitos/spec/plan/tasks gerados (opcional → padrão: output)
  commit: "en"           # Mensagens de commit do git (opcional → padrão: output)
  templates: "en"        # Mantenha como "en"

project:
  ai: "claude"          # claude | codex | both — qual assistente de IA este projeto usa
  created: "2025-02-15"

i18n da documentação no GitHub Pages¶

Idiomas do site de docs vs. idiomas da CLI/runtime — não os confunda.

Site de documentação (esta seção): 8 idiomas. O site do GitHub Pages gerado pelo MkDocs entrega exatamente os oito locales listados abaixo (en, zh, ja, ko, es, fr, de, pt-BR). Este é um conjunto fixo, definido pelo layout de diretórios docs/{lang}/ e pelo plugin mkdocs-i18n.

CLI / runtime (a seção acima): 13 idiomas. As dimensões language.* que você configura em .codexspec/config.yml aceitam 13 códigos suportados (en, zh-CN, zh-TW, ja, ko, es, fr, de, pt-BR, ru, it, ar, hi), traduzidos em tempo real pelo LLM. Veja a tabela "Supported Languages" no README do projeto para a lista canônica.

Os dois conjuntos se sobrepõem, mas não são idênticos: o site de docs não tem locales zh-TW/ru/it/ar/hi, e a CLI não usa os códigos puros zh/de/... que o MkDocs usa como nomes de pasta.

O site de documentação do CodexSpec suporta 8 idiomas usando MkDocs com o plugin mkdocs-i18n.

Idiomas suportados¶

Código	Idioma
`en`	English (padrão)
`zh`	中文简体
`ja`	日本語
`ko`	한국어
`es`	Español
`fr`	Français
`de`	Deutsch
`pt-BR`	Português (Brasil)

Estrutura de diretórios¶

docs/
├── en/                 # Inglês (fonte)
│   ├── index.md
│   ├── user-guide/
│   └── ...
├── zh/                 # Tradução em chinês
├── ja/                 # Tradução em japonês
├── ko/                 # Tradução em coreano
├── es/                 # Tradução em espanhol
├── fr/                 # Tradução em francês
├── de/                 # Tradução em alemão
└── pt-BR/              # Tradução em português (Brasil)

Traduzindo a documentação (apenas para mantenedores)¶

Nota: Os comandos /codexspec:translate-docs e /codexspec:check-i18n-semantics são ferramentas exclusivas dos mantenedores do CodexSpec. Eles estão fortemente acoplados ao layout i18n do MkDocs deste repositório (docs/{lang}/) e ao glossário interno em docs/i18n/glossary.yml. Eles não são distribuídos a projetos de usuários via codexspec init e não estão disponíveis como slash commands voltados ao usuário final.

Se você estiver trabalhando no próprio CodexSpec, esses comandos vivem em .claude/commands/codexspec/ e são invocados da mesma forma que qualquer outro slash command. Usuários finais que estejam traduzindo a documentação do seu próprio projeto devem usar o Claude diretamente, no fluxo de trabalho que preferirem.

Para mantenedores do CodexSpec, use o comando /codexspec:translate-docs para traduzir a documentação:

# Traduzir para chinês
/codexspec:translate-docs --lang zh

# Traduzir um arquivo específico para japonês
/codexspec:translate-docs user-guide/installation.md --lang ja

# Tradução incremental (apenas arquivos alterados)
/codexspec:translate-docs --lang ko --incremental

# Modo preview (sem alterar arquivos)
/codexspec:translate-docs --lang es --dry-run

Glossário de tradução¶

O glossário em docs/i18n/glossary.yml (apenas no repositório) garante terminologia consistente ao traduzir a própria documentação do CodexSpec:

version: "1.0"

# Termos para manter em inglês
keep_english:
  - CLI
  - API
  - YAML
  - JSON

# Traduções para termos comuns
translations:
  zh:
    specification: "规格说明"
    constitution: "宪法"
    task: "任务"

# Regras inteligentes para casos especiais
rules:
  - pattern: '\b(CLI|API)\b'
    action: keep

Metodologia de tradução¶

As traduções têm como objetivo ler de forma natural no seu idioma, e não como transcrições palavra a palavra do inglês:

O significado em primeiro lugar. Cada trecho é traduzido pelo que ele comunica e depois reexpresso com a redação e a estrutura de frases do idioma de destino.
Termos em inglês permanecem quando são mais claros. Termos técnicos sem um equivalente nativo adequado — ou mais reconhecíveis em inglês — são mantidos em inglês em vez de traduzidos de forma forçada. Por exemplo, "AI coding agent" vira uma frase nativa natural como "AI 编程助手", e não uma tradução literal e rígida.
Fluência nativa. O objetivo é uma prosa que leia como se tivesse sido escrita originalmente no seu idioma.

Verificações de qualidade¶

Verificação de estrutura¶

Verifica se todos os diretórios de idioma têm a mesma estrutura de arquivos:

./scripts/bash/check-i18n-structure.sh

Verificação de completude¶

Detecta conteúdo em inglês não traduzido nas traduções:

./scripts/bash/check-i18n-completeness.sh

Verificação semântica (apenas para mantenedores)¶

Análise de consistência semântica com IA, disponível para mantenedores do CodexSpec por meio do comando interno (veja a nota "apenas para mantenedores" acima):

/codexspec:check-i18n-semantics --lang zh

Integração com CI/CD¶

O workflow .github/workflows/docs-i18n.yml é apenas um portão de build: a cada alteração em docs/** / mkdocs.yml (push para main e pull requests) ele executa mkdocs build --strict em todas as versões de idioma para capturar erros de build, links quebrados e conteúdo malformado. Ele não traduz nada.

As traduções são produzidas e commitadas manualmente via /codexspec:translate-docs (veja acima), com a fonte em inglês e todas as traduções em um único commit atômico e revisado. A tradução automática em CI foi removida intencionalmente — o job anterior nunca chegava a executar (um if malformado o ignorava), exigia uma chave de API permanente e teria commitado traduções não revisadas diretamente na main.

Benefícios¶

Zero manutenção de tradução: não é necessário manter várias versões de template
Sempre atualizado: atualizações de template beneficiam todos os idiomas
Context-aware: termos técnicos permanecem em inglês quando apropriado
Qualidade automatizada: o CI garante a consistência da tradução
Assistido por IA: o Claude fornece traduções context-aware