Skip to Content

Locale registry and resolution

Define supported BCP 47 locales and resolve a request locale predictably.

createLocaleRegistry validates locale tags, aliases, defaults, and explicit fallbacks. Tags are canonicalized using Intl.getCanonicalLocales.

import { createLocaleRegistry, resolveLocale } from "@puzzle-ui/i18n";

const registry = createLocaleRegistry({
  locales: [
    { locale: "en", aliases: ["en-US"] },
    { locale: "nl" },
    { locale: "fr-CA", fallbacks: ["fr"] },
    { locale: "fr" },
  ],
  defaultLocale: "en",
  fallbackLocale: "nl",
});

const result = resolveLocale({
  registry,
  explicit: "fr-CA",
  urlLocale: "nl",
  cookie: "en",
  acceptLanguage: "fr-CA,fr;q=0.8,en;q=0.6",
});

Resolution priority is explicit input, URL locale, user preference, cookie, Accept-Language, browser locale, then the configured default. Invalid request values are skipped. The returned source identifies the winner.

fallbackChain(locale) includes the selected locale, its configured fallback chain, a supported base language when available, the fallback locale, and the default locale without duplicates.