
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.
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.
npm install next-intlCrear 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
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);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 <- 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|.*\\..*).*)'],
};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
import { routing } from '@/i18n/routing';
export function generateStaticParams() {
return routing.locales.map((locale) => ({ locale }));
}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
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>
);
}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.
// 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')} />;
}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 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}`])
),
},
};
}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
'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>
);
}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.
# 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)Automatitzi el control de qualitat de les traduccions
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.
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'
}));@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.
# 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,esErrors 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
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.jsonProvar i18n Agent ara
Arrossegar aquí el fitxer de traducció
JSON, YAML, PO, XML, CSV, Markdown, Properties
o fer clic per explorar
Idiomes de destinació
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.
npm install next-intl-localechainimport { 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 →