Правила URL для локалей
Задавайте префиксы локалей, учитывайте языковые предпочтения и определяйте перенаправления и альтернативные пути без привязки к фреймворку.
Для локализованных URL нужны единые правила: какие языки поддерживаются, как они представлены в путях и куда направлять читателя, если в пути нет префикса. @lingo.dev/locale-router принимает эти решения с помощью встроенного Intl. Сервер отправляет перенаправление, а приложение загружает выбранный каталог.
Задайте поддерживаемые локали и слаги #
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" },
});Локаль pt-BR обозначает бразильский вариант португальского, а br — лишь её слаг в URL. Если не задать другое значение, слагом будет тег локали в нижнем регистре. Используйте корректные теги, выбирайте локаль по умолчанию из поддерживаемых и задавайте уникальные слаги в нижнем регистре. Конструктор проверяет не все возможные конфликты в конфигурации.
createLocaleRouter<L extends string>(locales, options) принимает массив локалей только для чтения и возвращает LocaleRouter<L>. Обязательно укажите defaultLocale, а exclude и slugs — по желанию. Исключения сопоставляются с первым сегментом пути. Если первый сегмент начинается с _ или содержит ., путь тоже исключается. Так внутренние пути и пути к файлам остаются вне локализации.
Определите перенаправление для URL без префикса #
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:
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 для других языков #
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 локали по умолчанию, поэтому результаты этих двух подходов не взаимозаменяемы.