Filament Core Suite

Appearance

ADR-006: Português como Idioma Primário ​

Status: Aceito

Data: 2024-11-02

Decisores: Aron Cardoso

Contexto ​

O Filament Core Suite é desenvolvido no Brasil, com equipe falante de português. Precisávamos decidir o idioma para documentação, código e comunicação do projeto.

Forças em jogo:

  • Audiência alvo: Principalmente desenvolvedores brasileiros
  • Acessibilidade: Facilitar compreensão e contribuição
  • Alcance global: Possibilidade de internacionalização futura
  • Padrões da indústria: Maioria de docs técnicas em inglês
  • Código: Convenções de nomenclatura em inglês são padrão

Alternativas Consideradas ​

Opção 1: Inglês para Tudo ​

  • Prós:
    • Alcance global
    • Padrão da indústria
    • Facilita contribuições internacionais
    • Código e docs no mesmo idioma
  • Contras:
    • Barreira para desenvolvedores brasileiros
    • Qualidade pode sofrer (tradução mental)
    • Menos natural para equipe local

Opção 2: Português para Tudo (Incluindo Código) ​

  • Prós:
    • Zero fricção para equipe brasileira
    • Comunicação mais clara
    • Alinhamento perfeito docs-código
  • Contras:
    • Código em português é não-idiomático
    • Quebra convenções da comunidade
    • Dificulta uso de bibliotecas internacionais
    • Prejudica code review por ferramentas

Opção 3: Hybrid - Código em Inglês, Docs em Português (Escolhida) ​

  • Prós:
    • Código segue padrões internacionais
    • Documentação acessível para equipe local
    • Melhor dos dois mundos
    • Permite i18n futuro para docs
  • Contras:
    • Dois idiomas em um projeto (potencial confusão)
    • Decisões de onde usar cada idioma

Decisão ​

Adotamos abordagem híbrida com as seguintes regras:

1. Código sempre em Inglês ​

php
// ✅ Correto
class PersonCreated {}
interface PaymentGatewayInterface {}
public function calculateTax() {}

// ❌ Incorreto
class PessoaCriada {}
interface InterfaceGatewayPagamento {}
public function calcularImposto() {}

Razão: Código PHP/JavaScript em inglês é convenção universal.

2. Documentação primária em Português ​

  • README.md: Português
  • CONTRIBUTING.md: Português
  • CHANGELOG.md: Português
  • docs/**/*.md: Português
  • Commit messages: Português (Conventional Commits em PT)
  • Issues/PRs: Português

Razão: Facilita contribuição da equipe brasileira.

3. Comentários de código em Português ​

php
// ✅ Comentário explicativo pode ser em português
public function calculateTax(): Money
{
    // Aplica alíquota de 18% para produtos nacionais
    return $this->price->multiply(0.18);
}

Razão: Comentários destinados a equipe local.

4. Termos técnicos mantêm original ​

  • Interface, Service Provider, Event, Listener → mantém em inglês
  • DTO, Repository, Controller → mantém em inglês
  • Apenas traduza quando necessário para clareza

Razão: Consistência com literatura técnica.

5. Interface do VitePress em Português ​

  • Labels de navegação: Português
  • Busca: Português
  • Mensagens de erro: Português

Razão: Experiência do usuário otimizada para público-alvo.

Consequências ​

Positivas ​

  • Acessibilidade: Documentação clara para desenvolvedores brasileiros
  • Produtividade: Menos fricção na escrita de docs
  • Código idiomático: Segue padrões internacionais de PHP/JS
  • Flexibilidade futura: Docs podem ser traduzidas para inglês
  • Comunicação clara: Issues e discussões em linguagem natural

Negativas ​

  • Alcance limitado: Documentação não é acessível para não-lusófonos
  • Dualismo: Dois idiomas no mesmo projeto pode confundir
  • Contribuições internacionais: Barreira para contributors externos
  • Busca online: Docs em português têm menos visibilidade

Neutras ​

  • Necessita guidelines claros: Quando usar cada idioma deve estar documentado
  • Requer disciplina: Contributors precisam seguir convenções

Notas de Implementação ​

Commits em Português ​

bash
# ✅ Correto
git commit -m "docs: adicionar guia de webhooks"
git commit -m "feat: implementar validação de CPF"
git commit -m "fix: corrigir cálculo de impostos"

# ❌ Incorreto (evitar inglês em commits)
git commit -m "docs: add webhooks guide"

Nomenclatura de Branches ​

bash
# ✅ Pode ser em português
git checkout -b docs/adicionar-guia-webhooks
git checkout -b feat/validacao-cpf

README.md Bilíngue (Opcional Futuro) ​

markdown
# Filament Core Suite

[English](#english) | [Português](#português)

## Português

Descrição em português...

## English

English description...

VitePress i18n (Futuro) ​

typescript
export default defineConfig({
  locales: {
    root: {
      label: 'Português',
      lang: 'pt-BR'
    },
    en: {
      label: 'English',
      lang: 'en-US',
      link: '/en/'
    }
  }
})

Exceptions ​

Casos onde inglês pode ser usado em documentação:

  • Citações de fontes em inglês
  • Nomes de tecnologias (Laravel, VitePress, GitHub)
  • Termos técnicos sem tradução consagrada
  • Links para documentação externa

Referências ​

Documentação privada do ecossistema Filament Core.

© 2025 Aron Cardoso