Internacionalização (i18n)

Q: Como o roteamento baseado em locale funciona com o segmento dinâmico [locale]?

Todas as páginas são aninhadas sob app/[locale]/, produzindo URLs como /en/posts e /de/posts. O parâmetro locale é extraído da URL e usado para carregar o dicionário correto. generateStaticParams pré-renderiza páginas para todos os locales configurados no tempo de compilação.

Q: Como o middleware detecta o idioma preferido do usuário?

Ele lê o cabeçalho Accept-Language enviado pelo navegador. Ele analisa o cabeçalho em códigos de idioma com pesos de prioridade e os ordena por prioridade. O primeiro locale correspondente da configuração é usado; caso contrário, o locale padrão é retornado.

Q: Por que os dicionários são carregados com import() dinâmico em vez de imports estáticos?

import() dinâmico permite a divisão automática de código por locale. Apenas as traduções do locale solicitado são carregadas, não todas as línguas de uma vez. Isso mantém os tamanhos dos bundles pequenos, especialmente com muitos locales.

Q: Armadilha: O que acontece se generateStaticParams não incluir um locale?

Esse locale produzirá um 404 na produção, a menos que dynamicParams esteja habilitado. Sempre retorne todos os locales configurados de generateStaticParams. Locales ausentes falharão silenciosamente sem aviso no tempo de compilação.

Q: Componentes Cliente podem chamar getDictionary diretamente?

Não, porque getDictionary usa import() do lado do servidor. Passe as traduções como props de um Server Component pai para o Client Component. Alternativamente, use uma biblioteca como next-intl que fornece um hook useTranslations para o lado do cliente.

Q: Como adicionar tags hreflang para SEO com a Metadata API?

O campo alternates.languages gera tags .

Q: Como tipar o tipo Locale derivado da configuração em TypeScript?

A asserção as const é crucial; sem ela, o tipo se expande para string[].

Q: Como lidar com idiomas RTL (direita para esquerda) como árabe ou hebraico?

Defina o atributo dir em com base no locale.

app/
  [locale]/
    layout.tsx
    page.tsx
    posts/
      page.tsx
lib/
  i18n/
    config.ts
    get-dictionary.ts
    dictionaries/
      en.json
      de.json
      ja.json
middleware.ts

Configuração de i18n

// lib/i18n/config.ts
export const i18nConfig = {
  defaultLocale: "en",
  locales: ["en", "de", "ja"],
} as const;
 
export type Locale = (typeof i18nConfig.locales)[number];

Dicionários de Tradução

// lib/i18n/dictionaries/en.json
{
  "common": {
    "title": "My App",
    "nav": {
      "home": "Home",
      "posts": "Posts",
      "about": "About"
    }
  },
  "home": {
    "heading": "Welcome to My App",
    "description": "A modern web application"
  },
  "posts": {
    "heading": "All Posts",
    "empty": "No posts found"
  }
}

// lib/i18n/dictionaries/de.json
{
  "common": {
    "title": "Meine App",
    "nav": {
      "home": "Startseite",
      "posts": "Beiträge",
      "about": "Über uns"
    }
  },
  "home": {
    "heading": "Willkommen bei Meine App",
    "description": "Eine moderne Webanwendung"
  },
  "posts": {
    "heading": "Alle Beiträge",
    "empty": "Keine Beiträge gefunden"
  }
}

Carregador de Dicionário

// lib/i18n/get-dictionary.ts
import type { Locale } from "./config";
 
const dictionaries = {
  en: () => import("./dictionaries/en.json").then((m) => m.default),
  de: () => import("./dictionaries/de.json").then((m) => m.default),
  ja: () => import("./dictionaries/ja.json").then((m) => m.default),
};
 
export async function getDictionary(locale: Locale) {
  return dictionaries[locale]();
}
 
export type Dictionary = Awaited<ReturnType<typeof getDictionary>>;

Middleware de Detecção de Locale

// middleware.ts
import { NextRequest, NextResponse } from "next/server";
import { i18nConfig } from "./lib/i18n/config";
 
