Skip to Content

Localized routing

Match and generate localized paths, slugs, route aliases, and locale domains safely.

Import route helpers from @puzzle-ui/i18n/routing:

import { createLocalizedRouting } from "@puzzle-ui/i18n/routing";

const routing = createLocalizedRouting({
  registry: i18n.registry,
  prefixDefaultLocale: false,
  basePath: "/docs",
  routes: {
    product: {
      en: "/products/:id",
      nl: {
        path: "/producten/:slug",
        aliases: ["/item/:slug"],
      },
    },
  },
  origins: {
    en: "https://en.example.com",
    nl: "https://nl.example.com",
  },
});

routing.match("/docs/nl/about?tab=profile#bio");
routing.localize("/docs/about?tab=profile#bio", "nl");
routing.alternatePaths("/docs/about");

const route = routing.matchRoute("/docs/nl/item/42?ref=home");
const dutchProduct = routing.localizeRoute("product", "nl", { slug: "42" });
const productLinks = routing.alternateRoutePaths("product", { id: "42" });

match returns the locale, unprefixed pathname, search, hash, and whether a supported locale prefix was found. localize preserves query and hash values. Route IDs and localizeRoute locales are inferred from the route map. Every route must define a path for every locale. Route parameters are whole-segment :name patterns; parameter names may differ by locale and are mapped by segment position.

matchRoute returns the matched route ID, parameters, alias status, canonical path, and an optional redirectTo target. It does not perform redirects; delegate redirect responses to the framework. alternateRoutePaths creates one URL per locale. Configured origins must be bare HTTP(S) origins without credentials or paths; generated links use the target locale's origin and omit locale prefixes. Absolute URLs are matched only against configured origins.

Optional and catch-all parameters are not supported. External and protocol-relative inputs, malformed escapes, traversal, and encoded path-separators are rejected. Duplicate separators and unsafe base paths are rejected as well. If basePath is configured, matching inputs must be under that path and generated URLs include it. Unmapped paths retain the legacy prefix-based behavior.

Redirect targets are returned as data only. The package does not execute redirects; pass a validated redirectTo to your framework's redirect API and keep external destinations out of that boundary. Queries and fragments are preserved but never included in SEO canonical paths or route diagnostics.