Eine Next.js-Anwendung mit App Router übersetzen

Jede Seite unter einem Sprachpräfix bereitstellen, Pfade ohne Präfix weiterleiten und übersetzte Server- und Client-Komponenten mit @lingo.dev/react-next rendern.

Im App Router hat jede Sprache ihr eigenes URL-Präfix – auch die Quellsprache: Die Seiten werden unter /en/pricing und /de/pricing aufgerufen. @lingo.dev/react-next liest die Sprache aus einem app/[locale]-Routensegment, lädt den zugehörigen Katalog auf dem Server und stellt Server- und Client-Komponenten dieselben Texte bereit. In dieser Anleitung ergänzt du eine englische Anwendung um Deutsch und Französisch.

Verwende Next.js 16 oder neuer mit React 19; die Einstiegspunkte lesen die Sprache über next/root-params aus. Installiere die Pakete:

sh
npm install @lingo.dev/react@1.22.0 @lingo.dev/react-next@1.22.0 @lingo.dev/locale-router@0.3.0
npm install --save-dev @lingo.dev/cli@latest

Sprachen definieren #

Erstelle i18n.ts neben app/ (src/i18n.ts, wenn die Anwendung src/ verwendet):

ts
import { createLocaleRouter } from "@lingo.dev/locale-router";

export const locales = createLocaleRouter(["en", "de", "fr"] as const, { defaultLocale: "en", exclude: ["api"] });

export const localePath = (pathname: string, locale: string) =>
  locales.prefix(pathname, locales.toLocale(locale) ?? locales.defaultLocale);

Liste die Sprachen in .lingo/config.json auf und gib die Quellsprache als defaultLocale an. exclude legt fest, welche ersten Pfadsegmente kein Präfix erhalten, etwa Routenhandler unter app/api/. Übergib kein slugs: Das URL-Segment jeder Sprache muss ihrem kleingeschriebenen Sprach-Tag entsprechen (/pt-br für pt-BR), da getLingo() die Sprache allein aus diesem Segment ableitet. Bei einem benutzerdefinierten Slug löst der Provider einen Fehler aus, der den Slug nennt. Der Proxy sowie die Server- und Client-Komponenten importieren diese Datei. Halte sie daher frei von weiteren Importen.

Pfade ohne Präfix weiterleiten #

Erstelle proxy.ts neben app/:

ts
import { lingoProxy } from "@lingo.dev/react-next/app/proxy";
import { locales } from "./i18n";

export const proxy = lingoProxy(locales);

export const config = { matcher: ["/", "/((?!api|_next|.*\\..*).*)"] };

lingoProxy(locales) verarbeitet zwei Arten von Anfragen:

AnfrageAntwort
Ein erstes Segment, das eine Sprache anders als über ihren Slug angibt, etwa /DE/about, /de-AT oder /de_DE301 zur kanonischen Adresse.
Ein lokalisierter Pfad ohne Sprachangabe, etwa /about307 zur anhand von Accept-Language ausgehandelten Sprache, mit Cache-Control: private, no-store und Vary: Accept-Language.
Alles andereundefined.

Bei Weiterleitungen bleiben die Abfragezeichenfolge und basePath der Anwendung erhalten. Next.js liest den Matcher beim Build aus. Gib ihn deshalb als Literal an und halte seinen api mit exclude synchron. Hat die Anwendung bereits einen Proxy, rufe zuerst lingoProxy auf und fahre mit deiner eigenen Logik fort, wenn der Aufruf undefined zurückgibt. middleware.ts ist dieselbe Datei unter ihrem früheren Namen. Benenne sie in proxy.ts und ihre Funktion in proxy um.

Routen unter das Sprachsegment verschieben #

Verschiebe das Stammlayout und alle Seiten eine Ordnerebene tiefer nach app/[locale]/. app/[locale]/layout.tsx wird zum Stammlayout; danach gibt es kein app/layout.tsx mehr. Routenhandler unter app/api/, globals.css, Symbole, robots.ts und sitemap.ts bleiben, wo sie sind. Entferne alle i18n-Schlüssel aus next.config; der App Router liest sie nicht.