function getPreferredLocale(request: NextRequest): string {
  const acceptLanguage = request.headers.get("accept-language");
  if (!acceptLanguage) return i18nConfig.defaultLocale;
 
  const preferred = acceptLanguage
    .split(",")
    .map((lang) => {
      const [code, priority] = lang.trim().split(";q=");
      return {
        code: code.split("-")[0].toLowerCase(),
        priority: priority ? parseFloat(priority) : 1.0,
      };
    })
    .sort((a, b) => b.priority - a.priority);
 
  const match = preferred.find((p) =>
    i18nConfig.locales.includes(p.code as any)
  );
 
  return match?.code ?? i18nConfig.defaultLocale;
}
 
export function middleware(request: NextRequest) {
  const { pathname } = request.nextUrl;
 
  // Check if pathname already has a locale
  const pathnameHasLocale = i18nConfig.locales.some(
    (locale) => pathname.startsWith(`/${locale}/`) || pathname === `/${locale}`
  );
 
  if (pathnameHasLocale) return NextResponse.next();
 
  // Skip non-page paths
  if (
    pathname.startsWith("/_next") ||
    pathname.startsWith("/api") ||
    pathname.includes(".")
  ) {
    return NextResponse.next();
  }
 
  // Redirect to locale-prefixed path
  const locale = getPreferredLocale(request);
  const newUrl = new URL(`/${locale}${pathname}`, request.url);
  return NextResponse.redirect(newUrl);
}
 
export const config = {
  matcher: ["/((?!_next|api|favicon.ico).*)"],
};

Layout de Locale

// app/[locale]/layout.tsx
import type { Metadata } from "next";
import { notFound } from "next/navigation";
import { i18nConfig, type Locale } from "@/lib/i18n/config";
import { getDictionary } from "@/lib/i18n/get-dictionary";
 
type Props = {
  children: React.ReactNode;
  params: Promise<{ locale: string }>;
};
 
export async function generateStaticParams() {
  return i18nConfig.locales.map((locale) => ({ locale }));
}
 
export async function generateMetadata({
  params,
}: {
  params: Promise<{ locale: string }>;
}): Promise<Metadata> {
  const { locale } = await params;
  const dict = await getDictionary(locale as Locale);
 
  return {
    title: {
      default: dict.common.title,
      template: `%s | ${dict.common.title}`,
    },
    alternates: {
      languages: Object.fromEntries(
        i18nConfig.locales.map((l) => [l, `/${l}`])
      ),
    },
  };
}
 
export default async function LocaleLayout({ children, params }: Props) {
  const { locale } = await params;
 
  if (!i18nConfig.locales.includes(locale as Locale)) {
    notFound();
  }
 
  return (
    <html lang={locale}>
      <body>{children}</body>
    </html>
  );
}

Página Traduzida

// app/[locale]/page.tsx
import { getDictionary } from "@/lib/i18n/get-dictionary";
import type { Locale } from "@/lib/i18n/config";
 
type Props = {
  params: Promise<{ locale: string }>;
};
 
export default async function HomePage({ params }: Props) {
  const { locale } = await params;
  const dict = await getDictionary(locale as Locale);
 
  return (
    <main>
      <h1>{dict.home.heading}</h1>
      <p>{dict.home.description}</p>
    </main>
  );
}

Seletor de Idioma (Componente Cliente)

// components/language-switcher.tsx
"use client";
 
import { usePathname, useRouter } from "next/navigation";
import { i18nConfig, type Locale } from "@/lib/i18n/config";
 
const languageNames: Record<Locale, string> = {
  en: "English",
  de: "Deutsch",
  ja: "日本語",
};
 
export function LanguageSwitcher({ currentLocale }: { currentLocale: Locale }) {
  const pathname = usePathname();
  const router = useRouter();
 
  function switchLocale(newLocale: Locale) {
    // Replace current locale in path with new locale
    const segments = pathname.split("/");
    segments[1] = newLocale;
    router.push(segments.join("/"));
  }
 
  return (
    <select
      value={currentLocale}
      onChange={(e) => switchLocale(e.target.value as Locale)}
      aria-label="Select language"
    >
      {i18nConfig.locales.map((locale) => (
        <option key={locale} value={locale}>
          {languageNames[locale]}
        </option>
      ))}
    </select>
  );
}

