Internacionalização Next.js: Guia i18n completo com next-intl

Mais de 75% dos usuários da Internet preferem navegar em seu idioma nativo, e as empresas que localizam obtêm taxas de conversão 70% mais altas em mercados que não o inglês. Next.js combinado com next-intl fornece uma estrutura de internacionalização robusta que lida com roteamento, traduções, formatação e SEO em qualquer número de localidades.

Principais conclusões

• next-intl integra-se perfeitamente com Next.js App Router e componentes de servidor
• O roteamento com prefixo de localidade mantém URLs em inglês limpos enquanto adiciona prefixos para outros idiomas
• Os componentes do servidor carregam traduções sem sobrecarga do pacote JavaScript do lado do cliente
• Tags hreflang adequadas e mapas de sites multilíngues são essenciais para SEO internacional

---

Configuração do projeto

Instale next-intl e organize seu projeto com um diretório i18n contendo routing.ts, navigation.ts e request.ts. Coloque seu aplicativo em [locale] no App Router. Armazene arquivos JSON de tradução em um diretório de mensagens na raiz do projeto.

Configuração de roteamento

Defina o roteamento com defineRouting() especificando sua matriz de localidades, localidade padrão e estratégia de prefixo de localidade. A estratégia "conforme necessário" omite o prefixo para o código de idioma padrão (inglês) enquanto adiciona prefixos /es/, /fr/, /ar/ para outros.

Crie wrappers de navegação com createNavigation(routing) para obter funções Link, useRouter, usePathname e redirecionamento com reconhecimento de localidade. Use-os em vez da navegação nativa Next.js em todo o seu aplicativo.

Configuração de middleware

No Next.js 16, crie um arquivo proxy.ts (substituindo o padrão middleware.ts antigo). Exporte uma função de proxy criada por createMiddleware(routing). Configure o matcher para excluir rotas de API, arquivos estáticos e caminhos _next.

---

Arquivos de tradução

Estrutura JSON (aninhada, não plana)

Use chaves aninhadas organizadas por namespace. Nunca use chaves planas separadas por pontos, como "home.title" - elas quebram a resolução do namespace next-intl. Estruture as traduções como:

• comum: termos compartilhados (botões, rótulos, estados de carregamento)
• nav: itens de navegação
• home: conteúdo da página inicial
• sobre: sobre o conteúdo da página
• admin.common: termos de administração compartilhados
• admin.products: página de gerenciamento de produtos

Componentes do servidor

Use getTranslations("namespace") em componentes de servidor assíncronos. Isso carrega as traduções no servidor sem impacto no pacote do cliente. Chame t("key") para traduções de strings, t.rich("key", { negrito: (chunks) => ... }) para rich text.

Componentes do cliente

Use o gancho useTranslations("namespace") nos componentes do cliente marcados com "use client". O gancho fornece a mesma função t(). Somente as traduções do namespace ativo são incluídas no pacote configurável do cliente.

---

Suporte RTL (da direita para a esquerda)

Para árabe, hebraico, urdu e outros idiomas RTL, defina dir="rtl" no elemento HTML com base na localidade atual. No layout de localidade, verifique se a localidade está em seu array rtlLocales e defina a direção de acordo.

Use as propriedades lógicas CSS do Tailwind (ps, pe, ms, me em vez de pl, pr, ml, mr) para layouts que mudam automaticamente no modo RTL. Carregue fontes apropriadas para scripts RTL (por exemplo, Noto Sans Arabic para árabe e urdu).

---

SEO: Metadados e Hreflang

Metadados Dinâmicos

Cada página deve usar generateMetadata() (nunca metadados const de exportação estática) para títulos, descrições e alternativas de hreflang com reconhecimento de localidade. Crie um objeto alternativos.languages ​​mapeando cada localidade para seu caminho de URL, além de uma entrada x-default apontando para a versão em inglês.

Mapa do site multilíngue

Gere entradas de mapa do site para cada página em cada localidade. Cada entrada deve incluir suplentes.idiomas mapeando todas as variantes de localidade. Isso permite que os mecanismos de pesquisa forneçam a versão no idioma correto em cada mercado.