tsx
// app/[locale]/layout.tsx
import type { ReactNode } from "react";
import { getLingo, LingoAppProvider, lingoStaticParams } from "@lingo.dev/react-next/app/server";
import { locales } from "@/i18n";
import "../globals.css";

export function generateStaticParams() {
  return lingoStaticParams(locales);
}

export default async function RootLayout({ children }: { children: ReactNode }) {
  const l = await getLingo();
  return (
    <html lang={l.locale} dir={l.direction}>
      <body>
        <LingoAppProvider locales={locales}>{children}</LingoAppProvider>
      </body>
    </html>
  );
}

lingoStaticParams gibt pro Sprache ein { locale } zurück, sodass beim Build jede Seite einmal pro Sprache vorgerendert wird. Für eine Sprache, die nicht in der Liste steht, gibt LingoAppProvider einen 404-Fehler zurück. Füge kein export const dynamicParams = false hinzu: Next.js lehnt es ab, wenn cacheComponents aktiviert ist.

Server- und Client-Komponenten übersetzen #

Server-Komponenten, Seiten, Layouts und generateMetadata rufen await getLingo() aus @lingo.dev/react-next/app/server auf. Client-Komponenten rufen useLingo() aus @lingo.dev/react auf; LingoAppProvider stellt ihnen die Sprache und den Katalog bereit. Bei beiden Komponentenarten musst du die Sprache nicht weiterreichen.

tsx
// app/[locale]/page.tsx
import { getLingo } from "@lingo.dev/react-next/app/server";

export default async function Home() {
  const l = await getLingo();
  return <h1>{l.text("Welcome", { context: "Heading of the start page" })}</h1>;
}

Eine Server-Komponente kann l als Prop von ihrer übergeordneten Server-Komponente erhalten. Übergib aber niemals l an eine Client-Komponente: Funktionen lassen sich nicht vom Server an den Client übertragen. Ein Aufruf von getLingo() außerhalb von app/[locale]/ löst einen Fehler aus, weil kein [locale]-Segment gefunden wird.

Metadaten hinzufügen #

tsx
import { getLingo, lingoMetadata } from "@lingo.dev/react-next/app/server";
import { locales } from "@/i18n";

export async function generateMetadata() {
  const l = await getLingo();
  return {
    title: l.text("Pricing", { context: "Title of the pricing page" }),
    ...(await lingoMetadata({ locales, pathname: "/pricing", origin: "https://example.com" })),
  };
}

lingoMetadata({ locales, pathname, origin, ogLocale? }) gibt alternates.canonical, alternates.languages für jede Sprache plus x-default sowie openGraph.url und openGraph.locale zurück. Übergib den Seitenpfad ohne Sprachpräfix, Abfragezeichenfolge oder Fragment; bei einer dynamischen Route wird er aus den Routenparametern zusammengesetzt. Ersetze den Ursprung aus dem Beispiel durch den Ursprung deiner Website. URL-Richtlinie für Sprachen erläutert lingoHead, das die Werte erzeugt, sowie die Überschreibung mit ogLocale.

Füge jedem internen Link mit localePath("/pricing", l.locale) aus i18n.ts das passende Präfix hinzu. l.locale ist eine einfache Zeichenfolge. Deshalb schränkt localePath sie auf eine der Sprachen des Routers ein, bevor locales.prefix das Präfix hinzufügt. Ein Link ohne Präfix landet beim Proxy, der zur Sprache des Browsers statt zur Sprache der Seite weiterleitet. Dasselbe gilt für redirect(), router.push() und Formularaktionen, die einen Pfad angeben.

tsx
"use client";

import Link from "next/link";
import { useLocaleSwitch } from "@lingo.dev/react-next/app/client";
import { locales } from "@/i18n";