Análise Detalhada

Como Funciona

Roteamento baseado em locale usa o segmento dinâmico [locale] como o primeiro segmento do caminho. Todas as páginas são aninhadas sob app/[locale]/, produzindo URLs como /en/posts e /de/posts.
Middleware detecta o locale preferido do cabeçalho Accept-Language e redireciona caminhos não localizados para o prefixo de locale correto.
Dicionários são carregados por requisição em Server Components usando import() dinâmico. As traduções de cada locale são divididas em código automaticamente.
generateStaticParams pré-renderiza páginas para todos os locales no tempo de compilação, garantindo que a geração estática funcione com roteamento de locale.
Tags hreflang são adicionadas através do campo alternates.languages na Metadata API, informando aos motores de busca sobre alternativas de idioma.

Variações

Usando next-intl (Biblioteca Completa):

// next-intl setup
// i18n/request.ts
import { getRequestConfig } from "next-intl/server";
 
export default getRequestConfig(async ({ locale }) => ({
  messages: (await import(`../messages/${locale}.json`)).default,
}));

// app/[locale]/page.tsx
import { useTranslations } from "next-intl";
 
export default function HomePage() {
  const t = useTranslations("home");
  return <h1>{t("heading")}</h1>;
}

Interpolação e Plurais:

// lib/i18n/translate.ts
type TranslationValues = Record<string, string | number>;
 
export function t(
  template: string,
  values?: TranslationValues
): string {
  if (!values) return template;
 
  return Object.entries(values).reduce(
    (result, [key, value]) =>
      result.replace(new RegExp(`\\{${key}\\}`, "g"), String(value)),
    template
  );
}
 
// Usage:
// t("Hello, {name}! You have {count} messages.", { name: "Alice", count: 5 })
// => "Hello, Alice! You have 5 messages."

Suporte a Idiomas RTL:

// app/[locale]/layout.tsx
const rtlLocales = ["ar", "he"];
 
export default async function LocaleLayout({ children, params }: Props) {
  const { locale } = await params;
  const dir = rtlLocales.includes(locale) ? "rtl" : "ltr";
 
  return (
    <html lang={locale} dir={dir}>
      <body>{children}</body>
    </html>
  );
}

Notas de TypeScript

Defina Locale como um tipo union derivado da configuração: type Locale = (typeof i18nConfig.locales)[number].
Os tipos de dicionário são inferidos da estrutura JSON. Use Awaited<ReturnType<typeof getDictionary>> para o tipo completo.
params é Promise<{ locale: string }> no Next.js 15+. Converta para Locale após a validação.
Para chaves de tradução profundamente aninhadas, considere um helper que forneça autocompletar:

type NestedKeyOf<T> = T extends object
  ? { [K in keyof T]: K extends string
      ? T[K] extends object
        ? `${K}.${NestedKeyOf<T[K]>}`
        : K
      : never
    }[keyof T]
  : never;

Armadilhas

O middleware é executado em cada requisição. A regex de detecção de locale em config.matcher deve excluir assets estáticos (_next, arquivos com extensões) para evitar redirecionamentos desnecessários.
generateStaticParams deve retornar todos os locales. Locales ausentes produzirão 404 na produção, a menos que dynamicParams esteja habilitado.
Componentes Cliente não podem chamar getDictionary diretamente porque ele usa import() com módulos exclusivos do servidor. Passe as traduções como props de um Server Component, ou use uma biblioteca como next-intl que fornece um hook para o lado do cliente.
O tratamento do locale padrão varia. Alguns preferem /en/about (todos os locales prefixados), outros preferem /about para o padrão e /de/about para os outros. A abordagem de middleware acima sempre prefixa. Para ocultar o locale padrão, use rewrite em vez de redirect.
Formatação de datas, números e moedas deve usar Intl.DateTimeFormat e Intl.NumberFormat com o locale atual, não dicionários baseados em string.
Arquivos de tradução grandes aumentam o tamanho do bundle. Use import() dinâmico para dividir o código por locale e evitar carregar todas as línguas de uma vez.

Alternativas

