Skip to main content

Der vollständige Leitfaden zur Next.js-Internationalisierung

Richten Sie next-intl mit dem App Router ein, konfigurieren Sie das Locale-Routing und automatisieren Sie Übersetzungen mit KI.

1

next-intl installieren

next-intl ist ein einzelnes Paket, das Locale-Routing, das Laden von Nachrichten und Übersetzungs-Hooks für den Next.js App Router übernimmt.

Terminal
npm install next-intl
Warum next-intl statt next-i18next? next-intl wurde für den App Router und Serverkomponenten entwickelt. next-i18next wurde für den Pages Router konzipiert und unterstützt den App Router nur eingeschränkt.
2

i18n-Anfragenkonfiguration erstellen

Erstellen Sie zwei Dateien: src/i18n/request.ts zum Laden von Nachrichten und src/i18n/routing.ts für Locale-Definitionen. Sie legen fest, wie next-intl Nachrichten und Routen auflöst.

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, der standardmäßige Bundler in Next.js 15, benötigt experimental.turbo.resolveAlias in Ihrer next.config.js. Andernfalls treten Fehler mit der Meldung „Couldn't find next-intl config file“ auf.
3

Middleware konfigurieren

Fügen Sie middleware.ts hinzu, um Locale-Erkennung, URL-Umschreibung und Weiterleitungen zu verarbeiten. Die Middleware fängt jede Anfrage ab und stellt sicher, dass die richtige Locale angewendet wird.

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 MUSS sich im Stammverzeichnis Ihres Projekts befinden, nicht in src/. Dies ist der mit Abstand häufigste Konfigurationsfehler bei next-intl.
4

Ordnerstruktur [locale] einrichten

Verschieben Sie Ihre App-Routen nach app/[locale]/. Fügen Sie generateStaticParams hinzu, um beim Build Seiten für jede Locale zu erzeugen. So entsteht die URL-Struktur /en/about, /de/about usw.

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

export function generateStaticParams() {
  return routing.locales.map((locale) => ({ locale }));
}
Sie MÜSSEN setRequestLocale(locale) in jeder page.tsx und layout.tsx aufrufen, die Übersetzungen verwendet. Andernfalls wechselt Next.js zu dynamischem Rendering und Ihre Build-Leistung sinkt erheblich.
5

Stammlayout aktualisieren

Laden Sie Nachrichten mit getMessages() und übergeben Sie sie in Ihrem Locale-Stammlayout an NextIntlClientProvider. Setzen Sie das lang-Attribut von html anhand des Locale-Parameters.

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 benötigt eine ausdrücklich angegebene locale-Prop. Wird sie weggelassen, entstehen schwer zu untersuchende Fehler in Clientkomponenten.
6

Übersetzungen in Komponenten verwenden

Serverkomponenten verwenden getTranslations (asynchron, await), Clientkomponenten useTranslations (Hook). Wählen Sie je nach Renderort Ihrer Komponente; Serverkomponenten halten Übersetzungen vollständig aus dem JavaScript-Bundle heraus.

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')} />;
}
Bevorzugen Sie Serverkomponenten für übersetzte Inhalte. Sie halten Übersetzungszeichenfolgen aus Ihrem Client-JavaScript-Bundle heraus und verkürzen so die Ladezeit.
7

SEO hinzufügen: Metadaten und Hreflang

