Skip to main content

Guia completa de la internacionalització de Next.js

Configuri next-intl amb l'App Router, configuri l'encaminament per configuració regional i automatitzi les traduccions amb IA.

1

Instal·lar next-intl

next-intl és un únic paquet que gestiona l'encaminament per configuració regional, la càrrega de missatges i els hooks de traducció per a l'App Router de Next.js.

Terminal
npm install next-intl
Per què next-intl en lloc de next-i18next? next-intl està dissenyat per a l'App Router i els components de servidor. next-i18next es va dissenyar per al Pages Router i té un suport limitat per a l'App Router.
2

Crear la configuració de sol·licitud d’i18n

Creï dos fitxers: src/i18n/request.ts per a la càrrega de missatges i src/i18n/routing.ts per a les definicions de configuració regional. Aquests fitxers configuren com next-intl resol els missatges i les rutes.

src/i18n/routing.ts
// src/i18n/routing.ts
import { defineRouting } from 'next-intl/routing';
import { createNavigation } from 'next-intl/navigation';

export const routing = defineRouting({
  locales: ['en', 'de', 'ja', 'es'],
  defaultLocale: 'en',
  localePrefix: 'as-needed',  // /about for en, /de/about for de
});

export const { Link, redirect, usePathname, useRouter } =
  createNavigation(routing);