Abordagem	Prós	Contras
Roteamento manual `[locale]` + JSON	Sem dependências, controle total	Interpolação manual, sem plurais
next-intl	Completo, suporte a RSC, type-safe	Dependência extra
i18next + react-i18next	Grande ecossistema, maduro	Projetado para o lado do cliente, SSR precisa de adaptadores
Paraglide.js (inlang)	Tempo de compilação, runtime mínimo	Mais novo, comunidade menor
Crowdin ou Lokalise	Plataforma de gerenciamento de traduções	Custo, ferramentas externas

FAQs

Como o roteamento baseado em locale funciona com o segmento dinâmico `[locale]`?

Todas as páginas são aninhadas sob app/[locale]/, produzindo URLs como /en/posts e /de/posts.
O parâmetro locale é extraído da URL e usado para carregar o dicionário correto.
generateStaticParams pré-renderiza páginas para todos os locales configurados no tempo de compilação.

Como o middleware detecta o idioma preferido do usuário?

Ele lê o cabeçalho Accept-Language enviado pelo navegador.
Ele analisa o cabeçalho em códigos de idioma com pesos de prioridade e os ordena por prioridade.
O primeiro locale correspondente da configuração é usado; caso contrário, o locale padrão é retornado.

Por que os dicionários são carregados com `import()` dinâmico em vez de imports estáticos?

import() dinâmico permite a divisão automática de código por locale.
Apenas as traduções do locale solicitado são carregadas, não todas as línguas de uma vez.
Isso mantém os tamanhos dos bundles pequenos, especialmente com muitos locales.

Armadilha: O que acontece se `generateStaticParams` não incluir um locale?

Esse locale produzirá um 404 na produção, a menos que dynamicParams esteja habilitado.
Sempre retorne todos os locales configurados de generateStaticParams.
Locales ausentes falharão silenciosamente sem aviso no tempo de compilação.

Componentes Cliente podem chamar `getDictionary` diretamente?

Não, porque getDictionary usa import() do lado do servidor.
Passe as traduções como props de um Server Component pai para o Client Component.
Alternativamente, use uma biblioteca como next-intl que fornece um hook useTranslations para o lado do cliente.

Como adicionar tags hreflang para SEO com a Metadata API?

export async function generateMetadata() {
  return {
    alternates: {
      languages: {
        en: "/en",
        de: "/de",
        ja: "/ja",
      },
    },
  };
}

O campo alternates.languages gera tags <link rel="alternate" hreflang="...">.

Como tipar o tipo `Locale` derivado da configuração em TypeScript?

export const i18nConfig = {
  defaultLocale: "en",
  locales: ["en", "de", "ja"],
} as const;
 
export type Locale = (typeof i18nConfig.locales)[number];
// Result: "en" | "de" | "ja"

A asserção as const é crucial; sem ela, o tipo se expande para string[].

Como tipar o valor de retorno do dicionário em TypeScript?

export type Dictionary = Awaited<
  ReturnType<typeof getDictionary>
>;

O tipo é inferido automaticamente da estrutura JSON.
Nenhuma definição de interface manual é necessária.

Armadilha: Por que o matcher do middleware deve excluir assets estáticos e rotas de API?

O middleware é executado em cada requisição que corresponde ao padrão.
Sem exclusões, requisições para _next/static, imagens e rotas de API seriam redirecionadas para caminhos com prefixo de locale.
O matcher ["/((?!_next|api|favicon.ico).*)"] impede redirecionamentos desnecessários.

Como lidar com idiomas RTL (direita para esquerda) como árabe ou hebraico?

const rtlLocales = ["ar", "he"];
const dir = rtlLocales.includes(locale) ? "rtl" : "ltr";
 
return (
  <html lang={locale} dir={dir}>
    <body>{children}</body>
  </html>
);

Defina o atributo dir em <html> com base no locale.

Qual a diferença entre redirecionar e reescrever para o locale padrão?

Redirecionar /about para /en/about sempre mostra o prefixo do locale na URL.
Reescrever serve o conteúdo de /en/about em /about sem alterar a URL.
Ocultar o locale padrão (reescrever) é comum; mostrá-lo (redirecionar) é mais simples de implementar.

