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.

Para entender de onde vêm essas bibliotecas, leia a história do i18n em JavaScript.

O que o benchmark diz sobre next-intl no Next.js

Antes de implementar as traduções, é essencial entender o perfil de performance do next-intl. O benchmark i18n avalia a mesma aplicação Next.js de 10 páginas e 10 locales em diferentes configurações e bibliotecas, para medir o peso real do bundle, o vazamento de strings e o custo de hydration.

Números-chave do next-intl no Next.js (gzip):

O que levar em conta:

• Evite catálogos de mensagens globais: em configurações padrão, onde todas as mensagens são carregadas nos layouts raiz, ~89.8% do conteúdo traduzido enviado ao navegador pertence a outras páginas. Usar pick(messages, ['namespace']) por rota elimina esse vazamento, embora exija manutenção manual.
• Peso do runtime: o runtime do next-intl adiciona ~14.7 KB gzip a cada página. Para apps next-intl existentes, o adaptador de compatibilidade @intlayer/next-intl mantém os mesmos hooks (useTranslations, useFormatter, etc.) e reduz o runtime para ~8.0 KB com 0% de vazamento. O next-intlayer nativo reduz ainda mais o peso, para 5.5 KB.

Veja todos os dados: relatório do benchmark Next.js, e o repositório do benchmark.

Comparação de funcionalidades no Next.js

Como o next-intl se compara ao next-i18next e ao Intlayer nas funcionalidades de que um projeto Next.js App Router normalmente precisa:

