Arquitetura completa para aplicacoes multilinguais
Arquitetura completa para aplicacoes multilinguais
Demonstracao interativa do sistema de i18n implementado com next-intl, suportando PT-BR, EN e ES com type-safety completo, traducao automatica via DeepL/Google Cloud e validacao de qualidade.
Veja a traducao acontecendo em tempo real
Selecione o idioma
Preview — pt-BR
Saudacao
Ola, Vinicius!
Bem-vindo ao nosso sistema de internacionalizacao. Este texto muda dinamicamente conforme o idioma selecionado.
Data formatada
23 de março de 2026 às 17:53
Numero formatado
R$ 1.234.567,89
Contagem de itens
5 itens
Como o sistema foi construido
Todas as traducoes partem do portugues. Os arquivos en/ e es/ sao gerados automaticamente via scripts, garantindo consistencia e eliminando duplicacao manual.
Scripts inteligentes detectam novas chaves em pt-BR e traduzem automaticamente usando DeepL API (preferencial) ou Google Cloud Translation com rate limiting.
TypeScript com autocomplete para todos os namespaces e chaves. O compilador avisa se uma chave de traducao esta errada ou faltando parametros.
Scripts de validacao detectam vazamento de portugues em en/es, verificam sincronizacao de chaves entre idiomas e podem ser integrados ao CI/CD.
Como abordar internacionalização (i18n) em diferentes contextos de projeto? Veja dicas práticas para cada cenário:
DeepL API - 500k caracteres/mes gratis
DeepL oferece traducoes mais naturais que Google Translate
Traducao acontece antes do build, zero impacto em runtime
Plano gratuito suficiente para a maioria dos projetos
# Obtenha sua chave gratuita em: https://www.deepl.com/pt-BR/pro-apiDEEPL_API_KEY=sua_chave_aqui# Alternativa: Google Cloud Translation# GOOGLE_CLOUD_API_KEY=sua_chave_aqui
💡 Dica: O plano gratuito do DeepL oferece 500.000 caracteres por mes, suficiente para ~50 paginas de conteudo. Perfeito para startups e projetos pessoais.
Traducoes carregadas em build-time, nao em runtime
Todas as traducoes sao processadas durante o build. O bundle final ja contem apenas o idioma necessario.
Cada locale tem seu proprio bundle. Usuario baixa apenas o idioma que esta usando.
TypeScript valida todas as chaves em tempo de desenvolvimento. Impossivel usar chave inexistente.
Diferentes abordagens para cada contexto
Processo passo a passo para adicionar traducoes
Adicione ou edite as chaves de traducao no arquivo JSON correspondente em messages/pt-BR/.
vim messages/pt-BR/global.jsonExecute o script que detecta novas chaves e traduz automaticamente para EN e ES.
pnpm run translateVerifique se nao ha vazamento de portugues nas traducoes e se todos os idiomas estao sincronizados.
pnpm run check:pt-leaksConfirme que todos os locales possuem as mesmas chaves para evitar erros em producao.
pnpm run validate:i18nImporte o hook useTranslations com o namespace correto e use t() para acessar as traducoes com autocomplete.
Ferramentas de automacao do sistema i18n
pnpm run translateTraduz apenas chaves novas de pt-BR para en/es. Preserva traducoes existentes.
pnpm run translate:forceRe-traduz TODAS as chaves do zero. Use quando encontrar traducoes ruins.
pnpm run validate:i18nValida se todos os locales possuem as mesmas chaves sincronizadas.
pnpm run check:pt-leaksDetecta palavras em portugues vazando para arquivos en/es.
pnpm run add-locale -- {code}Cria estrutura completa para um novo idioma (ex: de, fr, it).
Convencoes do projeto para manter a qualidade
SEMPRE edite pt-BR primeiro (fonte de verdade)
Use namespaces descritivos: auth, global, admin.userManagement
Reutilize textos globais para acoes comuns (salvar, cancelar)
Rode translate + validate antes de commitar
Use placeholders {variavel} para conteudo dinamico
Combine namespaces especificos + global no mesmo componente
NUNCA edite en/es manualmente (serao sobrescritos)
Nao deixe textos hardcoded no JSX
Evite duplicar textos que ja existem em global
Nao concatene strings traduzidas (quebra gramatica)
Nao use chaves excessivamente longas
Nao crie namespaces genericos como 'page1' ou 'form'
Principais erros de i18n e como resolver rapidamente.
Tradução não aparece (typo na chave)
const t = useTranslations("auth");
t("login.tittle"); // typo: 'tittle' em vez de 'title'const t = useTranslations("auth");
t("login.title"); // TypeScript avisa se errarChave não encontrada (namespace errado)
const t = useTranslations("admin");
t("actions.save"); // 'actions' está em 'global'!const tGlobal = useTranslations("global");
tGlobal("actions.save");Texto em português aparece em en/es
# messages/en/global.json: "back": "Voltar"
pnpm run translate:force pnpm run check:pt-leaks
TypeScript não sugere chaves ou acusa erro falso
// Possível causa: TypeScript não atualizou
// Ctrl+Shift+P → 'TypeScript: Restart TS Server' // Se não resolver: Reload Window
Cannot find module '../../messages/pt-BR/...'
# Possível causa: Arquivo novo não foi salvo
# Ctrl+K S (VS Code) e reinicie TS Server
Organizacao do sistema de mensagens
pt-BR e a fonte de verdade. en/ e es/ sao gerados automaticamente. Cada modulo tem sua pasta com index.ts proprio.
messages/├── pt-BR/ # Fonte de verdade│ ├── index.ts # Barrel export│ ├── auth.json # Autenticacao│ ├── global.json # Acoes, status, navegacao│ ├── components.json # UI compartilhados│ ├── errors.json # Mensagens de erro│ ├── admin/│ │ ├── index.ts│ │ └── user-management.json│ ├── consultor/│ │ ├── index.ts│ │ └── business-unit.json│ └── cockpit/│ ├── index.ts│ └── dashboard.json├── en/ # Gerado automaticamente└── es/ # Gerado automaticamentesrc/i18n/├── config.ts # Locales suportados├── routing.ts # Config next-intl├── request.ts # Resolver locale (cookie)├── load-messages.ts # Carregar JSONs└── types.d.ts # TypeScript autocomplete
Repositorio completo com toda a estrutura de i18n, scripts de automacao e documentacao. Pronto para usar em producao.
Este sistema de i18n demonstra uma arquitetura production-ready com type-safety, automacao e qualidade. Tudo construido com next-intl v4+.
Voltar às Implementações