Turbopack (l'empaquetador per defecte a Next.js 15) requereix experimental.turbo.resolveAlias al seu next.config.js. Sense això, obtindrà errors de "Couldn't find next-intl config file".
3

Configurar el middleware

Afegeixi middleware.ts per gestionar la detecció de la configuració regional, la reescriptura d'URL i les redireccions. El middleware intercepta cada sol·licitud i garanteix que s'apliqui la configuració regional correcta.

middleware.ts
// middleware.ts  <- Must be in project ROOT, not src/
import createMiddleware from 'next-intl/middleware';
import { routing } from './src/i18n/routing';

export default createMiddleware(routing);

export const config = {
  matcher: ['/((?!api|_next|.*\\..*).*)'],
};
middleware.ts HA d'estar al directori arrel del projecte, no dins de src/. Aquest és, de llarg, l'error de configuració més habitual amb next-intl.
4

Configurar l’estructura de carpetes [locale]

Traslladi les rutes de l'aplicació dins d'app/[locale]/. Afegeixi generateStaticParams per generar pàgines per a cada configuració regional en el moment de la compilació. Això crea l'estructura d'URL /en/about, /de/about, etc.

app/[locale]/layout.tsx
// app/[locale]/layout.tsx
import { routing } from '@/i18n/routing';

export function generateStaticParams() {
  return routing.locales.map((locale) => ({ locale }));
}
HA de cridar setRequestLocale(locale) a cada page.tsx i layout.tsx que utilitzi traduccions. Sense això, Next.js recorre a la renderització dinàmica i el rendiment de la compilació es degrada significativament.
5

Actualitzar el disseny arrel

Carregui els missatges amb getMessages() i passi'ls a NextIntlClientProvider al disseny arrel de la configuració regional. Estableixi l'atribut lang de l'html a partir del paràmetre de configuració regional.

app/[locale]/layout.tsx
// app/[locale]/layout.tsx
import { NextIntlClientProvider } from 'next-intl';
import { getMessages, setRequestLocale } from 'next-intl/server';
import { routing } from '@/i18n/routing';
import { notFound } from 'next/navigation';

export function generateStaticParams() {
  return routing.locales.map((locale) => ({ locale }));
}

export default async function LocaleLayout({
  children,
  params,
}: {
  children: React.ReactNode;
  params: { locale: string };
}) {
  const { locale } = await params;
  if (!routing.locales.includes(locale as any)) notFound();

  setRequestLocale(locale);
  const messages = await getMessages();

  return (
    <html lang={locale}>
      <body>
        <NextIntlClientProvider locale={locale} messages={messages}>
          {children}
        </NextIntlClientProvider>
      </body>
    </html>
  );
}
NextIntlClientProvider requereix una propietat locale explícita. Ometre-la provoca errors subtils en els components de client que són difícils de depurar.
6

Utilitzi les traduccions als components

Els components de servidor utilitzen getTranslations (async, await). Els components de client utilitzen useTranslations (hook). Triï l'opció adequada segons on es renderitzi el component: els components de servidor mantenen les traduccions totalment fora del paquet de JavaScript.

app/[locale]/page.tsx
// Server Component (default)
import { getTranslations, setRequestLocale } from 'next-intl/server';

export default async function AboutPage({
  params,
}: { params: { locale: string } }) {
  const { locale } = await params;
  setRequestLocale(locale);
  const t = await getTranslations('AboutPage');

  return <h1>{t('title')}</h1>;
}

// Client Component ('use client')
'use client';
import { useTranslations } from 'next-intl';

export default function SearchBar() {
  const t = useTranslations('SearchBar');
  return <input placeholder={t('placeholder')} />;
}
Prefereixi els components de servidor per al contingut traduït. Mantenen les cadenes de traducció fora del paquet de JavaScript de client, cosa que redueix el temps de càrrega per als usuaris.
7

Afegeixi SEO: metadades i hreflang

Utilitzi generateMetadata per generar títols i descripcions de pàgina específics per a cada configuració regional. Afegeixi alternates.languages per a les etiquetes hreflang perquè els cercadors descobreixin totes les versions lingüístiques de cada pàgina.

app/[locale]/layout.tsx
// app/[locale]/layout.tsx or any page.tsx
import { getTranslations } from 'next-intl/server';
import { routing } from '@/i18n/routing';

export async function generateMetadata({
  params,
}: { params: { locale: string } }) {
  const { locale } = await params;
  const t = await getTranslations({ locale, namespace: 'Metadata' });

  return {
    title: t('title'),
    description: t('description'),
    alternates: {
      languages: Object.fromEntries(
        routing.locales.map((l) => [l, `/${l}`])
      ),
    },
  };
}
A Vercel, les compilacions poden generar localhost com a URL canònica si no s'estableix metadataBase. Estableixi sempre metadataBase al disseny arrel amb el domini de producció.
8

Gestioni les pàgines d'error i de no trobat

error.tsx i not-found.tsx necessiten un tractament especial perquè es poden renderitzar fora del disseny normal de la configuració regional. El not-found.tsx arrel requereix la seva pròpia configuració de proveïdor d'i18n per mostrar missatges d'error localitzats.

app/[locale]/error.tsx
// app/[locale]/error.tsx
'use client';
import { useTranslations } from 'next-intl';

export default function Error() {
  const t = useTranslations('Error');
  return (
    <div>
      <h1>{t('title')}</h1>
      <p>{t('description')}</p>
    </div>
  );
}

// app/not-found.tsx (root level -- needs own provider)
import { routing } from '@/i18n/routing';

export default async function GlobalNotFound() {
  return (
    <html lang={routing.defaultLocale}>
      <body>
        <h1>404 - Page Not Found</h1>
      </body>
    </html>
  );
}
Next.js només renderitza la pàgina 404 localitzada quan es crida explícitament notFound() al codi. Les rutes desconegudes sense una pàgina corresponent mostren el 404 per defecte de Next.js, no la versió localitzada.
9

Automatitzi les traduccions

Un cop finalitzada la configuració d'i18n, tradueixi els fitxers de missatges amb IA directament des de l'IDE o utilitzi la CLI d'i18n Agent al seu pipeline de CI/CD per automatitzar la traducció a cada desplegament.

Terminal
# In your IDE, ask your AI assistant:
> Translate messages/en.json to German, Japanese, and Spanish

✓ messages/de.json created (1.1s)
✓ messages/ja.json created (1.4s)
✓ messages/es.json created (1.0s)
Utilitzi next-intl-localechain per obtenir cadenes de reserva intel·ligents de configuracions regionals: un usuari de pt-BR veu traduccions de pt-PT en lloc de recórrer a l'anglès quan el portuguès brasiler no està disponible.

Automatitzi el control de qualitat de les traduccions

Detecti claus que falten i marcadors de posició trencats abans que es publiquin amb i18n-validate. Provi la interfície amb traduccions falses mitjançant i18n-pseudo abans que arribin les traduccions reals.

Eines de codi obert per a i18n de Next.js

Aquests paquets de codi obert resolen problemes habituals en els fluxos de treball d'internacionalització de Next.js.

next-intl-localechain

El next-intl estàndard recorre directament a la configuració regional per defecte quan falta una traducció. Un usuari de portuguès brasiler veu anglès en lloc de traduccions de pt-PT perfectament vàlides. next-intl-localechain afegeix cadenes de reserva intel·ligents: fusiona en profunditat les traduccions de configuracions regionals relacionades perquè els usuaris regionals vegin sempre la traducció disponible més propera.

src/i18n/request.ts
import { getRequestConfig } from 'next-intl/server';
import { withLocaleChain } from 'next-intl-localechain';

export default getRequestConfig(withLocaleChain({
  loadMessages: (locale) =>
    import(`../../messages/${locale}.json`).then(m => m.default),
  defaultLocale: 'en'
}));
Fusiona en profunditat les traduccions entre cadenes de configuracions regionals automàticament
Cadenes integrades per al portuguès, l'espanyol, el francès, l'alemany i més
Omet correctament els fitxers de missatges que falten sense generar errors
Configuració d'una sola línia: embolcalla el getRequestConfig existent
Veure a GitHub

@i18n-agent/cli

Una eina de línia d'ordres per traduir els fitxers de missatges de Next.js sense sortir del terminal. Tradueixi fitxers directament, comprovi l'estat de les tasques i descarregui els resultats. Funciona en pipelines de CI/CD amb autenticació per clau d'API per a fluxos de treball de localització totalment automatitzats.

Terminal
# Install the CLI
npm install -g @i18n-agent/cli

# Authenticate
i18nagent login

# Translate your message files
i18nagent translate ./messages/en.json --lang de,ja,es

# Or use in CI/CD with an API key
export I18N_AGENT_API_KEY=your-key-here
i18nagent translate ./messages/en.json --lang de,ja,es
Tradueixi fitxers JSON, YAML, PO i altres formats d'i18n des del terminal
Preparat per a CI/CD: autentiqui's mitjançant una variable d'entorn per a pipelines automatitzats
Faci seguiment de l'estat de les tasques, reprengui les tasques fallides i descarregui els resultats
Sortida JSON llegible per màquina per a scripts i automatització
Veure a GitHub

Errors habituals

"Unable to find next-intl locale"

El middleware no ha coincidit amb la sol·licitud. Comprovi si middleware.ts és al directori arrel del projecte, si el patró matcher exclou correctament els fitxers estàtics i si la configuració regional està inclosa a la configuració d'encaminament.

Renderització dinàmica inesperada

Falta setRequestLocale(locale) en una pàgina o disseny. Sense això, next-intl utilitza capçaleres o cookies per detectar la configuració regional, cosa que força la renderització dinàmica i impedeix la generació estàtica.

Les rutes paral·leles fallen amb i18n

Les rutes paral·leles (@modal) i les rutes d'intercepció ((.)photo) tenen incompatibilitats conegudes amb el segment dinàmic [locale]. Utilitzi l'encaminament basat en middleware com a solució alternativa per a aquests patrons d'encaminament avançats.

El canvi d'idioma perd la ruta actual

En canviar de configuració regional, conservi el pathname actual mitjançant usePathname() i substitueixi només el segment de configuració regional. Vagi amb compte amb els paràmetres de ruta dinàmics: cal tornar-los a resoldre per a la nova configuració regional.

Estructura de fitxers recomanada

Project Structure
my-nextjs-app/
├── middleware.ts              # Locale routing (project root!)
├── next.config.mjs
├── messages/
│   ├── en.json                # Source messages
│   ├── de.json
│   └── ja.json
├── src/
│   ├── i18n/
│   │   ├── request.ts         # Message loading config
│   │   └── routing.ts         # Locale definitions
│   └── app/
│       └── [locale]/
│           ├── layout.tsx     # Root locale layout
│           ├── page.tsx       # Home page
│           ├── error.tsx      # Localized error page
│           ├── not-found.tsx  # Localized 404
│           └── about/
│               └── page.tsx
└── package.json

Provar i18n Agent ara

Arrossegar aquí el fitxer de traducció

JSON, YAML, PO, XML, CSV, Markdown, Properties

o fer clic per explorar

Idiomes de destinació

No cal registrePressupost instantani

Configuració regional de reserva amb next-intl-localechain

Quan falta una clau de traducció en una configuració regional com pt-BR, next-intl passa directament a la configuració regional per defecte en lloc de comprovar primer la configuració regional pare pt.

Terminal
npm install next-intl-localechain
Configuration
import { withLocaleChain } from 'next-intl-localechain';

export default withLocaleChain({
  fallbacks: {
    'pt-BR': ['pt', 'en'],
    'zh-Hant-HK': ['zh-Hant', 'zh', 'en'],
  },
  defaultLocale: 'en',
  loadMessages: (locale) => import(`./messages/${locale}.json`),
});

Consulti la nostra guia de configuracions regionals de reserva per veure la llista completa de frameworks admesos i les 75 cadenes integrades. Learn more →

Preguntes freqüents