Eine Next.js-Pages-Anwendung übersetzen
Lade die übersetzten Texte einer Seite, rendere sie über den Pages-Wrapper und ergänze einen Sprachumschalter sowie Links zu alternativen Sprachversionen.
Eine Next.js-Pages-Route ermittelt bereits die Sprache der jeweiligen Anfrage. @lingo.dev/react-next nutzt diese Sprache, um React-Texte bereitzustellen. So bleiben Seitendaten und übersetzte Texte zusammen. Dieses Beispiel rendert eine Über-uns-Seite auf Englisch und Französisch und behält die Routenauswahl auch dann bei, wenn die übersetzte JSONC-Datei ihre Metadaten verloren hat.
Verwende eine bestehende Pages-Anwendung mit React 19. Das Paket deklariert Next.js 13+ und React 18/19 als Peer-Abhängigkeiten, der aktuelle Laufzeit-Provider nutzt jedoch die Context-Kurzschreibweise von React 19. Das Paket exportiert /pages, /pages/client und /pages/server; es bietet weder einen Root-Export noch einen Einstiegspunkt für den App Router.
Sprachen und App-Wrapper konfigurieren #
npm install @lingo.dev/react@1.17.1 @lingo.dev/react-next@1.17.1
npm install @lingo.dev/spec@1.17.1 jsonc-parser
npm install --save-dev @lingo.dev/cli@latestErgänze i18n in deiner bestehenden next.config.mjs und behalte die übrigen Einstellungen bei:
export default {
i18n: { locales: ["en", "fr"], defaultLocale: "en" },
};Umschließe die Anwendung in pages/_app.tsx mit dem Wrapper:
import type { AppProps } from "next/app";
import { useRouter } from "next/router";
import { useEffect } from "react";
import { withLingoApp } from "@lingo.dev/react-next/pages/client";
function App({ Component, pageProps }: AppProps) {
const { locale, defaultLocale } = useRouter();
useEffect(() => {
document.documentElement.lang = locale ?? defaultLocale ?? "en";
}, [locale, defaultLocale]);
return <Component {...pageProps} />;
}
export default withLingoApp(App);Der Wrapper liest pageProps.__lingoMessages, ermittelt die aktive Sprache von Next und stellt LingoProvider bereit. Die eigenen i18n-Einstellungen von Next bestimmen die URL-Regeln; der Pfad für die Standardsprache Englisch hat normalerweise kein Präfix.
Die Seite erstellen und ihre Texte laden #
Füge zunächst die Funktion loadMatchedMessages aus Kataloge laden als lib/catalog.ts hinzu. Sie validiert JSONC mit Zeichenfolgenwerten und ordnet die Zielwerte den aktiven Quellschlüsseln zu.
Erstelle dann pages/about.tsx:
import { readFile } from "node:fs/promises";
import path from "node:path";
import type { GetStaticProps } from "next";
import { useLingo, type Messages } from "@lingo.dev/react";
import { loadMatchedMessages } from "../lib/catalog";
export const getStaticProps: GetStaticProps<{ __lingoMessages: Messages }> = async (ctx) => {
const locale = ctx.locale ?? ctx.defaultLocale ?? "en";
if (!["en", "fr"].includes(locale)) return { notFound: true };
const source = await readFile(path.join(process.cwd(), "locales/en.jsonc"), "utf8");
const target =
locale === "en" ? source : await readFile(path.join(process.cwd(), "locales", `${locale}.jsonc`), "utf8");
const messages = loadMatchedMessages(source, target, (entry) => {
const route = entry.metadata.src?.replace(/\.\w+(?::\d+)?$/, "");
return !route || route === "pages/about" || (!route.startsWith("pages/") && !route.startsWith("src/pages/"));
});
return { props: { __lingoMessages: messages } };
};
export default function About() {
const l = useLingo();
return <h1>{l.text("About us", { context: "About page heading" })}</h1>;
}Dieses Prädikat behält die Einträge der Seite sowie die Texte gemeinsam genutzter Komponenten bei. Es entfernt Dateiendungen und ältere Zeilennummernsuffixe aus den Quellmetadaten. Liegt die Seite unter src/pages/about.tsx, passe sowohl den Importpfad als auch den Routenvergleich entsprechend an.
Der benutzerdefinierte Loader schlägt bewusst fehl, wenn eine erforderliche Datei fehlt oder fehlerhaft ist. So kann ein Build den erwarteten französischen Katalog nicht unbemerkt durch den englischen Fallback ersetzen. Einzelne fehlende Zielschlüssel bleiben ungesetzt; für sie greift der normale Laufzeit-Fallback.
Extrahieren, übersetzen und beide Routen öffnen #
Führe npx lingo extract --src pages --source-locale en im Stammverzeichnis des Projekts aus. Für eine neue Lingo.dev-Projektkonfiguration verwende:
npx lingo init --source en --targets fr --files 'locales/en.jsonc' --yes
npx lingo login
npx lingo link
npx lingo push --backfill-missing --waitBehalte bei einem bereits konfigurierten Projekt die bestehende Verknüpfung und die übrigen Dateioptionen bei. Führe nach der Extraktion die üblichen Aktualisierungen für die vorhandenen Zielsprachen durch, rufe die Ergebnisse ab und sieh sie dir an. Füge anschließend fr hinzu und ergänze die fehlenden Übersetzungen, ohne die Quellrevision zu ändern. Kataloge laden beschreibt die Konfigurationsschritte, und Eine Sprache hinzufügen erklärt die erforderliche Reihenfolge. Wenn gemeinsam genutzte Komponenten außerhalb von pages liegen, extrahiere aus einem Verzeichnis, das alle Textaufrufe enthält. Alternativ kannst du sie in einer gemeinsamen src-Verzeichnisstruktur organisieren und --src src verwenden.
Führe nach dem Abrufen von locales/fr.jsonc den üblichen Next-Befehl für die Entwicklung oder den Build aus. Öffne /about und /fr/about. Die erste Route nutzt die englische Quelle, die zweite die französische Übersetzung für denselben Überschriftenschlüssel. Kontrolliere den tatsächlichen französischen Text und den Rückgriff auf die Quelle bei einem absichtlich fehlenden Eintrag.
Integriertes Laden statischer Props #
Wenn jede Sprachdatei korrekte @src- und @orphan-Metadaten enthält, kann die Server-Hilfsfunktion den oben verwendeten benutzerdefinierten getStaticProps ersetzen:
import { withLingoProps } from "@lingo.dev/react-next/pages/server";
export const getStaticProps = withLingoProps({ route: "pages/about" });withLingoProps({ route, handler? }) liest feste locales/<locale>.jsonc-Pfade relativ zum Arbeitsverzeichnis. Die Funktion filtert verwaiste Einträge und andere Seiten heraus. Quellen, die nicht zu Seiten gehören, sowie Einträge ohne @src behandelt sie als gemeinsam genutzt. Bei einer allgemeinen JSONC-Übersetzung bleiben @orphan-Markierungen erhalten, @src-Kommentare werden jedoch entfernt. Verwende für diese Ausgabe daher das obige Beispiel zur Zuordnung über Quellschlüssel; die Hilfsfunktion stellt keine Metadaten wieder her.
Fehlt eine Datei, wird {} zurückgegeben und im Entwicklungsmodus eine Warnung ausgegeben; eine vorhandene, aber ungültige Datei kann einen Fehler auslösen. Ein optionaler asynchroner Handler ergänzt Props oder gibt ein Weiterleitungs- bzw. Nicht-gefunden-Ergebnis zurück. Erfolgreiche Ergebnisse behalten Felder wie revalidate bei und ergänzen __lingoMessages. Die öffentlichen Typen verwenden den Kontext und die Ergebnisse statischer Props. Gehe daher nicht davon aus, dass beliebige serverseitige Anfrage-Handler denselben Vertrag erfüllen. Auch das Überschreiben des Katalogpfads über die CLI ändert dieses feste Loader-Verzeichnis nicht.
Dynamische statische Pfade erweitern #
Bei einer dynamischen Route erweitert die Server-Hilfsfunktion jeden Parametereintrag auf alle in Next konfigurierten Sprachen:
import { withLingoPaths } from "@lingo.dev/react-next/pages/server";
export const getStaticPaths = withLingoPaths(async () => [{ params: { slug: "refund-policy" } }], {
fallback: "blocking",
});Der Standard-Fallback ist "blocking"; false und true werden ebenfalls unterstützt. Die Erweiterung übersetzt keine Slugs und stellt nicht sicher, dass jeder Katalog die Texte der Route enthält.
Sprache wechseln und Links zu alternativen Sprachversionen hinzufügen #
Rendere einen Sprachumschalter unterhalb des App-Wrappers:
import { LingoHead, useLocaleSwitch } from "@lingo.dev/react-next/pages/client";
export function Languages() {
const switchLocale = useLocaleSwitch();
return (
<nav aria-label="Language">
<LingoHead baseUrl="https://example.com" />
<button onClick={() => switchLocale("en")}>English</button>
<button onClick={() => switchLocale("fr")}>Français</button>
</nav>
);
}Ersetze den Beispiel-Origin durch den absoluten Origin der Website in der Produktionsumgebung. LingoHead erzeugt Links zu alternativen Versionen für die konfigurierten Sprachen und x-default und lässt dabei das Präfix der Standardsprache weg. Canonical- oder Open-Graph-Metadaten werden nicht erzeugt. Sieh dir die resultierenden URLs im Hinblick auf deine Routen- und Query-Regeln an.
Der Callback für den Sprachwechsel schreibt NEXT_LOCALE mit einer Gültigkeit von einem Jahr unter / mit SameSite=Lax. Anschließend navigiert er mit dem Router von Next unter Verwendung des aktuellen asPath. Übergib wie oben die konfigurierten Sprachen; beliebige Eingaben werden nicht mit der Liste der unterstützten Sprachen abgeglichen.
Anfängliche Dokumentattribute setzen #
Setze die anfänglichen Attribute in pages/_document.tsx und behalte alle bestehenden Dokumentanpassungen bei:
import Document, { Html, Head, Main, NextScript } from "next/document";
import { createLingo } from "@lingo.dev/react";
export default class LocalizedDocument extends Document {
render() {
const locale = this.props.__NEXT_DATA__.locale ?? "en";
return (
<Html lang={locale} dir={createLingo(locale).direction}>
<Head />
<body>
<Main />
<NextScript />
</body>
</Html>
);
}
}withLingoApp setzt nach einem Sprachwechsel die Schreibrichtung und gibt für das erste Rendern ein Inline-RTL-Skript aus, setzt aber nicht lang. Der obige _app-Effekt aktualisiert lang während der Navigation; das benutzerdefinierte Dokument stellt beide anfänglichen Attribute bereit. Eine strenge Content-Security-Policy kann das Inline-Skript des Wrappers blockieren, und der Wrapper bietet keine Nonce-Option. Das benutzerdefinierte Dokument stellt die anfängliche Schreibrichtung unabhängig von diesem Skript bereit. Kontrolliere die Skriptrichtlinie der Anwendung auch während der Navigation.
Kontrolliere abschließend die Hydrierung mit demselben Katalog und expliziten Zeitangaben. Stelle sicher, dass ein Sprachwechsel die Texte und die Dokumentattribute gemeinsam ändert.