Como a biblioteca `next-intl` simplifica o i18n em comparação com a abordagem manual?

Ela fornece useTranslations para Componentes Cliente sem prop-drilling.
Ela lida com interpolação, plurais e formatação de números/datas prontos para uso.
Ela se integra nativamente com o App Router e Server Components.

Relacionados

SEO - tags hreflang e metadados específicos de locale
Autenticação - redirecionamentos de autenticação cientes do locale
Implantação - servindo builds específicos de locale
Documentação de Internacionalização do Next.js

app/
  [locale]/
    layout.tsx
    page.tsx
    posts/
      page.tsx
lib/
  i18n/
    config.ts
    get-dictionary.ts
    dictionaries/
      en.json
      de.json
      ja.json
middleware.ts

Configuração de i18n

// lib/i18n/config.ts
export const i18nConfig = {
  defaultLocale: "en",
  locales: ["en", "de", "ja"],
} as const;
 
export type Locale = (typeof i18nConfig.locales)[number];

Dicionários de Tradução

// lib/i18n/dictionaries/en.json
{
  "common": {
    "title": "My App",
    "nav": {
      "home": "Home",
      "posts": "Posts",
      "about": "About"
    }
  },
  "home": {
    "heading": "Welcome to My App",
    "description": "A modern web application"
  },
  "posts": {
    "heading": "All Posts",
    "empty": "No posts found"
  }
}

// lib/i18n/dictionaries/de.json
{
  "common": {
    "title": "Meine App",
    "nav": {
      "home": "Startseite",
      "posts": "Beiträge",
      "about": "Über uns"
    }
  },
  "home": {
    "heading": "Willkommen bei Meine App",
    "description": "Eine moderne Webanwendung"
  },
  "posts": {
    "heading": "Alle Beiträge",
    "empty": "Keine Beiträge gefunden"
  }
}

Carregador de Dicionário

// lib/i18n/get-dictionary.ts
import type { Locale } from "./config";
 
const dictionaries = {
  en: () => import("./dictionaries/en.json").then((m) => m.default),
  de: () => import("./dictionaries/de.json").then((m) => m.default),
  ja: () => import("./dictionaries/ja.json").then((m) => m.default),
};
 
export async function getDictionary(locale: Locale) {
  return dictionaries[locale]();
}
 
export type Dictionary = Awaited<ReturnType<typeof getDictionary>>;

Middleware de Detecção de Locale

// middleware.ts
import { NextRequest, NextResponse } from "next/server";
import { i18nConfig } from "./lib/i18n/config";
 
function getPreferredLocale(request: NextRequest): string {
  const acceptLanguage = request.headers.get("accept-language");
  if (!acceptLanguage) return i18nConfig.defaultLocale;
 
  const preferred = acceptLanguage
    .split(",")
    .map((lang) => {
      const [code, priority] = lang.trim().split(";q=");
      return {
        code: code.split("-")[0].toLowerCase(),
        priority: priority ? parseFloat(priority) : 1.0,
      };
    })
    .sort((a, b) => b.priority - a.priority);
 
  const match = preferred.find((p) =>
    i18nConfig.locales.includes(p.code as any)
  );
 
  return match?.code ?? i18nConfig.defaultLocale;
}
 
export function middleware(request: NextRequest) {
  const { pathname } = request.nextUrl;
 
  // Check if pathname already has a locale
  const pathnameHasLocale = i18nConfig.locales.some(
    (locale) => pathname.startsWith(`/${locale}/`) || pathname === `/${locale}`
  );
 
  if (pathnameHasLocale) return NextResponse.next();
 
  // Skip non-page paths
  if (
    pathname.startsWith("/_next") ||
    pathname.startsWith("/api") ||
    pathname.includes(".")
  ) {
    return NextResponse.next();
  }
 
  // Redirect to locale-prefixed path
  const locale = getPreferredLocale(request);
  const newUrl = new URL(`/${locale}${pathname}`, request.url);
  return NextResponse.redirect(newUrl);
}
 
export const config = {
  matcher: ["/((?!_next|api|favicon.ico).*)"],
};

Layout de Locale

