ADR-002 — English-only identifiers and comments in source code

Date: 2026-05-07 Status: Accepted

Context

A Fase 2 entregou o canon como Pedidos (PT-BR): Pedido, EPedidoStatus.{Pendente, Aprovado, Cancelado}, Aprovar, Cliente, CriarPedido, etc. Em paralelo, o DevPack (consumido pelo template) e todos os pacotes Microsoft/Mediator/FluentValidation usam APIs em inglês. O resultado é uma codebase mista: identificadores PT junto a IServiceCollection, DbContext, Result<T>, INotificationHandler<T> etc.

Mistura PT/EN cria atrito:

• Para devs novos (que podem ter passado anos lendo .NET em inglês): trocar contexto entre Order.Approve() e Pedido.Aprovar() em chamadas vizinhas custa atenção.
• Para agentes de IA (que treinaram majoritariamente em código inglês): geram código menos consistente em codebases mistas — autocompletion sugere Approve quando o canon espera Aprovar.
• Para search/grep: OrderId e PedidoId precisam buscas separadas para conceitos equivalentes.

Decision

Todo identificador, comentário, XML doc, log message, mensagem de exceção, código de erro (Error.Code), nome de arquivo/pasta e nome de teste em src/ e tests/ é 100% em inglês.

Markdown documentation (CLAUDE.md, README.md, arquivos em docs/) permanece em português — é prosa para humanos do time, não código.

Decisão aplicada retroativamente: Pedidos → Orders, Aprovar → Approve, EPedidoStatus.Pendente → EOrderStatus.Pending, Cliente → Customer (no campo de Order), CriarPedido → CreateOrder, etc. Migration regenerada como InitialCreate (não InitialCreatePedidos).

Consequences

Positivas:

• Codebase 100% consistente — code review, search, IDE features, IA suggestions ficam alinhados.
• Strings de erro ("Order.NotFound") viajam para clientes/parceiros sem necessidade de tradução.
• Templates de outros times ITLab que sigam padrão similar ficam intercambiáveis.

Negativas:

• Refactor inicial pesado: ~30 arquivos renomeados na Fase 2 quando a decisão foi ratificada.
• Devs lendo a doc PT (README/CLAUDE.md) e o código EN precisam fazer a tradução mental ao referenciar — mitigado mantendo os termos canônicos do domínio (Order, Customer) consistentes nos dois lados.

Scope

A regra cobre:

• src/**/*.cs — identifiers, XML doc, comments, string literals (incluindo Error.Code, log messages).
• tests/**/*.cs — test class/method names, fixtures, helpers.
• File/folder names em src//tests/.
• Migration names (InitialCreate, não InitialCreatePedidos).

A regra não cobre:

• *.md em qualquer pasta (preserva sessões históricas).
• appsettings*.json chaves (são scoped; Authentication:Jwt:Authority é o caminho documentado).
• User-facing error messages na hora de localização (a localização vive em resource files quando adicionada; a chave dentro do .cs continua inglês).

Alternatives considered

Opção	Por que descartada
Manter PT no domínio (Pedidos/Cliente)	Inconsistência com framework + dificuldade de IA assistance.
Tudo em inglês incluindo docs	Sessões anteriores do time ratificaram PT-BR como linguagem da doc — markdown é onde a discussão acontece.
EN nos identifiers + PT em XML doc	Hibridismo ruim — XML doc é lido pelo IDE em tooltips junto ao identifier, gera atrito.

References

• Memory entry: feedback_codebase_language.md.
• Commit fbc310a (initial Pedidos canon) + commits subsequentes do rename.