Pravidla pro jazykové varianty URL
Nastavte jazykové prefixy, vyhodnocujte jazykové preference a rozhodujte o přesměrování i alternativních cestách nezávisle na frameworku.
Lokalizované URL vyžadují jednotná pravidla: které jazyky jsou k dispozici, jak se zapisují do cest a kam má cesta bez prefixu čtenáře přesměrovat. @lingo.dev/locale-router o tom rozhoduje pomocí nativního Intl. Server odešle přesměrování a aplikace načte zvolený katalog.
Definujte podporované jazyky a slugy #
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" },
});Jazyk pt-BR označuje brazilskou portugalštinu; br je pouze jeho slug v URL. Pokud nenastavíte vlastní slugy, použijí se jazykové značky převedené na malá písmena. Používejte platné značky, výchozí jazyk ze sady podporovaných jazyků a jedinečné slugy psané malými písmeny. Konstruktor nekontroluje všechny možné konflikty v konfiguraci.
createLocaleRouter<L extends string>(locales, options) přijímá pole jazyků jen pro čtení a vrací LocaleRouter<L>. defaultLocale je povinné; exclude a slugs jsou nepovinné. Výjimky se vyhodnocují podle prvního segmentu cesty. Z lokalizace se vyloučí také cesty, jejichž první segment začíná na _ nebo obsahuje .. Interní cesty a cesty k souborům tak zůstávají mimo lokalizaci.
Rozhodněte o přesměrování URL bez prefixu #
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);
}Výsledkem je https://example.com/de/account?tab=billing#details. Preference švýcarské němčiny se přiřadí k podporované němčině. Pomocná funkce vrátí novou URL; neodesílá odpověď HTTP ani nenastavuje soubor cookie. Server zvolí stavový kód a odešle cílovou adresu přesměrování. Skutečný požadavek HTTP neobsahuje fragment z prohlížeče, přestože pomocná funkce pro práci s URL zachová fragment, který jí předáte.
Pokud má mít uložená preference přednost, ověřte její jazykovou značku pomocí toLocale a výsledek předejte jako nepovinný třetí argument funkce redirect. Nepředávejte libovolný řetězec jako podporovaný jazyk.
Prohlížejte a sestavujte cesty #
| Volání s výše uvedenými pravidly | Výsledek |
|---|---|
locales.toLocale("pt_BR") | "pt-BR". Podtržítka se normalizují před hledáním přesné shody jazykové značky. |
locales.toLocale("br") | undefined. Slug v URL není jazyková značka. |
locales.split("/br/account") | { locale: "pt-BR", rest: "/account" }. |
locales.isLocalized("/account") | true. Znamená to, že cestu lze lokalizovat, nikoli že už má prefix. |
locales.prefix("/account", "de") | "/de/account". |
locales.prefix("/", "de") | "/de". |
locales.prefix("/api/status", "de") | "/api/status", beze změny. |
locales.canonical("/DE/account") | "/de/account". |
split vrací undefined, pokud nerozpozná slug v prvním segmentu. Metodám pro práci s cestami předávejte samotnou cestu, nikoli řetězec s parametry dotazu nebo fragmentem.
prefix a alternates očekávají cestu bez prefixu. Chcete-li změnit jazyk cesty /br/account na němčinu, rozdělte ji a předejte rest:
const current = locales.split("/br/account");
const germanPath = current ? locales.prefix(current.rest, "de") : undefined;Výsledkem je /de/account. Přidáte-li prefix přímo k původní cestě, může vzniknout druhý jazykový segment.
Vyhodnocujte jazykové preference #
negotiate(acceptLanguage: string | null): L seřadí preference s kladnou hodnotou kvality podle této hodnoty a postupně je zkouší. U každé preference nejprve hledá přesnou shodu jazykové značky a poté shodu s podporovaným jazykem. Pokud stejný jazyk sdílí více podporovaných regionálních variant, může o výběru náhradní varianty rozhodnout jejich pořadí v konfiguraci.
Neplatné hodnoty kvality a preference s nulovou kvalitou se vyřadí. Neplatné značky nevedou ke shodě a zástupný znak nenahrazuje výchozí pravidla. Pokud žádná preference neodpovídá, metoda vrátí defaultLocale. Jazyk se tedy vybírá podle uvedených preferencí, nikoli podle geolokace.
Řešte kanonizaci odděleně od přesměrování cest bez prefixu #
canonical(pathname): string | undefined navrhne normalizovaný slug pro rozpoznaný první segment, který připomíná jazykovou značku. Nejde o univerzální generátor kanonických URL. redirect vrací undefined pro cesty, které už mají prefix, pro vyloučené cesty a pro cesty, u nichž může canonical navrhnout opravu.
Pokud vaše aplikace vyžaduje normalizaci pomocí /DE/account, řešte ji samostatně. Server může před odesláním zvoleného přesměrování nahradit cestu v kopii URL požadavku a zachovat přitom parametry dotazu. Middleware TanStack vyhodnocuje jazykové preference pro cesty bez prefixu, ale tento samostatný krok normalizace neprovádí.
Generujte URL pro další jazyky #
const links = locales.alternates("/account").map(({ locale, pathname }) => ({
hrefLang: locale,
href: new URL(pathname, "https://example.com").href,
}));Místo ukázkové hodnoty použijte důvěryhodný origin webu. alternates vrací jednu položku { locale, pathname } pro každý podporovaný jazyk a navíc x-default odkazující na cestu výchozího jazyka. Položka pro jazyk pt-BR používá /br/account; výchozí anglická položka podle těchto pravidel používá /en/account.
Volající tyto položky vykresluje jako metadata. Metadata hlavičky TanStack doplňují tato pravidla o pole pro kanonickou URL a Open Graph. Adaptér Next Pages se řídí odlišnými pravidly Next pro URL výchozího jazyka, proto jejich výstupy nezaměňujte.