// app/[locale]/layout.tsx
import type { Metadata } from "next";
import { notFound } from "next/navigation";
import { i18nConfig, type Locale } from "@/lib/i18n/config";
import { getDictionary } from "@/lib/i18n/get-dictionary";
 
type Props = {
  children: React.ReactNode;
  params: Promise<{ locale: string }>;
};
 
export async function generateStaticParams() {
  return i18nConfig.locales.map((locale) => ({ locale }));
}
 
export async function generateMetadata({
  params,
}: {
  params: Promise<{ locale: string }>;
}): Promise<Metadata> {
  const { locale } = await params;
  const dict = await getDictionary(locale as Locale);
 
  return {
    title: {
      default: dict.common.title,
      template: `%s | ${dict.common.title}`,
    },
    alternates: {
      languages: Object.fromEntries(
        i18nConfig.locales.map((l) => [l, `/${l}`])
      ),
    },
  };
}
 
export default async function LocaleLayout({ children, params }: Props) {
  const { locale } = await params;
 
  if (!i18nConfig.locales.includes(locale as Locale)) {
    notFound();
  }
 
  return (
    <html lang={locale}>
      <body>{children}</body>
    </html>
  );
}

Página Traduzida

// app/[locale]/page.tsx
import { getDictionary } from "@/lib/i18n/get-dictionary";
import type { Locale } from "@/lib/i18n/config";
 
type Props = {
  params: Promise<{ locale: string }>;
};
 
export default async function HomePage({ params }: Props) {
  const { locale } = await params;
  const dict = await getDictionary(locale as Locale);
 
  return (
    <main>
      <h1>{dict.home.heading}</h1>
      <p>{dict.home.description}</p>
    </main>
  );
}

Seletor de Idioma (Componente Cliente)

// components/language-switcher.tsx
"use client";
 
import { usePathname, useRouter } from "next/navigation";
import { i18nConfig, type Locale } from "@/lib/i18n/config";
 
const languageNames: Record<Locale, string> = {
  en: "English",
  de: "Deutsch",
  ja: "日本語",
};
 
export function LanguageSwitcher({ currentLocale }: { currentLocale: Locale }) {
  const pathname = usePathname();
  const router = useRouter();
 
  function switchLocale(newLocale: Locale) {
    // Replace current locale in path with new locale
    const segments = pathname.split("/");
    segments[1] = newLocale;
    router.push(segments.join("/"));
  }
 
  return (
    <select
      value={currentLocale}
      onChange={(e) => switchLocale(e.target.value as Locale)}
      aria-label="Select language"
    >
      {i18nConfig.locales.map((locale) => (
        <option key={locale} value={locale}>
          {languageNames[locale]}
        </option>
      ))}
    </select>
  );
}

Análise Detalhada

Como Funciona

Roteamento baseado em locale usa o segmento dinâmico [locale] como o primeiro segmento do caminho. Todas as páginas são aninhadas sob app/[locale]/, produzindo URLs como /en/posts e /de/posts.
Middleware detecta o locale preferido do cabeçalho Accept-Language e redireciona caminhos não localizados para o prefixo de locale correto.
Dicionários são carregados por requisição em Server Components usando import() dinâmico. As traduções de cada locale são divididas em código automaticamente.
generateStaticParams pré-renderiza páginas para todos os locales no tempo de compilação, garantindo que a geração estática funcione com roteamento de locale.
Tags hreflang são adicionadas através do campo alternates.languages na Metadata API, informando aos motores de busca sobre alternativas de idioma.

Variações

Usando next-intl (Biblioteca Completa):

// next-intl setup
// i18n/request.ts
import { getRequestConfig } from "next-intl/server";
 
export default getRequestConfig(async ({ locale }) => ({
  messages: (await import(`../messages/${locale}.json`)).default,
}));

// app/[locale]/page.tsx
import { useTranslations } from "next-intl";
 
export default function HomePage() {
  const t = useTranslations("home");
  return <h1>{t("heading")}</h1>;
}

Interpolação e Plurais:

// lib/i18n/translate.ts
type TranslationValues = Record<string, string | number>;
 
