i18n & Localização
Regra de Leitura Seletiva
Comece com:
references/senior-master-standard.mdreferences/usage-routing.mdreferences/quality-checklist.md
Em seguida, carregue apenas os documentos herdados, scripts, assets ou exemplos que correspondam à tarefa real do usuário.
Práticas recomendadas de Internacionalização (i18n) e Localização (L10n).
1. Conceitos Principais
| Termo | Significado |
|---|---|
| i18n | Internacionalização - tornar o aplicativo traduzível |
| L10n | Localização - traduções reais |
| Locale | Idioma + Região (en-US, tr-TR) |
| RTL | Idiomas da direita para a esquerda (árabe, hebraico) |
2. Quando Usar i18n
| Tipo de Projeto | Precisa de i18n? |
|---|---|
| Aplicativo web público | ✅ Sim |
| Produto SaaS | ✅ Sim |
| Ferramenta interna | ⚠️ Talvez |
| Aplicativo de região única | ⚠️ Considere o futuro |
| Projeto pessoal | ❌ Opcional |
3. Padrões de Implementação
React (react-i18next)
import { useTranslation } from 'react-i18next';
function Welcome() {
const { t } = useTranslation();
return <h1>{t('welcome.title')}</h1>;
}
Next.js (next-intl)
import { useTranslations } from 'next-intl';
export default function Page() {
const t = useTranslations('Home');
return <h1>{t('title')}</h1>;
}
Python (gettext)
from gettext import gettext as _
print(_("Bem-vindo ao nosso aplicativo"))
4. Estrutura de Arquivos
locales/
├── en/
│ ├── common.json
│ ├── auth.json
│ └── errors.json
├── tr/
│ ├── common.json
│ ├── auth.json
│ └── errors.json
└── ar/ # RTL
└── ...
5. Boas Práticas
FAÇA ✅
- Use chaves de tradução, não texto bruto
- Namespace as traduções por funcionalidade
- Suporte a pluralização
- Lide com formatos de data/número por locale
- Planeje RTL desde o início
- Use o formato ICU para strings complexas
NÃO FAÇA ❌
- Hardcode strings nos componentes
- Concatene strings traduzidas
- Presuma o comprimento do texto (alemão é 30% mais longo)
- Esqueça o layout RTL
- Misture idiomas no mesmo arquivo
6. Problemas Comuns
| Problema | Solução |
|---|---|
| Tradução faltando | Fallback para o idioma padrão |
| Strings hardcoded | Use script linter/verificador |
| Formato de data | Use Intl.DateTimeFormat |
| Formato de número | Use Intl.NumberFormat |
| Pluralização | Use formato ICU |
7. Suporte RTL
/* Propriedades Lógicas CSS */
.container {
margin-inline-start: 1rem; /* Não margin-left */
padding-inline-end: 1rem; /* Não padding-right */
}
[dir="rtl"] .icon {
transform: scaleX(-1);
}
8. Checklist
Antes de publicar:
- Todas as strings voltadas para o usuário usam chaves de tradução
- Arquivos de locale existem para todos os idiomas suportados
- Formatação de data/número usa a API Intl
- Layout RTL testado (se aplicável)
- Idioma de fallback configurado
- Nenhuma string hardcoded nos componentes
Script
| Script | Propósito | Comando |
|---|---|---|
scripts/i18n_checker.py | Detectar strings hardcoded e traduções ausentes | python scripts/i18n_checker.py <project_path> |