@lingo.dev/locale-router
v0.3.0
Published
URL and Accept-Language locale policy for a localized site: prefix, split, negotiate, alternates, redirect. Intl only.
Keywords
Readme
@lingo.dev/locale-router
URL and Accept-Language policy for a site that serves every page under a locale prefix (/de/pricing). One call turns your list of locales into the functions a server needs: recognise a prefix, add one, pick a locale from the browser's header, list the hreflang alternates of a page, and redirect a bare URL to its localized one. Pure string work on top of Intl; no runtime dependencies, no framework.
Getting started
import { createLocaleRouter } from "@lingo.dev/locale-router";
const LOCALES = ["en", "de", "fr", "pt-BR", "pt-PT"] as const;
export const locales = createLocaleRouter(LOCALES, {
defaultLocale: "en",
exclude: ["api"],
slugs: { "pt-BR": "pt" },
});
// In your request handler:
const url = new URL(request.url);
const canonical = locales.canonical(url.pathname);
if (canonical) return Response.redirect(new URL(`${canonical}${url.search}`, url), 301);
const target = locales.redirect(url, request.headers.get("accept-language"));
if (target) return Response.redirect(target, 302);
const locale =
locales.split(new URL(request.url).pathname)?.locale ?? locales.negotiate(request.headers.get("accept-language"));API
createLocaleRouter(locales, { defaultLocale, exclude?, slugs? }) returns a LocaleRouter.
A locale's address in a URL is its slug: slugs[locale] ?? locale.toLowerCase(). Give the most-read variant of a language the bare language ({ "pt-BR": "pt" }) and the rest keep their region (/pt-pt). The tag itself (/pt-BR) is never an address; canonical says where it goes.
| Method | Does |
| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| toLocale(tag) | The listed locale a tag names, matched case-insensitively after canonicalisation ("PT_br" → "pt-BR"), or undefined. |
| split(pathname) | { locale, rest } when the first segment is a slug, read case-insensitively ("/pt/docs" → { locale: "pt-BR", rest: "/docs" }), else undefined. A tag that is not a slug ("/pt-BR/docs") is not split. |
| isLocalized(pathname) | Whether a path takes a prefix: false for an excluded first segment, a segment starting with _, or one containing a dot (a file). |
| prefix(pathname, locale) | "/pricing" → "/pt/pricing", "/" → "/pt"; a path that is not localized comes back unchanged. |
| canonical(pathname) | The address a path is served at when its first segment names a locale by something other than its slug: a tag ("/pt-BR/docs" → "/pt/docs"), a wrong case ("/PT-pt" → "/pt-pt"), an underscore ("/pt_PT" → "/pt-pt"), a region not shipped ("/pt-AO" → "/pt"). undefined when the prefix already is the slug, the segment names no locale, or the path is not localized. |
| negotiate(acceptLanguage) | The listed locale the header asks for: q-values honoured, q=0 and unparseable q dropped, an exact match first, then the locale whose slug is the bare language, then the first listed locale of that language. Falls back to defaultLocale. |
| alternates(pathname) | One { locale, pathname } per listed locale, then x-default pointing at the default locale's path. Feed it to <link rel="alternate" hreflang>. |
| redirect(url, acceptLanguage, preferred?) | For a localized path whose first segment names no locale, a new URL prefixed with preferred ?? negotiate(acceptLanguage), search carried verbatim. Otherwise undefined. |
The router also keeps what it was built from: locales, the list as given, and defaultLocale.
There is no resolve: locales.split(pathname)?.locale ?? locales.negotiate(acceptLanguage) says it in one line.
Head tags
import { lingoHead } from "@lingo.dev/locale-router";
const { meta, links } = lingoHead({ router: locales, locale: "de", pathname: "/about", origin: "https://example.com" });lingoHead({ router, locale, pathname, origin, ogLocale? }) returns { meta, links }: a canonical link, one alternate per locale plus x-default, og:url and og:locale. Pass an unprefixed pathname without query or hash. The platform locale (de_DE) derives from Intl.Locale.maximize(); pass ogLocale: { "es-419": "es_LA" } where a platform spells it otherwise. A trailing slash the router kept is dropped.
Why Intl and not @lingo.dev/locales
@lingo.dev/locales answers questions about any BCP 47 tag and loads the IANA registry to do it; a router only needs to match a handful of tags you already chose, which Intl.getCanonicalLocales and Intl.Locale do at zero bytes.