export function t(
  template: string,
  values?: TranslationValues
): string {
  if (!values) return template;
 
  return Object.entries(values).reduce(
    (result, [key, value]) =>
      result.replace(new RegExp(`\\{${key}\\}`, "g"), String(value)),
    template
  );
}
 
// Usage:
// t("Hello, {name}! You have {count} messages.", { name: "Alice", count: 5 })
// => "Hello, Alice! You have 5 messages."

Suporte a Idiomas RTL:

// app/[locale]/layout.tsx
const rtlLocales = ["ar", "he"];
 
export default async function LocaleLayout({ children, params }: Props) {
  const { locale } = await params;
  const dir = rtlLocales.includes(locale) ? "rtl" : "ltr";
 
  return (
    <html lang={locale} dir={dir}>
      <body>{children}</body>
    </html>
  );
}

Notas de TypeScript

Defina Locale como um tipo union derivado da configuração: type Locale = (typeof i18nConfig.locales)[number].
Os tipos de dicionário são inferidos da estrutura JSON. Use Awaited<ReturnType<typeof getDictionary>> para o tipo completo.
params é Promise<{ locale: string }> no Next.js 15+. Converta para Locale após a validação.
Para chaves de tradução profundamente aninhadas, considere um helper que forneça autocompletar:

type NestedKeyOf<T> = T extends object
  ? { [K in keyof T]: K extends string
      ? T[K] extends object
        ? `${K}.${NestedKeyOf<T[K]>}`
        : K
      : never
    }[keyof T]
  : never;

Armadilhas

O middleware é executado em cada requisição. A regex de detecção de locale em config.matcher deve excluir assets estáticos (_next, arquivos com extensões) para evitar redirecionamentos desnecessários.
generateStaticParams deve retornar todos os locales. Locales ausentes produzirão 404 na produção, a menos que dynamicParams esteja habilitado.
Componentes Cliente não podem chamar getDictionary diretamente porque ele usa import() com módulos exclusivos do servidor. Passe as traduções como props de um Server Component, ou use uma biblioteca como next-intl que fornece um hook para o lado do cliente.
O tratamento do locale padrão varia. Alguns preferem /en/about (todos os locales prefixados), outros preferem /about para o padrão e /de/about para os outros. A abordagem de middleware acima sempre prefixa. Para ocultar o locale padrão, use rewrite em vez de redirect.
Formatação de datas, números e moedas deve usar Intl.DateTimeFormat e Intl.NumberFormat com o locale atual, não dicionários baseados em string.
Arquivos de tradução grandes aumentam o tamanho do bundle. Use import() dinâmico para dividir o código por locale e evitar carregar todas as línguas de uma vez.

Alternativas

Abordagem	Prós	Contras
Roteamento manual `[locale]` + JSON	Sem dependências, controle total	Interpolação manual, sem plurais
next-intl	Completo, suporte a RSC, type-safe	Dependência extra
i18next + react-i18next	Grande ecossistema, maduro	Projetado para o lado do cliente, SSR precisa de adaptadores
Paraglide.js (inlang)	Tempo de compilação, runtime mínimo	Mais novo, comunidade menor
Crowdin ou Lokalise	Plataforma de gerenciamento de traduções	Custo, ferramentas externas

FAQs

Como o roteamento baseado em locale funciona com o segmento dinâmico `[locale]`?

Todas as páginas são aninhadas sob app/[locale]/, produzindo URLs como /en/posts e /de/posts.
O parâmetro locale é extraído da URL e usado para carregar o dicionário correto.
generateStaticParams pré-renderiza páginas para todos os locales configurados no tempo de compilação.

Como o middleware detecta o idioma preferido do usuário?

Ele lê o cabeçalho Accept-Language enviado pelo navegador.
Ele analisa o cabeçalho em códigos de idioma com pesos de prioridade e os ordena por prioridade.
O primeiro locale correspondente da configuração é usado; caso contrário, o locale padrão é retornado.

Por que os dicionários são carregados com `import()` dinâmico em vez de imports estáticos?

import() dinâmico permite a divisão automática de código por locale.
Apenas as traduções do locale solicitado são carregadas, não todas as línguas de uma vez.
Isso mantém os tamanhos dos bundles pequenos, especialmente com muitos locales.

