Правила URL для локалей

Задавайте префиксы локалей, учитывайте языковые предпочтения и определяйте перенаправления и альтернативные пути без привязки к фреймворку.

Для локализованных URL нужны единые правила: какие языки поддерживаются, как они представлены в путях и куда направлять читателя, если в пути нет префикса. @lingo.dev/locale-router принимает эти решения с помощью встроенного Intl. Сервер отправляет перенаправление, а приложение загружает выбранный каталог.

Задайте поддерживаемые локали и слаги #

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" },
});

Локаль pt-BR обозначает бразильский вариант португальского, а br — лишь её слаг в URL. Если не задать другое значение, слагом будет тег локали в нижнем регистре. Используйте корректные теги, выбирайте локаль по умолчанию из поддерживаемых и задавайте уникальные слаги в нижнем регистре. Конструктор проверяет не все возможные конфликты в конфигурации.

createLocaleRouter<L extends string>(locales, options) принимает массив локалей только для чтения и возвращает LocaleRouter<L>. Обязательно укажите defaultLocale, а exclude и slugs — по желанию. Исключения сопоставляются с первым сегментом пути. Если первый сегмент начинается с _ или содержит ., путь тоже исключается. Так внутренние пути и пути к файлам остаются вне локализации.

Определите перенаправление для URL без префикса #

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);
}

Результат — https://example.com/de/account?tab=billing#details. Предпочтение швейцарского варианта немецкого сопоставляется с поддерживаемым немецким языком. Вспомогательная функция возвращает новый URL, но не отправляет HTTP-ответ и не устанавливает cookie. Сервер выбирает код состояния и отправляет адрес перенаправления. Реальный HTTP-запрос не содержит фрагмента URL из браузера, хотя вспомогательная функция сохраняет фрагмент, если он ей передан.

Если сохранённое предпочтение должно иметь приоритет, проверьте его тег локали с помощью toLocale и передайте результат третьим, необязательным аргументом redirect. Не передавайте произвольную строку в качестве поддерживаемой локали.

Проверяйте и создавайте пути #

Вызов с указанными выше правиламиРезультат
locales.toLocale("pt_BR")"pt-BR". Подчёркивания нормализуются до проверки точного совпадения локали.
locales.toLocale("br")undefined. Слаг в URL — не тег локали.
locales.split("/br/account"){ locale: "pt-BR", rest: "/account" }.
locales.isLocalized("/account")true. Это означает, что путь подходит для локализации, а не то, что у него уже есть префикс.
locales.prefix("/account", "de")"/de/account".
locales.prefix("/", "de")"/de".
locales.prefix("/api/status", "de")"/api/status", без изменений.
locales.canonical("/DE/account")"/de/account".

split возвращает undefined, если слаг в первом сегменте не распознан. Передавайте методам работы с путями только путь, без параметров запроса и фрагмента после решётки.

prefix и alternates ожидают путь без префикса. Чтобы переключить /br/account на немецкий, разделите путь и передайте rest:

ts
const current = locales.split("/br/account");
const germanPath = current ? locales.prefix(current.rest, "de") : undefined;

Результат — /de/account. Если добавить префикс прямо к исходному пути, в нём может появиться второй сегмент локали.

Учитывайте языковые предпочтения #

negotiate(acceptLanguage: string | null): L сортирует предпочтения с положительным весом по значению веса и перебирает их по порядку. Для каждого предпочтения сначала проверяет точное совпадение локали, затем — совпадение с поддерживаемым языком. Если несколько поддерживаемых региональных локалей используют один язык, выбор запасного варианта может зависеть от их порядка в конфигурации.

Некорректные значения веса и предпочтения с нулевым весом отбрасываются. Некорректные теги не дают совпадений, а подстановочный знак не заменяет правила по умолчанию. Если ни одно предпочтение не подошло, метод возвращает defaultLocale. Язык выбирается по указанным предпочтениям, а не по геолокации.

Обрабатывайте канонизацию отдельно от перенаправлений для путей без префикса #

canonical(pathname): string | undefined предлагает нормализованный слаг, если первый сегмент похож на локаль и распознан. Это не универсальный генератор канонических URL. redirect возвращает undefined для путей, в которых уже есть префикс, исключённых путей и путей, для которых canonical может предложить исправление.

Обрабатывайте нормализацию /DE/account отдельно, если она нужна приложению. Перед отправкой перенаправления сервер может заменить путь в копии URL запроса, сохранив параметры запроса. Промежуточный обработчик TanStack выбирает локаль для путей без префикса, но не выполняет этот отдельный шаг нормализации.

Создавайте URL для других языков #

ts
const links = locales.alternates("/account").map(({ locale, pathname }) => ({
  hrefLang: locale,
  href: new URL(pathname, "https://example.com").href,
}));

Вместо адреса из примера используйте доверенный базовый адрес сайта. alternates возвращает по одному { locale, pathname } для каждой поддерживаемой локали, а также x-default, указывающий на путь локали по умолчанию. При таких правилах запись для языка pt-BR использует /br/account, а запись для английского языка, выбранного по умолчанию, — /en/account.

Вызывающий код выводит эти значения как метаданные. Метаданные head в TanStack дополняют эти правила полями канонического URL и Open Graph. Адаптер Next Pages следует другим правилам Next для URL локали по умолчанию, поэтому результаты этих двух подходов не взаимозаменяемы.