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 #

sh
npm install @lingo.dev/locale-router@0.2.1
ts
import { 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 #

ts
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 pravidlyVý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:

ts
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 #

ts
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.