Faça sua pergunta e obtenha um resumo do documento referenciando esta página e o provedor AI de sua escolha
Histórico de versões
- Versão inicialv7.0.001/11/2025
O conteúdo desta página foi traduzido com uma IA.
Veja a última versão do conteúdo original em inglêsSe você tiver uma ideia para melhorar esta documentação, sinta-se à vontade para contribuir enviando uma pull request no GitHub.
Link do GitHub para a documentaçãoCopiar o Markdown do documento para a área de transferência
Como internacionalizar sua aplicação Next.js usando next-intl em 2026
Índice
O que é next-intl?
next-intl é uma biblioteca popular de internacionalização (i18n) projetada especificamente para o Next.js App Router. Ela oferece uma forma integrada de construir aplicações Next.js multilíngues com excelente suporte a TypeScript e otimizações embutidas.
Se preferir, você também pode consultar o guia do next-i18next, ou usar diretamente o Intlayer.
Veja a comparação em next-i18next vs next-intl vs Intlayer.
Práticas que você deve seguir
Antes de mergulharmos na implementação, aqui estão algumas práticas que você deve seguir:
- Defina os atributos HTML
langedir
No seu layout, calculedirusandogetLocaleDirection(locale)e defina<html lang={locale} dir={dir}>para garantir acessibilidade adequada e SEO. - Separe as mensagens por namespace
Organize os arquivos JSON por locale e namespace (por exemplo,common.json,about.json) para carregar apenas o que você precisa. - Minimize o payload no cliente
Nas páginas, envie apenas os namespaces necessários para oNextIntlClientProvider(por exemplo,pick(messages, ['common', 'about'])). - Prefira páginas estáticas
Use páginas estáticas sempre que possível para melhor desempenho e SEO. - I18n em componentes de servidor
Componentes de servidor, como páginas ou todos os componentes não marcados comoclient, são estáticos e podem ser pré-renderizados em tempo de build. Portanto, teremos que passar as funções de tradução para eles como props. - Configure os tipos TypeScript
Para seus locales, a fim de garantir a segurança de tipos em toda a sua aplicação. - Proxy para redirecionamento
Use um proxy para lidar com a detecção de locale e roteamento, redirecionando o usuário para a URL apropriada com prefixo de locale. - Internacionalização dos seus metadados, sitemap, robots.txt
Internacionalize seus metadados, sitemap, robots.txt usando a funçãogenerateMetadatafornecida pelo Next.js para garantir uma melhor descoberta pelos motores de busca em todos os locales. - Localize os Links
Localize os Links usando o componente Link para redirecionar o usuário para a URL apropriada com prefixo de locale. É importante garantir a descoberta das suas páginas em todos os locales.
- Automatize testes e traduções
Automatizar testes e traduções ajuda a economizar tempo na manutenção da sua aplicação multilíngue.
Veja nossa documentação listando tudo que você precisa saber sobre internacionalização e SEO: Internationalization (i18n) with next-intl.
Guia Passo a Passo para Configurar o next-intl em uma Aplicação Next.js
Veja o Template da Aplicação no GitHub.
Aqui está a estrutura do projeto que iremos criar:
Copiar o código para a área de transferência
Instalar Dependências
Instale os pacotes necessários usando npm:
bashCopiar códigoCopiar o código para a área de transferência
- next-intl: A biblioteca principal de internacionalização para o Next.js App Router que fornece hooks, funções no servidor e provedores no cliente para gerenciar traduções.
Configure seu Projeto
Crie um arquivo de configuração que defina os seus locales suportados e configure a request do next-intl. Este arquivo serve como a fonte única de verdade para a sua configuração i18n e garante segurança de tipos em toda a sua aplicação.
Centralizar a configuração dos seus locales previne inconsistências e facilita a adição ou remoção de locales no futuro. A função
getRequestConfigé executada em cada requisição e carrega apenas as traduções necessárias para cada página, permitindo code-splitting e reduzindo o tamanho do bundle.src/i18n.tsCopiar códigoCopiar o código para a área de transferência
Definir Rotas Dinâmicas por Locale
Configure o roteamento dinâmico para locais criando um diretório
[locale]na sua pasta de app. Isso permite que o Next.js gerencie o roteamento baseado em localidade, onde cada localidade se torna um segmento da URL (por exemplo,/en/about,/fr/about).Usar rotas dinâmicas permite que o Next.js gere páginas estáticas para todas as localidades no momento da build, melhorando o desempenho e SEO. O componente de layout define os atributos HTML
langedircom base na localidade, o que é crucial para acessibilidade e compreensão pelos motores de busca.src/app/[locale]/layout.tsxCopiar códigoCopiar o código para a área de transferência
src/app/[locale]/about/page.tsxCopiar códigoCopiar o código para a área de transferência
Crie Seus Arquivos de Tradução
Crie arquivos JSON para cada locale e namespace. Essa estrutura permite organizar as traduções de forma lógica e carregar apenas o que você precisa para cada página.
Organizar as traduções por namespace (por exemplo,
common.json,about.json) possibilita o code splitting e reduz o tamanho do bundle. Você carrega apenas as traduções necessárias para cada página, melhorando a performance.locales/en/common.jsonCopiar códigoCopiar o código para a área de transferência
locales/fr/common.jsonCopiar códigoCopiar o código para a área de transferência
locales/en/about.jsonCopiar códigoCopiar o código para a área de transferência
locales/fr/about.jsonCopiar códigoCopiar o código para a área de transferência
Utilize as Traduções nas Suas Páginas
Crie um componente de página que carregue as traduções no servidor e as passe para componentes tanto do servidor quanto do cliente. Isso garante que as traduções sejam carregadas antes da renderização e evita o flashing de conteúdo.
O carregamento das traduções no lado do servidor melhora o SEO e previne o FOUC (Flash of Untranslated Content). Ao usar
pickpara enviar apenas os namespaces necessários para o provedor do cliente, minimizamos o bundle de JavaScript enviado para o navegador.src/app/[locale]/about/page.tsxCopiar códigoCopiar o código para a área de transferência
Usar Traduções em Componentes Client
Componentes client podem usar os hooks
useTranslationseuseFormatterpara acessar traduções e funções de formatação. Esses hooks leem do contextoNextIntlClientProvider.Componentes client precisam de hooks do React para acessar traduções. Os hooks
useTranslationseuseFormatterse integram perfeitamente com o next-intl e fornecem atualizações reativas quando o locale muda.Não esqueça de adicionar os namespaces necessários às mensagens client da página (inclua apenas os namespaces que seus componentes client realmente precisam).
src/components/ClientComponent.tsxCopiar códigoCopiar o código para a área de transferência
Usar Traduções em Componentes de Servidor
Componentes de servidor não podem usar hooks do React, então eles recebem traduções e formatadores via props de seus componentes pai. Essa abordagem mantém os componentes de servidor síncronos e permite que eles sejam aninhados dentro de componentes cliente.
Componentes server que podem estar aninhados sob limites de componentes client precisam ser síncronos. Ao passar strings traduzidas e valores formatados como props, evitamos operações assíncronas e garantimos a renderização adequada. Pré-compute traduções e formatações no componente pai da página.
src/components/ServerComponent.tsxCopiar códigoCopiar o código para a área de transferência
Na sua página/layout, use
getTranslationsegetFormatterdenext-intl/serverpara pré-calcular traduções e formatações, e então passe-os como props para os componentes de servidor.Mude o idioma do seu conteúdo
OpcionalPara mudar o idioma do seu conteúdo com next-intl, renderize links sensíveis ao locale que apontam para o mesmo pathname enquanto troca o locale. O provider reescreve as URLs automaticamente, então você só precisa direcionar para a rota atual.
src/components/LocaleSwitcher.tsxCopiar códigoCopiar o código para a área de transferência
Use o componente Link localizado
OpcionalO
next-intlfornece um subpacotenext-intl/navigationque contém um componente Link localizado que aplica automaticamente a localidade ativa. Já o extraímos para você no arquivo@/i18n, então você pode usá-lo assim:src/components/MyComponent.tsxCopiar códigoCopiar o código para a área de transferência
Acesse a localidade ativa dentro das Server Actions
OpcionalAs Server Actions podem ler a localidade atual usando
next-intl/server. Isso é útil para enviar e-mails localizados ou armazenar preferências de idioma junto com os dados enviados.src/app/actions/get-current-locale.tsCopiar códigoCopiar o código para a área de transferência
getLocalelê o locale definido pelo proxy donext-intl, então funciona em qualquer lugar no servidor: Route Handlers, Server Actions e edge functions.Internacionalize seus Metadados
OpcionalTraduzir conteúdo é importante, mas o objetivo principal da internacionalização é tornar seu site mais visível para o mundo. I18n é uma alavanca incrível para melhorar a visibilidade do seu site por meio de SEO adequado.
Metadados internacionalizados corretamente ajudam os mecanismos de busca a entender quais idiomas estão disponíveis em suas páginas. Isso inclui configurar meta tags hreflang, traduzir títulos e descrições, e garantir que URLs canônicas estejam corretamente definidas para cada localidade.
src/app/[locale]/about/layout.tsxCopiar códigoCopiar o código para a área de transferência
Internacionalize Seu Sitemap
OpcionalGere um sitemap que inclua todas as versões locais das suas páginas. Isso ajuda os motores de busca a descobrir e indexar todas as versões linguísticas do seu conteúdo.
Um sitemap devidamente internacionalizado garante que os motores de busca possam encontrar e indexar todas as versões linguísticas das suas páginas. Isso melhora a visibilidade nos resultados de busca internacionais.
src/app/sitemap.tsCopiar códigoCopiar o código para a área de transferência
Internacionalize seu robots.txt
OpcionalCrie um arquivo robots.txt que gerencie corretamente todas as versões de locale das suas rotas protegidas. Isso garante que os motores de busca não indexem páginas de administração ou dashboard em nenhum idioma.
Configurar corretamente o robots.txt para todos os locales impede que motores de busca indexem páginas sensíveis quando suas rotas são diferentes para cada locale.
src/app/robots.tsCopiar códigoCopiar o código para a área de transferência
Configurar Proxy para Roteamento de Locale
OpcionalCrie um proxy para detectar automaticamente o locale preferido do usuário e redirecioná-lo para a URL apropriada com prefixo de locale. O next-intl fornece uma função proxy conveniente que faz isso automaticamente.
O proxy garante que os usuários sejam automaticamente redirecionados para o idioma preferido ao visitarem seu site. Ele também salva a preferência do usuário para visitas futuras, melhorando a experiência do usuário.
src/proxy.tsCopiar códigoCopiar o código para a área de transferência
Configurar Tipos TypeScript para o Locale
OpcionalConfigurar o TypeScript ajudará você a obter autocompletar e segurança de tipos para suas chaves.
Para isso, você pode criar um arquivo global.ts na raiz do seu projeto e adicionar o seguinte código:
global.tsCopiar códigoCopiar o código para a área de transferência
Este código usará Module Augmentation para adicionar os locales e mensagens ao tipo AppConfig do next-intl.
Automatize Suas Traduções Usando Intlayer
OpcionalIntlayer é uma biblioteca gratuita e open-source projetada para auxiliar o processo de localização na sua aplicação. Enquanto o next-intl gerencia o carregamento e a gestão das traduções, o Intlayer ajuda a automatizar o fluxo de trabalho das traduções.
Gerenciar traduções manualmente pode ser demorado e sujeito a erros. O Intlayer automatiza os testes, a geração e a gestão das traduções, economizando seu tempo e garantindo consistência em toda a sua aplicação.
O Intlayer permite que você:
Declare seu conteúdo onde quiser na sua base de código
O Intlayer permite declarar seu conteúdo onde quiser na sua base de código usando arquivos.content.{ts|js|json}. Isso possibilita uma melhor organização do seu conteúdo, garantindo melhor legibilidade e manutenção da sua base de código.Teste traduções faltantes Intlayer fornece funções de teste que podem ser integradas no seu pipeline CI/CD ou nos seus testes unitários. Saiba mais sobre testar suas traduções.
Automatize suas traduções, Intlayer fornece uma CLI e uma extensão para VSCode para automatizar suas traduções. Pode ser integrado no seu pipeline CI/CD. Saiba mais sobre automatizar suas traduções. Você pode usar sua própria chave de API e o provedor de IA de sua escolha. Também oferece traduções contextuais, veja preencher conteúdo.
Conectar conteúdo externo Intlayer permite que você conecte seu conteúdo a um sistema externo de gerenciamento de conteúdo (CMS). Para buscá-lo de forma otimizada e inseri-lo em seus recursos JSON. Saiba mais sobre busca de conteúdo externo.
Editor visual
Intlayer oferece um editor visual gratuito para editar seu conteúdo usando um editor visual. Saiba mais sobre edição visual das suas traduções.
E mais. Para descobrir todos os recursos fornecidos pelo Intlayer, consulte a documentação sobre o interesse do Intlayer.
Comentários
Ainda sem comentários. Seja o primeiro a compartilhar seus pensamentos.