Erzeugen Sie mit generateMetadata Locale-spezifische Seitentitel und Beschreibungen. Fügen Sie alternates.languages für hreflang-Tags hinzu, damit Suchmaschinen alle Sprachversionen jeder Seite finden.

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}`])
      ),
    },
  };
}
Auf Vercel können Builds localhost als kanonische URL erzeugen, wenn metadataBase nicht gesetzt ist. Setzen Sie metadataBase in Ihrem Stammlayout stets auf Ihre Produktionsdomain.
8

Fehler- und Nicht-gefunden-Seiten verarbeiten

error.tsx und not-found.tsx erfordern eine besondere Behandlung, da sie außerhalb des üblichen Locale-Layouts gerendert werden können. Die not-found.tsx im Stammverzeichnis benötigt eine eigene i18n-Provider-Einrichtung, um lokalisierte Fehlermeldungen anzuzeigen.

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 rendert Ihre lokalisierte 404-Seite nur, wenn notFound() ausdrücklich in Ihrem Code aufgerufen wird. Unbekannte Routen ohne passende Seite zeigen die Standard-404-Seite von Next.js und nicht Ihre lokalisierte Version.
9

Übersetzungen automatisieren

Wenn Ihre i18n-Einrichtung abgeschlossen ist, übersetzen Sie Ihre Nachrichtendateien mit KI direkt aus Ihrer IDE oder verwenden Sie die CLI von i18n Agent in Ihrer CI/CD-Pipeline für automatisierte Übersetzungen bei jeder Bereitstellung.

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)
Verwenden Sie next-intl-localechain für intelligente Locale-Fallbacks: Eine Person mit pt-BR sieht pt-PT-Übersetzungen, statt auf Englisch zurückzufallen, wenn brasilianisches Portugiesisch nicht verfügbar ist.

Übersetzungsqualität automatisieren

Erkennen Sie mit i18n-validate fehlende Schlüssel und beschädigte Platzhalter vor der Veröffentlichung. Testen Sie Ihre Benutzeroberfläche mit i18n-pseudo und simulierten Übersetzungen, bevor echte Übersetzungen vorliegen.

Open-Source-Werkzeuge für Next.js-i18n

Diese quelloffenen Pakete lösen häufige Probleme in Arbeitsabläufen zur Next.js-Internationalisierung.

next-intl-localechain

Standardmäßig wechselt next-intl bei einer fehlenden Übersetzung direkt zu Ihrer Standard-Locale. Eine Person mit brasilianischem Portugiesisch sieht Englisch statt vollständig geeigneter pt-PT-Übersetzungen. next-intl-localechain ergänzt intelligente Fallback-Ketten und führt Übersetzungen verwandter Locales rekursiv zusammen, sodass regionale Personen stets die ähnlichste verfügbare Übersetzung sehen.

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'
}));
Führt Übersetzungen über Locale-Ketten automatisch rekursiv zusammen
Integrierte Ketten für Portugiesisch, Spanisch, Französisch, Deutsch und weitere Sprachen
Überspringt fehlende Nachrichtendateien zuverlässig und ohne Fehler
Einrichtung mit einer Zeile – umschließt Ihr bestehendes getRequestConfig
Auf GitHub ansehen

@i18n-agent/cli

Ein Befehlszeilenwerkzeug zum Übersetzen Ihrer Next.js-Nachrichtendateien, ohne das Terminal zu verlassen. Übersetzen Sie Dateien direkt, prüfen Sie den Auftragsstatus und laden Sie Ergebnisse herunter. Funktioniert mit API-Schlüssel-Authentifizierung in CI/CD-Pipelines und ermöglicht vollständig automatisierte Lokalisierungsabläufe.

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
JSON, YAML, PO und andere i18n-Dateiformate im Terminal übersetzen
Für CI/CD geeignet – Authentifizierung über eine Umgebungsvariable für automatisierte Pipelines
Auftragsstatus verfolgen, fehlgeschlagene Aufträge fortsetzen und Ergebnisse herunterladen
Maschinenlesbare JSON-Ausgabe für Skripte und Automatisierung
Auf GitHub ansehen

Häufige Fallstricke

„Unable to find next-intl locale“

Die Middleware entsprach der Anfrage nicht. Prüfen Sie: Befindet sich middleware.ts im Projektstamm? Schließt das matcher-Muster statische Dateien korrekt aus? Ist die Locale in Ihrer Routing-Konfiguration enthalten?

Unerwartetes dynamisches Rendering

setRequestLocale(locale) fehlt auf einer Seite oder in einem Layout. Ohne diesen Aufruf verwendet next-intl Header/Cookies zur Erkennung der Locale, was dynamisches Rendering erzwingt und statische Erzeugung verhindert.

Parallele Routen funktionieren mit i18n nicht

Parallele Routen (@modal) und abfangende Routen ((.)photo) weisen bekannte Unvereinbarkeiten mit dem dynamischen Segment [locale] auf. Verwenden Sie für diese erweiterten Routing-Muster als Behelfslösung Middleware-basiertes Routing.

Beim Sprachwechsel geht die aktuelle Route verloren

Behalten Sie beim Wechseln der Locale den aktuellen Pfadnamen mit usePathname() bei und ersetzen Sie nur das Locale-Segment. Gehen Sie bei dynamischen Routenparametern vorsichtig vor: Sie müssen für die neue Locale erneut aufgelöst werden.

Empfohlene Dateistruktur

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

Auch übersetzen:

i18n Agent jetzt testen

Legen Sie Ihre Übersetzungsdatei hier ab

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

oder zum Auswählen klicken

Zielsprachen

Keine Registrierung erforderlichSofortiges Angebot

Locale-Fallback mit next-intl-localechain

Fehlt ein Übersetzungsschlüssel in einer regionalen Locale wie pt-BR, wechselt next-intl direkt zur Standard-Locale, statt zuerst die übergeordnete Locale pt zu prüfen.

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`),
});

In unserem Leitfaden zu Locale-Fallbacks finden Sie die vollständige Liste unterstützter Frameworks und 75 integrierter Ketten. Learn more →

Häufig gestellte Fragen