Os tamanhos de runtime vêm do benchmark Next.js. Para uma discussão detalhada, leia 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 lang e dir
  No seu layout, calcule dir usando getLocaleDirection(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 o NextIntlClientProvider (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 como client, 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ção generateMetadata fornecida 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:

.
├── global.ts
├── locales
│   ├── en
│   │  ├── common.json
│   │  └── about.json
│   ├── fr
│   │  ├── common.json
│   │  └── about.json
│   └── es
│      ├── common.json
│      └── about.json
└── src # Src é opcional
    ├── proxy.ts
    ├── app
    │   ├── i18n.ts
    │   └── [locale]
    │       ├── layout.tsx
    │       ├── (home) # / (Grupo de Rotas para não poluir todas as páginas com recursos da home)
    │       │   ├── layout.tsx
    │       │   └── page.tsx
    │       └── about # /about
    │           ├── layout.tsx
    │           └── page.tsx
    └── components
        ├── ClientComponent.tsx
        └── ServerComponent.tsx

1. 1

   Instalar Dependências

   Instale os pacotes necessários usando npm:

   bash

   Copiar conteúdo

   Copiar código

   Copiar o código para a área de transferência

   npm install next-intl
   

   • 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.
2. 2

   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.ts

   Copiar conteúdo

   Copiar código

   Copiar o código para a área de transferência

   import { notFound } from "next/navigation";
   import createMiddleware from "next-intl/middleware";
   import { createNavigation } from "next-intl/navigation";
   
   // Define os locales suportados com segurança de tipos
   export const locales = ["en", "fr", "es"] as const;
   export type Locale = (typeof locales)[number];
   export const defaultLocale: Locale = "en";
   
   export function isRTL(locale: Locale | (string & {})) {
     // Verifica se o locale é de um idioma que é escrito da direita para a esquerda
     return /^(ar|fa|he|iw|ur|ps|sd|ug|yi|ckb|ku)(-|$)/i.test(locale);
   }
   
   // Carrega mensagens dinamicamente por locale para permitir code-splitting
   // Promise.all carrega namespaces em paralelo para melhor performance
   async function loadMessages(locale: Locale) {
     // Carrega apenas os namespaces que seu layout/páginas precisam
     const [common, home, about] = await Promise.all([
       import(`../locales/${locale}/common.json`).then((m) => m.default),
       import(`../locales/${locale}/home.json`).then((m) => m.default),
       import(`../locales/${locale}/about.json`).then((m) => m.default),
       // ... Arquivos JSON futuros devem ser adicionados aqui
     ]);
   
     return { common, home, about } as const;
   }
   
   // Auxiliar para gerar URLs localizadas (exemplo: /about vs /fr/about)
   export function localizedPath(locale: string, path: string) {
     return locale === defaultLocale ? path : `/${locale}${path}`;
   }
   
   // getRequestConfig é executado a cada requisição e fornece mensagens para componentes do servidor
   // É aqui que o next-intl se conecta ao server-side rendering do Next.js
   export default async function getRequestConfig({
     requestLocale,
   }: {
     requestLocale: Promise<string | undefined>;
   }) {
     const requested: Locale = ((await requestLocale) as Locale) ?? defaultLocale;
   
     if (!locales.includes(requested)) notFound();
   
     return {
       locale: requested,
       messages: await loadMessages(requested),
     };
   }
   
   export function getCookie(locale: Locale) {
     return [
       `NEXT_LOCALE=${locale}`,
       "Path=/",
       `Max-Age=${60 * 60 * 24 * 365}`, // 1 ano
       "SameSite=Lax",
     ].join("; ");
   }
   
   const routingOptions = {
     locales,
     defaultLocale,
     localePrefix: "as-needed", // Altera rota /en/... para /...
     // Opcional: caminhos localizados
     // pathnames: {
     //   '/': '/',
     //   '/about': {en: '/about', fr: '/a-propos', es: '/acerca-de'},
     //   '/blog/[slug]': '/blog/[slug]'
     // }
     //  localeDetection: true, // previne redirecionamentos de "/" para "/en" via cookie
   } as const;
   
   export const { Link, redirect, usePathname, useRouter, getPathname } =
     createNavigation(routingOptions);
   
   export const proxy = createMiddleware(routingOptions);
   

3. 3

   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 lang e dir com base na localidade, o que é crucial para acessibilidade e compreensão pelos motores de busca.

   src/app/[locale]/layout.tsx

   Copiar conteúdo

   Copiar código

   Copiar o código para a área de transferência

   import type { ReactNode } from "react";
   import { locales } from "@/i18n";
   import { getLocaleDirection, setRequestLocale } from "next-intl/server";
   
   // Pré-gerar páginas estáticas para todas as localidades no momento da build (SSG)
   // Isso melhora o desempenho e SEO
   export function generateStaticParams() {
     return locales.map((locale) => ({ locale }));
   }
   
   export default function LocaleLayout({
     children,
     params,
   }: {
     children: ReactNode;
     params: Promise<{ locale: string }>;
   }) {
     // No Next.js App Router, params é uma Promise (pode ser await'd)
     // Isso permite que segmentos de rota dinâmicos sejam resolvidos assincronamente
     const { locale } = await params;
   
     // Crítico: setRequestLocale informa ao next-intl qual locale usar para esta requisição
     // Sem isso, getTranslations() não saberá qual locale usar nos componentes do servidor
     setRequestLocale(locale);
   
     // Obtém a direção do texto (LTR/RTL) para renderização HTML correta
     const dir = getLocaleDirection(locale);
   
     return (
       <html lang={locale} dir={dir}>
         <body>{children}</body>
       </html>
     );
   }
   

   src/app/[locale]/about/page.tsx

   Copiar conteúdo

   Copiar código

   Copiar o código para a área de transferência

   import { getTranslations, getMessages, getFormatter } from "next-intl/server";
   import { NextIntlClientProvider } from "next-intl";
   import pick from "lodash/pick";
   import ServerComponent from "@/components/ServerComponent";
   import ClientComponent from "@/components/ClientComponent";
   
   export default async function AboutPage({
     params,
   }: {
     params: Promise<{ locale: string }>;
   }) {
     const { locale } = await params;
   
     // As mensagens são carregadas no lado do servidor. Envie apenas o que é necessário para o cliente.
     // Isso minimiza o pacote JavaScript enviado para o navegador
     const messages = await getMessages();
     const clientMessages = pick(messages, ["common", "about"]);
   
     // Traduções/formatações estritamente do lado do servidor
     // Estes são executados no servidor e podem ser passados como props para os componentes
     const tAbout = await getTranslations("about");
     const tCounter = await getTranslations("about.counter");
     const format = await getFormatter();
   
     const initialFormattedCount = format.number(0);
   
     return (
       // NextIntlClientProvider torna as traduções disponíveis para os componentes cliente
       // Passe apenas os namespaces que seus componentes cliente realmente usam
       <NextIntlClientProvider locale={locale} messages={clientMessages}>
         <main>
           <h1>{tAbout("title")}</h1>
           <ClientComponent />
           <ServerComponent
             formattedCount={initialFormattedCount}
             label={tCounter("label")}
             increment={tCounter("increment")}
           />
         </main>
       </NextIntlClientProvider>
     );
   }
   

4. 4

   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.

   InglêsFrancês

   locales/en/common.json

   Copiar conteúdo

   Copiar código

   Copiar o código para a área de transferência

   {
     "welcome": "Welcome",
     "greeting": "Hello, world!"
   }
   

   locales/fr/common.json

   Copiar conteúdo

   Copiar código

   Copiar o código para a área de transferência

   {
     "welcome": "Bienvenue",
     "greeting": "Bonjour le monde!"
   }
   

   InglêsFrancês

   locales/en/about.json

   Copiar conteúdo

   Copiar código

   Copiar o código para a área de transferência

   {
     "title": "About",
     "description": "About page description",
     "counter": {
       "label": "Counter",
       "increment": "Increment"
     }
   }
   

   locales/fr/about.json

   Copiar conteúdo

   Copiar código

   Copiar o código para a área de transferência

   {
     "title": "À propos",
     "description": "Description de la page À propos",
     "counter": {
       "label": "Compteur",
       "increment": "Incrémenter"
     }
   }
   

5. 5

   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 pick para 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.tsx

   Copiar conteúdo

   Copiar código

   Copiar o código para a área de transferência

   import { getTranslations, getMessages, getFormatter } from "next-intl/server";
   import { NextIntlClientProvider } from "next-intl";
   import pick from "lodash/pick";
   import ServerComponent from "@/components/ServerComponent";
   import ClientComponent from "@/components/ClientComponent";
   
   export default async function AboutPage({
     params,
   }: {
     params: Promise<{ locale: string }>;
   }) {
     const { locale } = await params;
   
     // As mensagens são carregadas no lado do servidor. Envie apenas o que é necessário para o cliente.
     // Isso minimiza o pacote JavaScript enviado para o navegador
     const messages = await getMessages();
     const clientMessages = pick(messages, ["common", "about"]);
   
     // Traduções/formatações estritamente do lado do servidor
     // Estas são executadas no servidor e podem ser passadas como props para os componentes
     const tAbout = await getTranslations("about");
     const tCounter = await getTranslations("about.counter");
     const format = await getFormatter();
   
     const initialFormattedCount = format.number(0);
   
     return (
       // NextIntlClientProvider disponibiliza traduções para componentes client
       // Passe apenas os namespaces que seus componentes client realmente usam
       <NextIntlClientProvider locale={locale} messages={clientMessages}>
         <main>
           <h1>{tAbout("title")}</h1>
           <ClientComponent />
           <ServerComponent
             formattedCount={initialFormattedCount}
             label={tCounter("label")}
             increment={tCounter("increment")}
           />
         </main>
       </NextIntlClientProvider>
     );
   }
   

6. 6

   Usar Traduções em Componentes Client

   Componentes client podem usar os hooks useTranslations e useFormatter para acessar traduções e funções de formatação. Esses hooks leem do contexto NextIntlClientProvider.

   Componentes client precisam de hooks do React para acessar traduções. Os hooks useTranslations e useFormatter se 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.tsx

   Copiar conteúdo

   Copiar código

   Copiar o código para a área de transferência

   "use client";
   
   import React, { useState } from "react";
   import { useTranslations, useFormatter } from "next-intl";
   
   const ClientComponent = () => {
     // Escopo diretamente para o objeto aninhado
     // useTranslations/useFormatter são hooks que leem do contexto NextIntlClientProvider
     // Eles só funcionam se o componente estiver envolvido pelo NextIntlClientProvider
     const t = useTranslations("about.counter");
     const format = useFormatter();
     const [count, setCount] = useState(0);
   
     return (
       <div>
         <p>{format.number(count)}</p>
         <button
           aria-label={t("label")}
           onClick={() => setCount((count) => count + 1)}
         >
           {t("increment")}
         </button>
       </div>
     );
   };
   

7. 7

   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.tsx

   Copiar conteúdo

   Copiar código

   Copiar o código para a área de transferência

   // Componentes server aninhados dentro de componentes client devem ser síncronos
   // O React não consegue serializar funções assíncronas através da fronteira server/client
   // Solução: pré-computar traduções/formatações no componente pai e passar como props
   type ServerComponentProps = {
     formattedCount: string;
     label: string;
     increment: string;
   };
   
   const ServerComponent = ({
     formattedCount,
     label,
     increment,
   }: ServerComponentProps) => {
     return (
       <div>
         <p>{formattedCount}</p>
         <button aria-label={label}>{increment}</button>
       </div>
     );
   };
   

   Na sua página/layout, use getTranslations e getFormatter de next-intl/server para pré-calcular traduções e formatações, e então passe-os como props para os componentes de servidor.

8. 8

   Mude o idioma do seu conteúdo

   Opcional

   Para 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.tsx

   Copiar conteúdo

   Copiar código

   Copiar o código para a área de transferência

   "use client";
   
   import Link from "next/link";
   import { usePathname } from "next/navigation";
   import { useLocale } from "next-intl";
   import { defaultLocale, getCookie, type Locale, locales } from "@/i18n";
   
   const getLocaleLabel = (locale: Locale): string => {
     try {
       const displayNames = new Intl.DisplayNames([locale], { type: "language" });
       return displayNames.of(locale) ?? locale.toUpperCase();
     } catch {
       return locale.toUpperCase();
     }
   };
   
   const localeFlags: Record<Locale, string> = {
     en: "🇬🇧",
     fr: "🇫🇷",
     es: "🇪🇸",
   };
   
   export default function LocaleSwitcher() {
     const activeLocale = useLocale();
     const pathname = usePathname();
   
     // Remove o prefixo do locale do pathname para obter o caminho base
     const getBasePath = (path: string) => {
       for (const locale of locales) {
         if (path.startsWith(`/${locale}`)) {
           return path.slice(locale.length + 1) || "/";
         }
       }
       return path;
     };
   
     const basePath = getBasePath(pathname);
   
     return (
       <nav aria-label="Seletor de idioma">
         <div>
           {(locales as readonly Locale[]).map((locale) => {
             const isActive = locale === activeLocale;
             // Construir o href baseado em se é o locale padrão
             const href =
               locale === defaultLocale ? basePath : `/${locale}${basePath}`;
             return (
               <Link
                 key={locale}
                 href={href}
                 aria-current={isActive ? "page" : undefined}
                 onClick={() => {
                   document.cookie = getCookie(locale);
                 }}
               >
                 <span>{localeFlags[locale]}</span>
                 <span>{getLocaleLabel(locale)}</span>
                 <span>{locale.toUpperCase()}</span>
               </Link>
             );
           })}
         </div>
       </nav>
     );
   }
   

9. 9

   Use o componente Link localizado

   Opcional

   O next-intl fornece um subpacote next-intl/navigation que 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.tsx

   Copiar conteúdo

   Copiar código

   Copiar o código para a área de transferência

   import { Link } from "@/i18n";
   
   return <Link href="/about">t("about.title")</Link>;
   

10. 10

    Acesse a localidade ativa dentro das Server Actions

    Opcional

    As 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.ts

    Copiar conteúdo

    Copiar código

    Copiar o código para a área de transferência

    "use server";
    
    import { getLocale } from "next-intl/server";
    
    export async function getCurrentLocale() {
      return getLocale();
    }
    
    export async function handleContactForm(formData: FormData) {
      const locale = await getCurrentLocale();
    
      // Use o locale para selecionar templates, rótulos de analytics, etc.
      console.log(`Formulário de contato recebido do locale ${locale}`);
    }
    

    getLocale lê o locale definido pelo proxy do next-intl, então funciona em qualquer lugar no servidor: Route Handlers, Server Actions e edge functions.

11. 11

    Internacionalize seus Metadados

    Opcional

    Traduzir 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.tsx

    Copiar conteúdo

    Copiar código

    Copiar o código para a área de transferência

    import type { Metadata } from "next";
    import { locales, defaultLocale, localizedPath } from "@/i18n";
    import { getTranslations } from "next-intl/server";
    
    // generateMetadata é executado para cada localidade, gerando metadados amigáveis para SEO
    // Isso ajuda os motores de busca a entender versões alternativas de idioma
    export async function generateMetadata({
      params,
    }: {
      params: { locale: string };
    }): Promise<Metadata> {
      const { locale } = params;
      const t = await getTranslations({ locale, namespace: "about" });
    
      const url = "/about";
      const languages = Object.fromEntries(
        locales.map((locale) => [locale, localizedPath(locale, url)])
      );
    
      return {
        title: t("title"),
        description: t("description"),
        alternates: {
          canonical: localizedPath(locale, url),
          languages: { ...languages, "x-default": url },
        },
      };
    }
    
    // ... Resto do código da página
    

12. 12

    Internacionalize Seu Sitemap

    Opcional

    Gere 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.ts

    Copiar conteúdo

    Copiar código

    Copiar o código para a área de transferência

    import type { MetadataRoute } from "next";
    import { defaultLocale, locales } from "@/i18n";
    
    const origin = "https://example.com";
    
    const formatterLocalizedPath = (locale: string, path: string) =>
      locale === defaultLocale ? `${origin}${path}` : `${origin}/${locale}${path}`;
    
    /**
     * Obter um mapa de todos os locais e seus caminhos localizados
     *
     * Exemplo de saída:
     * {
     *   "en": "https://example.com",
     *   "fr": "https://example.com/fr",
     *   "es": "https://example.com/es",
     *   "x-default": "https://example.com"
     * }
     */
    const getLocalizedMap = (path: string) =>
      Object.fromEntries([
        ...locales.map((locale) => [locale, formatterLocalizedPath(locale, path)]),
        ["x-default", formatterLocalizedPath(defaultLocale, path)],
      ]);
    
    // Gerar sitemap com todas as variantes de locale para melhor SEO
    // O campo alternates informa aos motores de busca sobre as versões de idioma
    export default function sitemap(): MetadataRoute.Sitemap {
      return [
        {
          url: formatterLocalizedPath(defaultLocale, "/"),
          lastModified: new Date(),
          changeFrequency: "monthly",
          priority: 1.0,
          alternates: { languages: getLocalizedMap("/") },
        },
        {
          url: formatterLocalizedPath(defaultLocale, "/about"),
          lastModified: new Date(),
          changeFrequency: "monthly",
          priority: 0.7,
          alternates: { languages: getLocalizedMap("/about") },
        },
      ];
    }
    

13. 13

    Internacionalize seu robots.txt

    Opcional

    Crie 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.ts

    Copiar conteúdo

    Copiar código

    Copiar o código para a área de transferência

    import type { MetadataRoute } from "next";
    import { locales, defaultLocale } from "@/i18n";
    
    const origin = "https://example.com";
    // Gera caminhos para todos os locales (ex: /admin, /fr/admin, /es/admin)
    const withAllLocales = (path: string) => [
      path,
      ...locales
        .filter((locale) => locale !== defaultLocale)
        .map((locale) => "/" + locale + path),
    ];
    
    export default function robots(): MetadataRoute.Robots {
      const disallow = [
        ...withAllLocales("/dashboard"),
        ...withAllLocales("/admin"),
      ];
    
      return {
        rules: { userAgent: "*", allow: ["/"], disallow },
        host: origin,
        sitemap: origin + "/sitemap.xml",
      };
    }
    

14. 14

    Configurar Proxy para Roteamento de Locale

    Opcional

    Crie 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.ts

    Copiar conteúdo

    Copiar código

    Copiar o código para a área de transferência

    import { proxy } from "@/i18n";
    
    // Middleware executa antes das rotas, lidando com a detecção e roteamento do locale
    // localeDetection: true usa o cabeçalho Accept-Language para auto detectar o locale
    export default proxy;
    
    export const config = {
      // Ignorar API, internos do Next e assets estáticos
      // Regex: corresponde a todas as rotas exceto as que começam com api, _next, ou que contenham um ponto (arquivos)
      matcher: ["/((?!api|_next|.*\\..*).*)"],
    };
    

15. 15

    Configurar Tipos TypeScript para o Locale

    Opcional

    Configurar 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.ts

    Copiar conteúdo

    Copiar código

    Copiar o código para a área de transferência

    import type { locales } from "@/i18n";
    
    type Messages = {
      common: typeof import("./locales/en/common.json");
      home: typeof import("./locales/en/home.json");
      about: typeof import("./locales/en/about.json");
      // ... Arquivos JSON futuros também devem ser adicionados aqui
    };
    
    declare module "next-intl" {
      interface AppConfig {
        Locale: (typeof locales)[number];
        Messages: Messages;
      }
    }
    

    Este código usará Module Augmentation para adicionar os locales e mensagens ao tipo AppConfig do next-intl.

16. 16

    Automatize Suas Traduções Usando Intlayer

    Opcional

    Intlayer é 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.

    documentação sobre o interesse do Intlayer

    Para benchmarks de performance e comparações detalhados, veja:

    Relatório do benchmark Next.js

    Suíte de benchmarks i18n

    next-intl vs @intlayer/next-intl

    Adaptador de compatibilidade @intlayer/next-intl