ADR-0046: Portal de docs só em pt-BR — remover o espelho docs/en

Status: accepted Date: 2026-09-14 Deciders: @barateza Supersedes in part: ADR-0035 (trilha de docs — §2 pins/enforcement, §4 onboarding de docs, §5 paridade) Amends: ADR-0037 (a barreira de drift i18n que ele decidiu manter não existe mais) Tags: [i18n, docs, docs/en, vitepress, cloudflare-pages, adr-0035, adr-0037, v1]

Context

O portal carregava um espelho inglês manual de docs/ (docs/en, 105 arquivos), com uma política "no-partial" (Kubernetes/MDN) e pins de frescor (default_lang_commit) verificados em CI por scripts/check-i18n.sh. O custo era real e contínuo: toda edição de página pt-BR exigia a tradução correspondente (ou um marcador # patched) no mesmo commit, sob pena de CI vermelho — ADR-0035 §2 tornou o drift bloqueante no v1.

Na prática a política também não se sustentava:

• A qualidade não era verificável. docs/en misturava páginas traduzidas, stubs byte-idênticos ao pt-BR (que a checagem acusava como falha, mas que existiam), páginas pt-BR servidas sob /en e páginas sem contraparte.
• O produto não tem público internacional hoje. O Neemias é um produto pt-BR; ninguém consome o portal em inglês, e o portal é documentação interna para contribuidores.
• O app nunca teve multi-locale. O runtime de i18n do app é um único objeto pt_BR (app/src/app/utils/i18n.ts, 84 linhas); app/src/locales/ não existe, não há seletor de idioma nem cadeia de fallback. O "en-US/es-ES" vivia apenas em specs, ADRs e SDDs — aspiração, não código.
• Dois documentos-fonte nem estavam em pt-BR. docs/product/prd.md e docs/architecture/srs.md — as fontes de verdade de produto e engenharia — tinham corpo 100% em inglês, contradizendo a própria regra "raiz = pt-BR".

Manter o espelho comprava nada e custava um gate de CI bloqueante em cada mudança de documentação.

Decision

O portal de documentação entrega só pt-BR. O espelho docs/en foi removido, junto com toda a sua maquinaria.

1. Conteúdo e locale

• docs/en/ (105 arquivos, incluindo .i18n-exempt e as páginas geradas de reference/api/) foi deletado.
• Fica uma página no locale en: docs/en/index.md, um aviso de que a tradução para inglês está em andamento, com link de volta para o portal pt-BR.
• docs/public/_redirects mapeia /en/* → /en/ com 302 (temporário, não 301: páginas reais voltam quando a tradução existir). Cobre no Cloudflare Pages toda URL /en/... publicada antes — links antigos não morrem em 404.
• A config do VitePress mantém o locale en apenas para essa página: sem sidebar (não há páginas para linkar) e nav mínimo.

2. Ferramental removido

Removido	O que era
scripts/check-i18n.sh	checker orphan/stub/missing/pin/drift
scripts/__tests__/test-check-i18n.sh	fixtures do checker
docs/en/.i18n-exempt	globs de páginas isentas
pnpm docs:i18n, pnpm docs:i18n:commit	policy check e refresh de pins
pnpm docs:endpoints:check	guard de pin en provisório
Gate docs-i18n em ci.yml	step bloqueante do job docs
Linha docs-i18n em scripts/gates.registry	inventário de gates
.github/CODEOWNERS	existia só para docs/en/
Alvos en de scripts/generate-endpoints-doc.ts + CONTRACT_LOCALE.en	páginas en geradas e pinadas
EN_DIR/drift/.i18n-exempt em scripts/check-doc-links.sh	exclusões de /en/ no lychee

check-doc-links.sh mantém uma exclusão: ^$BASE/en/.+. O VitePress ainda renderiza um link por página para o locale en (ex.: /en/product/prd em /product/prd); esse caminho não tem página construída e o _redirects só existe no Cloudflare Pages — um vitepress preview local não o honra.

3. Tradução das fontes de verdade

docs/product/prd.md e docs/architecture/srs.md foram traduzidos para pt-BR, com IDs, caminhos, identificadores de papel (ADMIN, CHAMADOR), requisitos (FR-*, NFR-*, DR-*, SR-*, SCR-*) e alvos de link preservados. As páginas de espelho docs/en/product/prd.md e docs/en/architecture/srs.md saíram junto com o resto de docs/en.

4. App: a ambição multi-locale é descartada, não o código

Não havia código de locale para remover — apenas a planta:

• .specs/features/203-multi-language/ e .specs/features/i18n-app-post-mvp/ foram arquivadas (.specs/archive/features/), com nota de status.
• docs/architecture/sdd-203-internationalization.md foi arquivado em docs/archive/design/ e removido do índice de docs/architecture/.
• app/src/app/utils/i18n.ts, i18n/domains/*.ts e o teste de snapshot de pt_BR permanecem intactos — são pt-BR hoje e continuam sendo.

Ponto de extensão mantido de propósito. prd.md §2 ("permitir idiomas adicionais depois"), §6 (arquitetura de localização) e srs.md FR-020 e §11 ("expansão de idiomas") foram traduzidos literalmente, não removidos: a decisão é que pt-BR é o único idioma entregue, não que adicionar idiomas fique proibido. Um locale novo é uma decisão de custo futura, não um redesenho.

5. O que permanece na história

• ADR-0035 §1 (strings do app: MT + revisão humana) e §3 (fronteira app/docs) seguem em vigor; §2/§4/§5 ficam como registro histórico.
• ADR-0037 recebeu uma nota "Amended by" — a barreira de drift que ele decidiu manter não existe mais.
• Specs arquivadas e docs/research/i18n-docs-pre-mvp.md não foram reescritos: são registro do que se pensava na época, e é isso que eles devem continuar dizendo.

Consequences

Positivas

• Toda edição de documentação deixa de exigir uma tradução (ou um marcador de escape) para passar no CI. O job docs perde um gate bloqueante.
• Uma fonte de verdade por documento, em um idioma — inclusive as duas fontes que estavam em inglês.
• Nenhuma página pt-BR é servida como se fosse inglesa, e nenhum visitante anglófono cai numa página traduzida pela metade: ele vê um aviso explícito.

Negativas

• Quem lê inglês perde o portal; até a tradução existir, tudo passa pelo aviso em /en/.
• Reverter custa caro: retomar o espelho significa reconstruir o checker, os pins e a disciplina de tradução no mesmo commit — ou seja, reviver o custo que esta ADR eliminou.
• docs/index.md, docs/maintenance.md, docs/community/security-policy.md e docs/community/code-of-conduct.md continuam com corpo em inglês. A regra "raiz = pt-BR" ainda não é 100% verdadeira; a conversão é passagem de conteúdo, não mudança de política.

Neutras

• Um locale novo no futuro volta a ser uma decisão de custo explícita (ADR-0035 §4 descreve o procedimento, agora histórico).
• O locale en permanece na config do VitePress como um único aviso; removê-lo exigiria cobrir /en/ só por _redirects.

References

• docs/maintenance.md — "Portal language" e "Source Language Policy"
• docs/public/_redirects — o 302 de /en/*
• ADR-0035 — política de tradução (trilha de docs superada)
• ADR-0037 — simplificação de infraestrutura para solo dev + LLM
• docs/research/i18n-docs-pre-mvp.md — diagnóstico que originou o espelho
• Specs arquivadas: .specs/archive/features/2026-08-10_i18n-docs-{pre-mvp,v1}, .specs/archive/features/2026-09-14_*
• Issues: #588 (frescor do docs/en), #203 (multi-locale do app)