Armadilha: O que acontece se `generateStaticParams` não incluir um locale?

Esse locale produzirá um 404 na produção, a menos que dynamicParams esteja habilitado.
Sempre retorne todos os locales configurados de generateStaticParams.
Locales ausentes falharão silenciosamente sem aviso no tempo de compilação.

Componentes Cliente podem chamar `getDictionary` diretamente?

Não, porque getDictionary usa import() do lado do servidor.
Passe as traduções como props de um Server Component pai para o Client Component.
Alternativamente, use uma biblioteca como next-intl que fornece um hook useTranslations para o lado do cliente.

Como adicionar tags hreflang para SEO com a Metadata API?

export async function generateMetadata() {
  return {
    alternates: {
      languages: {
        en: "/en",
        de: "/de",
        ja: "/ja",
      },
    },
  };
}

O campo alternates.languages gera tags <link rel="alternate" hreflang="...">.

Como tipar o tipo `Locale` derivado da configuração em TypeScript?

export const i18nConfig = {
  defaultLocale: "en",
  locales: ["en", "de", "ja"],
} as const;
 
export type Locale = (typeof i18nConfig.locales)[number];
// Result: "en" | "de" | "ja"

A asserção as const é crucial; sem ela, o tipo se expande para string[].

Como tipar o valor de retorno do dicionário em TypeScript?

export type Dictionary = Awaited<
  ReturnType<typeof getDictionary>
>;

O tipo é inferido automaticamente da estrutura JSON.
Nenhuma definição de interface manual é necessária.

Armadilha: Por que o matcher do middleware deve excluir assets estáticos e rotas de API?

O middleware é executado em cada requisição que corresponde ao padrão.
Sem exclusões, requisições para _next/static, imagens e rotas de API seriam redirecionadas para caminhos com prefixo de locale.
O matcher ["/((?!_next|api|favicon.ico).*)"] impede redirecionamentos desnecessários.

Como lidar com idiomas RTL (direita para esquerda) como árabe ou hebraico?

const rtlLocales = ["ar", "he"];
const dir = rtlLocales.includes(locale) ? "rtl" : "ltr";
 
return (
  <html lang={locale} dir={dir}>
    <body>{children}</body>
  </html>
);

Defina o atributo dir em <html> com base no locale.

Qual a diferença entre redirecionar e reescrever para o locale padrão?

Redirecionar /about para /en/about sempre mostra o prefixo do locale na URL.
Reescrever serve o conteúdo de /en/about em /about sem alterar a URL.
Ocultar o locale padrão (reescrever) é comum; mostrá-lo (redirecionar) é mais simples de implementar.

Como a biblioteca `next-intl` simplifica o i18n em comparação com a abordagem manual?

Ela fornece useTranslations para Componentes Cliente sem prop-drilling.
Ela lida com interpolação, plurais e formatação de números/datas prontos para uso.
Ela se integra nativamente com o App Router e Server Components.

Relacionados

SEO - tags hreflang e metadados específicos de locale
Autenticação - redirecionamentos de autenticação cientes do locale
Implantação - servindo builds específicos de locale
Documentação de Internacionalização do Next.js

Internacionalização (i18n)

Receita

Exemplo de Trabalho

Estrutura do Projeto

Configuração de i18n

Dicionários de Tradução

Carregador de Dicionário

Middleware de Detecção de Locale

Layout de Locale

Página Traduzida

Seletor de Idioma (Componente Cliente)

Análise Detalhada

Como Funciona

Variações

Notas de TypeScript

Armadilhas

Alternativas

FAQs

Relacionados

Internacionalização (i18n)

Receita

Exemplo de Trabalho

Estrutura do Projeto

Configuração de i18n

Dicionários de Tradução

Carregador de Dicionário

Middleware de Detecção de Locale

Layout de Locale

Página Traduzida

Seletor de Idioma (Componente Cliente)

Análise Detalhada

Como Funciona

Variações

Notas de TypeScript

Armadilhas

Alternativas

FAQs

Relacionados

Internacionalização (i18n)

Buscar na documentação

Internacionalização (i18n)