URL-Richtlinie für Sprachen
Definiere Sprachpräfixe, gleiche Sprachpräferenzen ab und bestimme Weiterleitungen und alternative Pfade – unabhängig vom Framework.
Eine lokalisierte URL braucht eine einheitliche Richtlinie: Welche Sprachen sind verfügbar, wie erscheinen sie in Pfaden und wohin führt ein Pfad ohne Sprachpräfix? @lingo.dev/locale-router trifft diese Entscheidungen mit nativem Intl. Dein Server sendet die Weiterleitung, und deine Anwendung lädt den ausgewählten Katalog.
Unterstützte Sprachen und Slugs definieren #
npm install @lingo.dev/locale-router@0.2.1import { createLocaleRouter } from "@lingo.dev/locale-router";
const locales = createLocaleRouter(["en", "de", "pt-BR"] as const, {
defaultLocale: "en",
exclude: ["api", "assets"],
slugs: { "pt-BR": "br" },
});Die Sprache pt-BR steht für brasilianisches Portugiesisch; br ist lediglich ihr URL-Slug. Ohne explizite Anpassung dienen Sprachkennungen in Kleinbuchstaben als Slugs. Verwende gültige Kennungen, eine Standardsprache aus den unterstützten Sprachen und eindeutige Slugs in Kleinbuchstaben. Der Konstruktor erkennt nicht alle Konfigurationskonflikte.
createLocaleRouter<L extends string>(locales, options) akzeptiert ein schreibgeschütztes Array von Sprachen und gibt LocaleRouter<L> zurück. defaultLocale ist erforderlich; exclude und slugs sind optional. Ausschlüsse werden mit dem ersten Segment des URL-Pfads abgeglichen. Beginnt dieses Segment mit _ oder enthält es ., wird der Pfad ebenfalls ausgeschlossen. So bleiben interne Pfade und Dateipfade von der Lokalisierung ausgenommen.
Weiterleitung für eine URL ohne Sprachpräfix bestimmen #
const target = locales.redirect(
new URL("https://example.com/account?tab=billing#details"),
"de-CH,de;q=0.8,en;q=0.5",
);
if (target) {
console.log(target.href);
}Das ergibt https://example.com/de/account?tab=billing#details. Die Präferenz für Schweizer Deutsch wird der unterstützten Sprache Deutsch zugeordnet. Die Hilfsfunktion gibt eine neue URL zurück; sie sendet weder eine HTTP-Antwort noch setzt sie ein Cookie. Dein Server wählt den Status und sendet die Zieladresse. Eine tatsächliche HTTP-Anfrage enthält das URL-Fragment des Browsers nicht. Die URL-Hilfsfunktion behält jedoch ein Fragment bei, wenn es ihr übergeben wird.
Soll eine gespeicherte Präferenz Vorrang haben, validiere ihre Sprachkennung mit toLocale und übergib das Ergebnis als optionales drittes Argument an redirect. Übergib keine beliebige Zeichenfolge als unterstützte Sprache.
Pfade untersuchen und erstellen #
| Aufruf mit der obigen Richtlinie | Ergebnis |
|---|---|
locales.toLocale("pt_BR") | "pt-BR". Unterstriche werden vor dem exakten Abgleich der Sprachkennung normalisiert. |
locales.toLocale("br") | undefined. Ein URL-Slug ist nicht die Sprachkennung. |
locales.split("/br/account") | { locale: "pt-BR", rest: "/account" }. |
locales.isLocalized("/account") | true. Das bedeutet, dass der Pfad für die Lokalisierung infrage kommt – nicht, dass er bereits ein Präfix hat. |
locales.prefix("/account", "de") | "/de/account". |
locales.prefix("/", "de") | "/de". |
locales.prefix("/api/status", "de") | "/api/status", unverändert. |
locales.canonical("/DE/account") | "/de/account". |
split gibt undefined zurück, wenn der Slug im ersten Segment nicht erkannt wird. Übergib den Pfadmethoden nur den URL-Pfad, keine Zeichenfolge mit Abfrageparametern oder einem Fragment.
prefix und alternates erwarten einen Pfad ohne Präfix. Um /br/account auf Deutsch umzustellen, zerlege den Pfad und übergib rest:
const current = locales.split("/br/account");
const germanPath = current ? locales.prefix(current.rest, "de") : undefined;Das Ergebnis ist /de/account. Wenn du dem ursprünglichen Pfad direkt ein Präfix voranstellst, kann ein zweites Sprachsegment entstehen.
Sprachpräferenzen abgleichen #
negotiate(acceptLanguage: string | null): L sortiert Präferenzen mit positivem Qualitätswert nach diesem Wert und geht sie der Reihe nach durch. Für jede Präferenz sucht die Methode zuerst nach einer exakten Übereinstimmung der Sprachkennung, dann nach einer passenden unterstützten Sprache. Gehören mehrere unterstützte regionale Sprachvarianten zur selben Sprache, kann ihre konfigurierte Reihenfolge bestimmen, welche Variante als Ausweichoption gewählt wird.
Ungültige Qualitätswerte und Präferenzen mit dem Qualitätswert 0 werden verworfen. Ungültige Kennungen ergeben keine Übereinstimmung, und ein Platzhalter ersetzt nicht die Standardrichtlinie. Passt keine Präferenz, gibt die Methode defaultLocale zurück. Die Sprache wird anhand der angegebenen Präferenzen ausgewählt, nicht anhand des geografischen Standorts.
Kanonisierung und Weiterleitungen für Pfade ohne Sprachpräfix getrennt behandeln #
canonical(pathname): string | undefined schlägt einen normalisierten Slug vor, wenn das erste Segment einer Sprachkennung ähnelt und erkannt wird. Die Funktion ist kein allgemeiner Generator für kanonische URLs. redirect gibt undefined zurück, wenn Pfade bereits ein Präfix haben, ausgeschlossen sind oder canonical eine Korrektur für sie vorschlagen kann.
Behandle die Normalisierung von /DE/account separat, wenn deine Anwendung sie benötigt. Ein Server kann den Pfad in einer Kopie der Anfrage-URL ersetzen und dabei die Abfrageparameter beibehalten, bevor er die gewählte Weiterleitung sendet. Die Middleware von TanStack übernimmt den Sprachabgleich für Pfade ohne Präfix, fügt diesen separaten Normalisierungsschritt aber nicht hinzu.
URLs für alternative Sprachen erzeugen #
const links = locales.alternates("/account").map(({ locale, pathname }) => ({
hrefLang: locale,
href: new URL(pathname, "https://example.com").href,
}));Verwende den vertrauenswürdigen Ursprung der Website statt des Beispielwerts. alternates gibt für jede unterstützte Sprache ein { locale, pathname } zurück sowie x-default, das auf den Pfad der Standardsprache verweist. Der Spracheintrag für pt-BR verwendet /br/account; der Eintrag für die Standardsprache Englisch verwendet gemäß dieser Richtlinie /en/account.
Der aufrufende Code gibt diese als Metadaten aus. Die Head-Metadaten von TanStack ergänzen diese Richtlinie um Felder für kanonische URLs und Open Graph. Der Next-Pages-Adapter folgt der abweichenden URL-Richtlinie von Next für die Standardsprache. Verwende die Ausgaben der beiden daher nicht austauschbar.