Meta tag de idioma de conteúdo

Defina a meta tag do idioma do conteúdo em seu layout de localidade para ajudar os mecanismos de pesquisa e rastreadores de IA a identificar o idioma da página. Isto é especialmente importante para o Bing e os mecanismos de pesquisa de IA emergentes.

---

Fluxo de trabalho de tradução

1. Edite en.json como a única fonte de verdade para todas as strings traduzíveis
2. Execute o script de tradução para propagar novas chaves para todos os arquivos de localidade (usando a API do Google Translate ou DeepL para rascunhos iniciais)
3. Analise as traduções com falantes nativos quanto à qualidade e adequação cultural
4. Teste as linguagens RTL minuciosamente – verifique a inversão do layout, o alinhamento do texto e as entradas do formulário
5. Verifique o SEO com ferramentas de validação hreflang e segmentação internacional do Google Search Console

Tratamento de arquivos de tradução grandes

Para aplicativos com mais de 5.000 chaves de tradução, organize os arquivos JSON por namespace para melhorar a capacidade de manutenção. next-intl carrega apenas os namespaces necessários para a página atual, mantendo o desempenho ideal.

---

Considerações de desempenho

• Renderização do servidor: as traduções são carregadas no servidor. Nenhuma tradução JSON é enviada ao cliente, a menos que o componente seja um componente cliente.
• Divisão de namespace: apenas os namespaces ativos são carregados por página, não o arquivo de tradução inteiro.
• Geração estática: páginas que usam getTranslations() podem ser geradas estaticamente no momento da construção para todas as localidades.
• Tamanho do pacote: os componentes do cliente incluem apenas suas traduções de namespace. Uma página usando useTranslations("home") envia apenas o namespace "home".

---

Armadilhas Comuns

1. Chaves simples: Usar "home.title" como chave em vez de aninhado { "home": { "title": "..." } } quebra a resolução do namespace
2. Traduções ausentes: Sempre forneça um comportamento substituto - next-intl mostra o nome da chave se uma tradução estiver faltando, mas isso parece quebrado para os usuários
3. Strings codificados: Audite sua base de código para quaisquer strings fora do sistema de tradução
4. Formatação de data/número: Use formatadores next-intl em vez de toLocaleDateString() para comportamento consistente
5. Metadados estáticos: usar export const metadata em vez de generateMetadata() evita títulos e descrições com reconhecimento de localidade

---

Perguntas frequentes

P: Quantos locais o next-intl pode manipular?

Não há limite prático. Aplicativos com mais de 11 localidades e mais de 7.000 chaves de tradução são executados sem problemas de desempenho. A renderização no lado do servidor significa que as traduções não sobrecarregam os pacotes do cliente.

P: O i18n afeta o desempenho de carregamento da página?

Com componentes de servidor, o carregamento da tradução ocorre no servidor. O impacto no desempenho é insignificante. Os componentes do cliente incluem apenas suas traduções de namespace, normalmente alguns KB.

P: Como lidamos com o conteúdo dinâmico do banco de dados em vários idiomas?

O texto estático da UI usa arquivos JSON. O conteúdo do banco de dados (postagens de blog, descrições de produtos) requer o armazenamento de traduções em colunas ou tabelas dedicadas ou o uso de um CMS com fluxo de trabalho de tradução integrado. Algumas equipes usam um híbrido: JSON para UI, banco de dados para conteúdo.

P: E quanto à formatação de números e datas?

next-intl provides useFormatter() for locale-aware formatting of numbers, currencies, dates, and relative times. Toda a formatação segue o padrão internacional e respeita as convenções locais automaticamente.

---

O que vem a seguir

A internacionalização é um investimento que rende dividendos em todos os mercados não ingleses. Comece com suas localidades de maior valor e expanda a partir daí.

Entre em contato com a ECOSIRE para obter ajuda na implementação do i18n ou explore nossos serviços de implementação Odoo para implantação de ERP multilíngue.

---

Publicado pela ECOSIRE – ajudando empresas a escalar com soluções de software empresarial.