Internacionalizando Sites
Fluxo de trabalho completo para adicionar suporte multilíngue a sites Next.js com as melhores práticas de SEO.
Quando usar este Skill
- Adicionar novas versões de idioma a um site existente
- Configurar i18n (internacionalização) para um novo site
- Configurar SEO para múltiplos idiomas
- O usuário menciona: "adicionar idioma", "tradução", "localização", "hreflang", "multilíngue"
Idiomas Suportados
Mercados-alvo comuns:
- 🇺🇸 Inglês (en) - Mercado global
- 🇯🇵 Japonês (ja) - Mercado asiático
- 🇨🇳 Chinês (zh) - Mercado chinês
Suporte estendido disponível para:
- Coreano (ko), Português (pt), Espanhol (es), Francês (fr), Alemão (de)
- Árabe (ar), Vietnamita (vi), Hindi (hi), Indonésio (id), Tailandês (th)
- Chinês Tradicional (zh-hk), Italiano (it), Russo (ru)
Fluxo de Trabalho de Internacionalização
Copie esta lista de verificação e acompanhe seu progresso:
Progresso i18n:
- [ ] Passo 1: Preparar arquivos de idioma base
- [ ] Passo 2: Adicionar novos arquivos de idioma
- [ ] Passo 3: Atualizar arquivos de configuração
- [ ] Passo 4: Adicionar traduções
- [ ] Passo 5: Configurar elementos SEO
- [ ] Passo 6: Validar e testar
Passo 1: Preparar arquivos de idioma base
Certifique-se de que os arquivos em inglês (en.json) existam como modelos:
Diretórios obrigatórios:
i18n/messages/en.json- Traduções principaisi18n/pages/landing/en.json- Traduções da página inicial
Verificar estrutura:
# Verificar se os arquivos base existem
ls i18n/messages/en.json
ls i18n/pages/landing/en.json
Se estiverem faltando, crie-os com chaves de tradução completas para seu site.
Passo 2: Adicionar novos arquivos de idioma
Execute o script de adição de idiomas:
node scripts/i18n-add-languages.mjs
O que este script faz:
- Copia
en.jsonpara todos os arquivos de idioma de destino - Atualiza
i18n/locale.tscom os novos locales - Atualiza
i18n/request.tscom os mapeamentos de idioma - Atualiza
public/sitemap.xmlcom novas URLs de idioma
Configuração do script (em i18n-add-languages.mjs):
- Array
languages- Lista de idiomas a adicionar - Objeto
languageNames- Nomes de exibição dos idiomas - Array
targetDirs- Diretórios contendo arquivos de tradução
Consulte WORKFLOW.md para um guia passo a passo detalhado.
Passo 3: Verificar atualizações de configuração
Verificar i18n/locale.ts:
export const locales = ["en", "ja", "zh", "ko", ...];
export const localeNames: any = {
en: "English",
ja: "日本語",
zh: "中文",
ko: "한국어",
...
};
Verificar i18n/request.ts:
- Mapeamentos de códigos de idioma configurados
- Mapeamentos
zh-CN→zh,zh-HK→zh-hkpresentes
Verificar public/sitemap.xml:
- Todas as versões de idioma listadas
- Tags
hreflangpresentes para cada URL
Passo 4: Adicionar traduções
Opção A: Usando tradução por IA (mais rápida, mas precisa de revisão):
# Adicionar dados estruturados e traduções de preços
node scripts/i18n-add-schema.js
Configure as traduções no objeto translations do script.
Opção B: Tradução manual (recomendada para qualidade):
Edite cada arquivo de idioma com as traduções adequadas:
# Abrir arquivo de idioma
code i18n/messages/ja.json
Melhores práticas de tradução:
- Use falantes nativos quando possível
- Mantenha palavras-chave SEO no idioma de destino
- Adapte o conteúdo à cultura local, não apenas traduza
- Mantenha a formatação consistente (placeholders, variáveis)
Consulte reference/locale-codes.md para referência de códigos de idioma.
Passo 5: Configurar elementos SEO
Tags hreflang - Automáticas via sitemap, mas verifique:
Consulte reference/hreflang-guide.md para um guia completo.
Meta tags localizadas - Traduza em cada arquivo de idioma:
{
"metadata": {
"title": "Título do seu Site",
"description": "Sua descrição SEO"
}
}
Estrutura de URL - Verifique o formato correto:
- Inglês:
https://exemplo.com/ouhttps://exemplo.com/en/ - Japonês:
https://exemplo.com/ja/ - Chinês:
https://exemplo.com/zh/
Passo 6: Validar e testar
Compilar o projeto:
npm run build
CRÍTICO: Corrija quaisquer erros antes de prosseguir.
Testes manuais:
-
Seletor de idioma:
- Visite cada versão de idioma
- Verifique se o seletor de idioma mostra todos os idiomas
- Clique em cada link de idioma, verifique se a página correta carrega
-
Exibição de conteúdo:
- Verifique se todas as páginas são renderizadas corretamente em cada idioma
- Verifique se não há texto não traduzido (procure por inglês em páginas não-inglesas)
- Teste a exibição correta de caracteres especiais (japonês, chinês, árabe)
-
Elementos SEO:
- Inspecione se o atributo
<html lang="...">corresponde ao idioma da página - Verifique se as tags
<link rel="alternate" hreflang="...">estão presentes - Verifique se as meta tags estão no idioma correto
- Inspecione se o atributo
Validação automatizada:
# Verificar sitemap
curl https://seu-site.com/sitemap.xml | grep hreflang
# Validar hreflang (use ferramenta online)
# Google Search Console > Internacionalização > hreflang
Lista de verificação SEO - Consulte reference/seo-checklist.md.
Se a validação falhar:
- Revise as mensagens de erro cuidadosamente
- Verifique arquivos de configuração em busca de erros de digitação
- Confirme que os códigos de idioma estão corretos
- Volte ao Passo 3 e corrija os problemas
Prossiga somente quando todas as validações passarem.
Notas Importantes
Padrões de Código de Idioma
Use ISO 639-1 (códigos de duas letras) com variantes regionais opcionais:
en- Inglêsja- Japonêszh- Chinês Simplificadozh-hk- Chinês Tradicional (Hong Kong)pt- Portuguêspt-br- Português Brasileiro
Consulte reference/locale-codes.md para a lista completa.
Implicações de SEO
O i18n correto melhora o SEO ao:
- Segmentar usuários em seu idioma nativo
- Evitar penalidades por conteúdo duplicado
- Ajudar os mecanismos de busca a servir a versão de idioma correta
Erros comuns de SEO a evitar:
- ❌ Redirecionamento automático baseado em IP (impede que os mecanismos de busca rastreiem todas as versões)
- ❌ Tags hreflang ausentes (causa problemas de conteúdo duplicado)
- ❌ Estrutura de URL inconsistente entre idiomas
- ❌ Meta tags não traduzidas
Qualidade da Tradução
Tradução por IA vs Tradução humana:
- ✅ IA: Rápida, econômica, boa para um rascunho inicial
- ⚠️ IA: Pode perder nuances culturais, precisa de revisão
- ✅ Humano: Melhor qualidade, adaptação cultural
- ⚠️ Humano: Mais lenta, mais cara
Abordagem recomendada:
- Use IA para gerar traduções iniciais
- Peça a um falante nativo para revisar e refinar
- Teste com usuários do mercado-alvo
- Itere com base no feedback
Roteamento i18n no Next.js
O sistema usa next-intl para roteamento:
- Detecção automática de locale a partir da URL
- Componente seletor de idioma
- Navegação localizada
Configuração em i18n/locale.ts e i18n/request.ts.
Tarefas Pós-Internacionalização
Após adicionar idiomas:
- Envie o sitemap atualizado para o Google Search Console
- Crie propriedades separadas no Search Console para cada idioma/região
- Monitore o tráfego orgânico internacional no Analytics
- Teste A/B as traduções se as taxas de conversão variarem por idioma
- Configure alertas para erros de rastreamento internacional
Localização dos Scripts
Todos os scripts i18n estão no diretório scripts/:
i18n-add-languages.mjs- Adicionar novos arquivos de idiomai18n-add-schema.js- Adicionar traduções de dados estruturados
Materiais de Referência
- WORKFLOW.md - Fluxo de trabalho detalhado passo a passo
- reference/hreflang-guide.md - Guia de implementação de hreflang
- reference/locale-codes.md - Referência de códigos de idioma
- reference/seo-checklist.md - Lista de verificação SEO internacional
Para solução de problemas, consulte a seção de solução de problemas em WORKFLOW.md.