Internacionalize um site em React ou Next.js (next-intl) | We.Inc
Traduza um site em React ou Next.js do jeito certo: arquivos de mensagens, rotas por idioma com next-intl, formatação Intl para datas, valores e plurais, layouts da direita para a esquerda e tags hreflang.
Mantenha todos os textos em um arquivo JSON de mensagens por idioma, dê a cada idioma a própria URL, como /de/about, e formate datas, preços e plurais com as APIs Intl nativas do navegador. No App Router do Next.js, o next-intl junta tudo isso: um segmento de rota [locale], um proxy que escolhe o idioma e useTranslations nos componentes.
As partes de um site traduzido
Parte
O que usar
Textos
messages/en.json, messages/de.json e assim por diante
URLs
Um prefixo de caminho por idioma: /en/..., /de/...
Detecção de idioma
createMiddleware do next-intl em proxy.ts (middleware.ts antes do Next.js 16)
Datas, números, valores
Intl.DateTimeFormat e Intl.NumberFormat
Plurais
Sintaxe de mensagens ICU ou Intl.PluralRules
Mecanismos de busca
Links hreflang para cada versão de idioma, mais x-default
Traduzir é mais do que trocar palavras. A ordem das palavras muda, as regras de plural são diferentes, o árabe é lido da direita para a esquerda e cada país escreve datas do seu jeito. Use o seletor abaixo para ver um pequeno card de produto mudar de idioma e depois monte o mesmo no seu app com os arquivos de configuração e o gerador de hreflang.
Escolha um idioma na demonstração. O card troca as mensagens, formata o preço e a data para aquela localidade e inverte a direção no árabe.
Mude a quantidade de itens para ver cada idioma escolher a própria forma de plural.
Copie os arquivos de configuração do next-intl para um projeto com o App Router do Next.js.
Informe seu domínio e seus idiomas no gerador de hreflang e cole as tags, ou o objeto de metadata, no seu layout.
Nunca monte frases juntando pedaços. Traduza frases inteiras com placeholders como {count}, porque a ordem das palavras varia.
Deixe espaço no layout, porque um rótulo traduzido costuma ser bem mais longo que o original em inglês.
Defina lang no elemento html para cada idioma e dir="rtl" para os idiomas da direita para a esquerda.
Evite bandeiras nos seletores de idioma. Bandeiras representam países, e muitos idiomas são falados em vários deles.
Deixe as pessoas trocarem de idioma manualmente e lembre a escolha delas em vez de depender só das configurações do navegador.
Perguntas frequentes
Qual biblioteca de i18n devo usar com React?
Para o App Router do Next.js, o next-intl foi feito para isso e suporta Server Components. Para um app React sem Next.js, escolha uma biblioteca que guarde as mensagens em JSON, para que migrar para outra depois continue viável.
Os idiomas devem ficar em subpastas, subdomínios ou domínios separados?
Subpastas como example.com/de/ são as mais simples de manter, porque um único site e um único domínio carregam tudo. O next-intl também suporta rotas por domínio se você precisar de de.example.com ou de um domínio de país.
Como adiciono hreflang no Next.js?
Retorne alternates.languages a partir de metadata ou generateMetadata, com uma entrada por URL de idioma. O Next.js gera uma tag link rel="alternate" hreflang para cada uma. Cada versão de idioma precisa listar todas as outras e a si mesma, senão os mecanismos de busca podem ignorar o conjunto.
Posso traduzir meu site com tradução automática?
Você pode usar tradução automática como primeiro rascunho, mas peça a alguém fluente para revisar, principalmente títulos, preços e textos jurídicos. Traduções rasas ou sem revisão podem confundir os leitores e enfraquecer a confiança.
Mensagens, não textos dentro dos componentes
Todo texto que uma pessoa vê deve vir de um arquivo de mensagens com chaves pelo significado, como Cart.checkoutButton. Desenvolvedores editam o inglês, tradutores editam os outros arquivos e ninguém precisa caçar texto fixo nos componentes.
Separar por namespace de componente deixa os arquivos legíveis. O useTranslations('Cart') do next-intl então fornece t('checkoutButton') somente dentro daquele componente.
Deixe o Intl cuidar da formatação
O Intl.NumberFormat escreve 1234.5 euros como 1.234,50 € para um leitor alemão, com o símbolo e os separadores no lugar que aquela localidade espera. O Intl.DateTimeFormat faz o mesmo para datas, e o Intl.PluralRules diz se um número usa a forma one, few, many ou other em um idioma.
Essas APIs vêm em todo navegador moderno e no Node, então a formatação não adiciona peso ao seu bundle e continua correta para idiomas que você nunca estudou.
Idiomas da direita para a esquerda
Árabe, hebraico, persa e urdu são lidos da direita para a esquerda. Definir dir="rtl" no elemento html espelha o alinhamento do texto e a ordem do conteúdo inline, mas valores fixos de left e right no CSS continuam onde estão.
Use propriedades lógicas como margin-inline-start e padding-inline-end, ou os utilitários ms- e pe- do Tailwind, para que o espaçamento se inverta automaticamente com a direção.
Configuração do next-intl para o App Router
Instale com npm install next-intl. Estes arquivos seguem a estrutura do próprio guia de primeiros passos do next-intl para rotas por idioma.
Um arquivo por idioma, com as mesmas chaves em cada um. A sintaxe ICU cuida dos plurais dentro da mensagem.
src/i18n/routing.ts e src/proxy.ts
O routing lista suas localidades uma vez. O proxy (chamado middleware.ts antes do Next.js 16) redireciona os visitantes para um prefixo de idioma.
src/i18n/request.ts
Lê a localidade do segmento [locale], rejeita as desconhecidas e carrega as mensagens daquele idioma.
next.config.ts, layout e uma página
O plugin conecta o request.ts. Mova suas páginas para app/[locale]/ e leia as mensagens com useTranslations. next/root-params vem ativado por padrão a partir do Next.js 16.3; versões anteriores precisam de experimental.rootParams.
Formatação sem biblioteca
Intl em JavaScript puro
Funciona em qualquer app React, traduzido ou não.
Regras de hreflang que os mecanismos de busca verificam
Acertando as anotações de idioma
Regra
Exemplo
Use URLs absolutas completas
Cada versão lista a si mesma e todas as outras
A página em alemão aponta para en, de, ar e x-default
Idioma em ISO 639-1, região opcional em ISO 3166-1 alpha-2
de, en-GB, pt-BR
Nunca só a região
be é bielorrusso, não Bélgica; use nl-BE ou fr-BE
x-default para todos os outros
Aponta para um seletor de idioma ou para sua versão principal
Experimente: um card em cinco idiomas
Troque o idioma e mude a quantidade de itens. Os textos vêm de um objeto de mensagens, e o preço, a data e a forma de plural vêm das APIs Intl do navegador.
Idioma
Itens no carrinho: {n}
Categoria de plural escolhida:
Direção:
A demonstração não converte moedas; ela só formata o mesmo número.
Gerador de hreflang
Informe seu domínio, o caminho de uma página e seus códigos de idioma para obter as tags link do head, ou o objeto alternates do Next.js.
Domínio
Caminho da página
Códigos de idioma (separados por vírgula)
Idioma x-default
Códigos inválidos ignorados: {codes}. Use um formato como de ou en-GB.