export function LocaleSwitcher() {
  const options = useLocaleSwitch(locales);
  return (
    <nav aria-label="Language">
      {options.map((option) => (
        <Link key={option.locale} href={option.href} hrefLang={option.locale} aria-current={option.current ? "page" : undefined}>
          {option.label}
        </Link>
      ))}
    </nav>
  );
}

useLocaleSwitch(locales) gibt pro Sprache ein { locale, label, href, current } zurück: die aktuelle Seite in dieser Sprache, den Namen der Sprache in der Sprache selbst und die Angabe, ob sie aktuell ausgewählt ist. Die Abfragezeichenfolge wird erst nach der Hydrierung hinzugefügt. So bleibt eine Seite, die die Sprachauswahl rendert, statisch. Beim Aufrufen eines Links wird das Layout neu gerendert und lädt den Katalog der neuen Sprache.

Kataloge extrahieren und laden #

Der Server liest locales/<locale>.jsonc mithilfe von fs aus dem Ordner, in dem next ausgeführt wird. Belasse i18n.messagesPath deshalb beim Standardwert locales. Er verwirft verwaiste Einträge und liest die Datei bei jeder Anfrage erneut ein. Dadurch stellt next dev einen bearbeiteten Katalog bereits bei der nächsten Anfrage bereit. Fehlt die Datei, wird ein leerer Katalog verwendet; während der Entwicklung erscheint zusätzlich eine Warnung. Eine fehlerhaft formatierte Datei oder ein Wert, der keine Zeichenfolge ist, löst einen Fehler aus, der die Datei nennt. Im Produktivbetrieb wird für die Quellsprache kein Katalog an den Browser gesendet, da ihr Text als Rückfallwert dient.

Wenn app/ im Projektstamm liegt und kein src/-Ordner vorhanden ist, setze "i18n": { "src": "." } in .lingo/config.json, damit die Extraktion app/ und components/ durchsucht. Die Extraktion überspringt node_modules und Ordner, deren Namen mit einem Punkt beginnen, etwa .next. Für eine neue Konfiguration:

sh
npx lingo init --source en --targets de,fr --files 'locales/en.jsonc' --yes
npx lingo extract --src .
npx lingo login
npx lingo link
npx lingo push --backfill-missing --wait

Setze i18n.src nach init, da dieser Schritt den Abschnitt i18n neu schreibt. In einem Monorepo liegt .lingo/config.json im Repository-Stamm; seine Pfade beziehen sich auf diesen Ordner. Deshalb setzt sich messagesPath aus dem App-Ordner und locales zusammen, etwa apps/web/locales. Siehe dazu die i18n-Zuordnung benannter Apps unter CLI-Konfiguration. Der Server liest locales/ weiterhin aus dem Ordner der App selbst.

Öffne nach next build und next start die Adresse / und stelle sicher, dass sie zu einer Sprache weiterleitet. Öffne anschließend /de und kontrolliere den deutschen Text im HTML.

Laufzeit #

Vorgerenderte Seiten funktionieren auf jedem Host. Eine bei Bedarf gerenderte Seite liest ihren Katalog vom Datenträger und benötigt deshalb die Node.js-Laufzeit. Cloudflare Workers und die Edge-Laufzeit können den Katalog nicht lesen.

Exporte #

EinstiegspunktExporte
@lingo.dev/react-next/app/servergetLingo(), LingoAppProvider, lingoMetadata(options), lingoStaticParams(locales).
@lingo.dev/react-next/app/clientuseLocaleSwitch(locales) und der Typ LocaleOption.
@lingo.dev/react-next/app/proxylingoProxy(locales).

Nach der Installation des Pakets können Programmieragenten der Anleitung in lingo agent-guide react-next-app folgen und für die Migration von next-intl lingo agent-guide react-next-migrate nutzen. Siehe Mit einem Programmieragenten einrichten.