@daanvandenbergh/i18nkit 1.0.0

package/dist/i18n/i18n.js

@@ -0,0 +1,254 @@
+/**
+ * The `I18n` class - the single public surface of i18nkit's core. A consumer constructs one
+ * instance from their locale config and authors + resolves every translation through it, so the
+ * instance's locale union `L` (inferred from the config) flows into every method and enforces
+ * 100% coverage at each call site.
+ *
+ * The class is a thin, config-bound facade over the pure functions in the sibling modules
+ * (`catalog`, `translate`, `detect`, `routing`), which stay independently testable and
+ * framework-free.
+ */
+import * as catalog from "./catalog.js";
+import * as detect from "./detect.js";
+import * as routing from "./routing.js";
+import * as text from "./translate.js";
+/** The default cookie name when the config does not override it. */
+const DEFAULT_COOKIE = "locale";
+/**
+ * A type-safe i18n instance bound to one locale set. Create it once and export it:
+ *
+ * ```ts
+ * export const i18n = new I18n({
+ *     locales: { en: { label: "English" }, nl: { label: "Nederlands", htmlLang: "nl", locale: "nl-NL" } },
+ *     default: "en",
+ * });
+ * export type Locale = keyof typeof i18n.locales; // "en" | "nl"
+ * ```
+ *
+ * @typeParam L - the locale union, inferred from the constructor's `locales` keys.
+ */
+export class I18n {
+    /** Every configured locale, fully resolved, keyed by code. `keyof this.locales` is the locale union. */
+    locales;
+    /** Every configured locale in declaration order - the order the picker lists them. */
+    list;
+    /** The fallback locale for detection/resolution (unknown cookie, unmatched `Accept-Language`). */
+    default;
+    /** The cookie name the picker writes and locale detection reads. */
+    cookie;
+    /** The absolute site origin for {@link hreflangAlternates}, or undefined if not configured. */
+    origin;
+    /** Path prefixes that are never localized. */
+    nonLocalizedPrefixes;
+    /** The URL scheme for the default locale (`"prefix-except-default"` or `"prefix-all"`). */
+    strategy;
+    /** Every locale code, cached for {@link uniform}. */
+    #codes;
+    /** The routing config passed to every routing helper. */
+    #routing;
+    /**
+     * Build an i18n instance.
+     *
+     * @param config - the locale set and options (see {@link I18nConfig}).
+     * @throws Error when `locales` is empty, `default` is not one of the configured locales, or two
+     *     locales resolve to the same case-insensitive `htmlLang`.
+     */
+    constructor(config) {
+        const codes = Object.keys(config.locales);
+        if (codes.length === 0) {
+            throw new Error("I18n: `locales` must declare at least one locale.");
+        }
+        if (!codes.includes(config.default)) {
+            throw new Error(`I18n: default locale "${config.default}" is not one of the configured locales (${codes.join(", ")}).`);
+        }
+        this.list = codes.map((code) => {
+            const info = config.locales[code];
+            const htmlLang = info.htmlLang ?? code;
+            return { code, label: info.label, htmlLang, locale: info.locale ?? htmlLang };
+        });
+        // URL routing matches locale segments case-insensitively (`/en-gb` resolves to `en-GB`), so
+        // two locales whose htmlLang differ only by case would share one URL prefix and leave one
+        // locale unreachable by URL. Fail fast at construction rather than fail silently at runtime.
+        const seenHtmlLang = new Map();
+        for (const entry of this.list) {
+            const key = entry.htmlLang.toLowerCase();
+            const clash = seenHtmlLang.get(key);
+            if (clash !== undefined) {
+                throw new Error(`I18n: locales "${clash}" and "${entry.code}" both resolve to htmlLang "${key}" (case-insensitive); each locale needs a distinct htmlLang.`);
+            }
+            seenHtmlLang.set(key, entry.code);
+        }
+        this.locales = Object.fromEntries(this.list.map((entry) => [entry.code, entry]));
+        this.default = config.default;
+        this.cookie = config.cookie ?? DEFAULT_COOKIE;
+        // Strip trailing slashes so a caller passing `origin: "https://x.com/"` does not yield a
+        // double slash in canonical/hreflang URLs (`https://x.com//pricing`), which harms SEO.
+        this.origin = config.origin?.replace(/\/+$/, "");
+        this.nonLocalizedPrefixes = config.nonLocalizedPrefixes ?? [];
+        this.strategy = config.strategy ?? "prefix-except-default";
+        this.#codes = codes;
+        this.#routing = {
+            locales: this.list,
+            default: this.default,
+            nonLocalizedPrefixes: this.nonLocalizedPrefixes,
+            strategy: this.strategy,
+            origin: this.origin,
+        };
+    }
+    // --- Authoring (type-level coverage enforcement) --------------------------------------------
+    /**
+     * Define a co-located catalog of copy. Every entry must carry a translation for every locale
+     * in `L`, or it is a compile error; the returned object keeps its precise literal type so a
+     * {@link Translator} can infer each parameterized entry's arguments. This is an identity
+     * function - all the work is in the type constraint.
+     *
+     * @typeParam C - the catalog literal, constrained to {@link LanguageTextCatalog}.
+     * @param catalog - the catalog object.
+     * @returns the same object, precisely typed.
+     */
+    defineTextCatalog(catalog) {
+        return catalog;
+    }
+    defineText(text) {
+        return text;
+    }
+    /**
+     * Build a {@link LanguageText} whose value is identical in every locale (a brand word, a
+     * symbol). Coverage is complete by construction.
+     *
+     * @param value - the string used for every locale.
+     * @returns a {@link LanguageText} for `L`.
+     */
+    uniform(value) {
+        return catalog.uniform(value, this.#codes);
+    }
+    // --- Resolution -----------------------------------------------------------------------------
+    /**
+     * Build a {@link Translator} bound to `locale` - the ergonomic path: bind once, resolve many.
+     *
+     * @param locale - the locale to bind.
+     * @returns a translator for that locale.
+     */
+    translator(locale) {
+        return text.createTranslator(locale);
+    }
+    /**
+     * Resolve one static text for a locale without binding a {@link Translator}. For parameterized
+     * text or repeated use, prefer {@link translator}.
+     *
+     * @param textValue - the {@link LanguageText} to resolve.
+     * @param locale - the locale to resolve against.
+     * @returns the string for that locale.
+     */
+    translate(textValue, locale) {
+        return text.translate(textValue, locale);
+    }
+    // --- Detection ------------------------------------------------------------------------------
+    /**
+     * Narrow an untrusted value (e.g. a cookie) to a valid locale, falling back to {@link default}.
+     *
+     * @param raw - the candidate value.
+     * @returns a guaranteed-valid locale.
+     */
+    resolveLocale(raw) {
+        return detect.resolveLocale(raw, this.list, this.default);
+    }
+    /**
+     * Pick the best locale from an HTTP `Accept-Language` header, falling back to {@link default}.
+     *
+     * @param header - the raw header value (or null/undefined).
+     * @returns the best supported locale.
+     */
+    matchAcceptLanguage(header) {
+        return detect.matchAcceptLanguage(header, this.list, this.default);
+    }
+    // --- Locale metadata ------------------------------------------------------------------------
+    /**
+     * The BCP-47 `<html lang>` subtag for a locale (e.g. `"nl"`).
+     *
+     * @param locale - the locale.
+     * @returns its `htmlLang`.
+     */
+    htmlLangFor(locale) {
+        return this.locales[locale]?.htmlLang ?? locale;
+    }
+    /**
+     * The full BCP-47 `Intl` formatting locale for a locale (e.g. `"nl-NL"`), for
+     * `new Intl.DateTimeFormat(i18n.intlLocaleFor(locale))`.
+     *
+     * @param locale - the locale.
+     * @returns its `Intl` locale.
+     */
+    intlLocaleFor(locale) {
+        return this.locales[locale]?.locale ?? this.htmlLangFor(locale);
+    }
+    // --- Routing (config-bound wrappers over the routing module) --------------------------------
+    /**
+     * The URL prefix for a locale: `""` for the default locale, `"/<htmlLang>"` otherwise.
+     *
+     * @param locale - the locale.
+     * @returns the leading URL segment.
+     */
+    prefixFor(locale) {
+        return routing.prefixFor(this.#routing, locale);
+    }
+    /**
+     * The locale a URL path segment denotes (via `htmlLang`), or null.
+     *
+     * @param segment - the first path segment, without slashes.
+     * @returns the locale, or null.
+     */
+    localeForSegment(segment) {
+        return routing.localeForSegment(this.#routing, segment);
+    }
+    /**
+     * Whether a pathname takes a locale prefix (i.e. is not under {@link nonLocalizedPrefixes}).
+     *
+     * @param pathname - the URL pathname.
+     * @returns true when the path is localized.
+     */
+    isLocalizedPath(pathname) {
+        return routing.isLocalizedPath(this.#routing, pathname);
+    }
+    /**
+     * Localize an internal href for a locale (`/pricing` -> `/nl/pricing`).
+     *
+     * @param href - the link target.
+     * @param locale - the active locale.
+     * @returns the localized href.
+     */
+    localizeHref(href, locale) {
+        return routing.localizeHref(this.#routing, href, locale);
+    }
+    /**
+     * Rewrite a pathname to another locale (used by the picker to switch pages).
+     *
+     * @param pathname - the current pathname.
+     * @param next - the locale to switch to.
+     * @returns the pathname in the target locale.
+     */
+    switchLocalePath(pathname, next) {
+        return routing.switchLocalePath(this.#routing, pathname, next);
+    }
+    /**
+     * Strip any locale prefix from a pathname (`/nl/x` -> `/x`).
+     *
+     * @param pathname - the current pathname.
+     * @returns the unprefixed pathname.
+     */
+    stripLocalePrefix(pathname) {
+        return routing.stripLocalePrefix(this.#routing, pathname);
+    }
+    /**
+     * Canonical + hreflang alternates for a page (requires `origin` in the config). A non-localized
+     * path yields a single canonical with only an `x-default`.
+     *
+     * @param path - the pathname (bare or already-locale-prefixed; it is reduced to the bare form).
+     * @param locale - the active locale.
+     * @returns the `{ canonical, languages }` alternates object.
+     * @throws Error when the config has no `origin`.
+     */
+    hreflangAlternates(path, locale) {
+        return routing.hreflangAlternates(this.#routing, path, locale);
+    }
+}

package/dist/i18n/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Public surface of the i18nkit core (the `.` entry). The star is the {@link I18n} class - a
+ * consumer constructs one instance and reaches every feature through it. The mapped-type
+ * vocabulary is exported for annotations, and the two locale-free resolvers (`createTranslator`,
+ * `translate`) are exported as escape hatches for resolving a text you already hold without an
+ * instance. Detection and routing are reached as `I18n` methods, not standalone, so there is one
+ * obvious way to do each.
+ */
+export { I18n, type LocaleOf } from "./i18n.js";
+export { createTranslator, translate } from "./translate.js";
+export type { I18nConfig, LanguageText, LanguageTextCatalog, LanguageTextFn, LocaleInfo, ResolvedLocale, Translator, } from "./types.js";

package/dist/i18n/index.js

@@ -0,0 +1,10 @@
+/**
+ * Public surface of the i18nkit core (the `.` entry). The star is the {@link I18n} class - a
+ * consumer constructs one instance and reaches every feature through it. The mapped-type
+ * vocabulary is exported for annotations, and the two locale-free resolvers (`createTranslator`,
+ * `translate`) are exported as escape hatches for resolving a text you already hold without an
+ * instance. Detection and routing are reached as `I18n` methods, not standalone, so there is one
+ * obvious way to do each.
+ */
+export { I18n } from "./i18n.js";
+export { createTranslator, translate } from "./translate.js";

package/dist/i18n/routing.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Pure, config-driven URL-locale routing, ported from the SwiftGuard i18n core and generalized
+ * over any locale set. The URL scheme is "as-needed": the default locale lives at bare URLs
+ * (`/pricing`) and every other locale under its `htmlLang` prefix (`/nl/pricing`); the default
+ * locale's own prefix never appears. Dependency-free (imports only `./types.js`) so it can be
+ * bundled into edge middleware. Reached as instance methods (`i18n.localizeHref(...)` etc.).
+ */
+import type { ResolvedLocale, RoutingStrategy } from "./types.js";
+/**
+ * The routing configuration a routing function needs - a structural subset of an {@link I18n}
+ * instance, so the instance can pass itself. Kept separate from the full config so the routing
+ * functions stay usable in isolation.
+ *
+ * @typeParam L - the locale union.
+ */
+export interface RoutingConfig<L extends string> {
+    /** Every resolved locale, for `htmlLang` <-> code mapping. */
+    readonly locales: readonly ResolvedLocale<L>[];
+    /** The default locale (served at bare URLs, no prefix). */
+    readonly default: L;
+    /** Path prefixes that are never localized (e.g. `["/api"]`). */
+    readonly nonLocalizedPrefixes: readonly string[];
+    /** The URL scheme for the default locale; see {@link RoutingStrategy}. */
+    readonly strategy: RoutingStrategy;
+    /** Absolute site origin for {@link hreflangAlternates} (e.g. `"https://example.com"`). */
+    readonly origin?: string | undefined;
+}
+/**
+ * Whether a pathname belongs to the localized zone, i.e. is not under any
+ * {@link RoutingConfig.nonLocalizedPrefixes} entry. Segment-aware: `/api` and `/api/x` are
+ * non-localized, `/apis` is localized.
+ *
+ * @param config - the routing config.
+ * @param pathname - the URL pathname (no query/hash).
+ * @returns true when the path takes a locale prefix.
+ */
+export declare function isLocalizedPath<L extends string>(config: RoutingConfig<L>, pathname: string): boolean;
+/**
+ * Map a URL path segment to the locale it denotes (via each locale's `htmlLang`, e.g. `"nl"`),
+ * or null when the segment is not a locale.
+ *
+ * @param config - the routing config.
+ * @param segment - the first path segment, without slashes.
+ * @returns the matching locale code, or null.
+ */
+export declare function localeForSegment<L extends string>(config: RoutingConfig<L>, segment: string): L | null;
+/**
+ * The URL prefix for a locale: `"/<htmlLang>"` (e.g. `"/nl"`), or `""` for the default locale under
+ * the `"prefix-except-default"` strategy (bare URLs). Under `"prefix-all"` the default locale is
+ * prefixed too, so this never returns `""`.
+ *
+ * The `htmlLang` is lowercased for the URL, so a region/script-subtag locale (`htmlLang: "en-GB"`)
+ * yields the conventional lowercase prefix `"/en-gb"`, matching the case-insensitive segment parsing
+ * in {@link localeForSegment} (it round-trips). The document `<html lang>` value keeps its configured
+ * BCP-47 casing - read that via `htmlLangFor`, not from the URL.
+ *
+ * @param config - the routing config.
+ * @param locale - the locale.
+ * @returns the leading URL segment (lowercased), or `""`.
+ */
+export declare function prefixFor<L extends string>(config: RoutingConfig<L>, locale: L): string;
+/**
+ * Localize an internal href for a locale: `/pricing` -> `/nl/pricing` when `nl` is active. Passes
+ * through unchanged: the default locale, hrefs that are not site-absolute (`mailto:`, `#hash`,
+ * external, protocol-relative `//`), non-localized targets, and hrefs that already carry a locale
+ * prefix. The prefix is inserted before the first `?` or `#`, and `"/"` becomes the bare prefix
+ * (`"/nl"`, never `"/nl/"`).
+ *
+ * @param config - the routing config.
+ * @param href - the link target as written at the call site.
+ * @param locale - the active locale.
+ * @returns the (possibly prefixed) href.
+ */
+export declare function localizeHref<L extends string>(config: RoutingConfig<L>, href: string, locale: L): string;
+/**
+ * Rewrite a pathname to another locale's URL: strips any existing locale segment and applies the
+ * target locale's prefix. Used by the language picker to navigate between `/nl/pricing` and
+ * `/pricing`.
+ *
+ * @param config - the routing config.
+ * @param pathname - the current URL pathname.
+ * @param next - the locale to switch to.
+ * @returns the pathname for the same page in the target locale.
+ */
+export declare function switchLocalePath<L extends string>(config: RoutingConfig<L>, pathname: string, next: L): string;
+/**
+ * Strip any locale prefix from a pathname (`/nl/dashboard` -> `/dashboard`, `/nl` -> `/`). Use
+ * before comparing a live pathname against bare hrefs (e.g. nav active-state highlighting), or as
+ * the primitive {@link switchLocalePath} builds on. Strips regardless of strategy - unlike
+ * "switch to the default locale", which under `"prefix-all"` would re-apply the default's prefix.
+ *
+ * @param config - the routing config.
+ * @param pathname - the current URL pathname.
+ * @returns the pathname without its locale prefix.
+ */
+export declare function stripLocalePrefix<L extends string>(config: RoutingConfig<L>, pathname: string): string;
+/**
+ * Canonical + hreflang alternates for a page, shaped to plug straight into a framework's metadata
+ * (typed structurally so this module stays framework-free). The canonical is the active locale's
+ * own URL; the `languages` map lists every locale by `htmlLang` plus `x-default` pointing at the
+ * bare (default-locale) URL. Adding a locale extends every page's hreflang automatically.
+ *
+ * @param config - the routing config; its `origin` must be set.
+ * @param path - the page's bare (unprefixed) pathname, e.g. `"/pricing"`.
+ * @param locale - the active locale (decides the canonical).
+ * @returns the `{ canonical, languages }` alternates object.
+ * @throws Error when the config has no `origin`.
+ */
+export declare function hreflangAlternates<L extends string>(config: RoutingConfig<L>, path: string, locale: L): {
+    canonical: string;
+    languages: Record<string, string>;
+};

package/dist/i18n/routing.js

@@ -0,0 +1,157 @@
+/**
+ * Look up a locale's `htmlLang`, falling back to the code itself when unknown.
+ *
+ * @param config - the routing config.
+ * @param locale - the locale to look up.
+ * @returns the locale's `htmlLang` subtag.
+ */
+function htmlLangOf(config, locale) {
+    return config.locales.find((info) => info.code === locale)?.htmlLang ?? locale;
+}
+/**
+ * Whether a pathname belongs to the localized zone, i.e. is not under any
+ * {@link RoutingConfig.nonLocalizedPrefixes} entry. Segment-aware: `/api` and `/api/x` are
+ * non-localized, `/apis` is localized.
+ *
+ * @param config - the routing config.
+ * @param pathname - the URL pathname (no query/hash).
+ * @returns true when the path takes a locale prefix.
+ */
+export function isLocalizedPath(config, pathname) {
+    return !config.nonLocalizedPrefixes.some((prefix) => pathname === prefix || pathname.startsWith(`${prefix}/`));
+}
+/**
+ * Map a URL path segment to the locale it denotes (via each locale's `htmlLang`, e.g. `"nl"`),
+ * or null when the segment is not a locale.
+ *
+ * @param config - the routing config.
+ * @param segment - the first path segment, without slashes.
+ * @returns the matching locale code, or null.
+ */
+export function localeForSegment(config, segment) {
+    // Compare case-insensitively so a lowercased URL (`/en-gb/x`) still matches a region-subtag
+    // locale (`htmlLang: "en-GB"`), mirroring how `matchAcceptLanguage` lowercases both sides.
+    const lower = segment.toLowerCase();
+    return config.locales.find((info) => info.htmlLang.toLowerCase() === lower)?.code ?? null;
+}
+/**
+ * The URL prefix for a locale: `"/<htmlLang>"` (e.g. `"/nl"`), or `""` for the default locale under
+ * the `"prefix-except-default"` strategy (bare URLs). Under `"prefix-all"` the default locale is
+ * prefixed too, so this never returns `""`.
+ *
+ * The `htmlLang` is lowercased for the URL, so a region/script-subtag locale (`htmlLang: "en-GB"`)
+ * yields the conventional lowercase prefix `"/en-gb"`, matching the case-insensitive segment parsing
+ * in {@link localeForSegment} (it round-trips). The document `<html lang>` value keeps its configured
+ * BCP-47 casing - read that via `htmlLangFor`, not from the URL.
+ *
+ * @param config - the routing config.
+ * @param locale - the locale.
+ * @returns the leading URL segment (lowercased), or `""`.
+ */
+export function prefixFor(config, locale) {
+    const prefixed = config.strategy === "prefix-all" || locale !== config.default;
+    return prefixed ? `/${htmlLangOf(config, locale).toLowerCase()}` : "";
+}
+/**
+ * Localize an internal href for a locale: `/pricing` -> `/nl/pricing` when `nl` is active. Passes
+ * through unchanged: the default locale, hrefs that are not site-absolute (`mailto:`, `#hash`,
+ * external, protocol-relative `//`), non-localized targets, and hrefs that already carry a locale
+ * prefix. The prefix is inserted before the first `?` or `#`, and `"/"` becomes the bare prefix
+ * (`"/nl"`, never `"/nl/"`).
+ *
+ * @param config - the routing config.
+ * @param href - the link target as written at the call site.
+ * @param locale - the active locale.
+ * @returns the (possibly prefixed) href.
+ */
+export function localizeHref(config, href, locale) {
+    const prefix = prefixFor(config, locale);
+    if (!prefix || !href.startsWith("/") || href.startsWith("//")) {
+        return href;
+    }
+    const queryIdx = href.indexOf("?");
+    const hashIdx = href.indexOf("#");
+    const stopIdx = queryIdx === -1 ? hashIdx : hashIdx === -1 ? queryIdx : Math.min(queryIdx, hashIdx);
+    const path = stopIdx === -1 ? href : href.slice(0, stopIdx);
+    const rest = stopIdx === -1 ? "" : href.slice(stopIdx);
+    if (!isLocalizedPath(config, path)) {
+        return href;
+    }
+    // `path` is guaranteed "/"-prefixed and non-empty here, so split("/")[1] is always present.
+    if (localeForSegment(config, path.split("/")[1])) {
+        return href;
+    }
+    return path === "/" ? `${prefix}${rest}` : `${prefix}${path}${rest}`;
+}
+/**
+ * Rewrite a pathname to another locale's URL: strips any existing locale segment and applies the
+ * target locale's prefix. Used by the language picker to navigate between `/nl/pricing` and
+ * `/pricing`.
+ *
+ * @param config - the routing config.
+ * @param pathname - the current URL pathname.
+ * @param next - the locale to switch to.
+ * @returns the pathname for the same page in the target locale.
+ */
+export function switchLocalePath(config, pathname, next) {
+    const stripped = stripLocalePrefix(config, pathname);
+    const prefix = prefixFor(config, next);
+    // A non-localized path (e.g. /api/*) never takes a locale prefix - mirror localizeHref, so
+    // the picker does not navigate to a route that does not exist.
+    if (!prefix || !isLocalizedPath(config, stripped)) {
+        return stripped;
+    }
+    return stripped === "/" ? prefix : `${prefix}${stripped}`;
+}
+/**
+ * Strip any locale prefix from a pathname (`/nl/dashboard` -> `/dashboard`, `/nl` -> `/`). Use
+ * before comparing a live pathname against bare hrefs (e.g. nav active-state highlighting), or as
+ * the primitive {@link switchLocalePath} builds on. Strips regardless of strategy - unlike
+ * "switch to the default locale", which under `"prefix-all"` would re-apply the default's prefix.
+ *
+ * @param config - the routing config.
+ * @param pathname - the current URL pathname.
+ * @returns the pathname without its locale prefix.
+ */
+export function stripLocalePrefix(config, pathname) {
+    const segment = pathname.split("/")[1] ?? "";
+    return localeForSegment(config, segment) ? pathname.slice(segment.length + 1) || "/" : pathname;
+}
+/**
+ * Canonical + hreflang alternates for a page, shaped to plug straight into a framework's metadata
+ * (typed structurally so this module stays framework-free). The canonical is the active locale's
+ * own URL; the `languages` map lists every locale by `htmlLang` plus `x-default` pointing at the
+ * bare (default-locale) URL. Adding a locale extends every page's hreflang automatically.
+ *
+ * @param config - the routing config; its `origin` must be set.
+ * @param path - the page's bare (unprefixed) pathname, e.g. `"/pricing"`.
+ * @param locale - the active locale (decides the canonical).
+ * @returns the `{ canonical, languages }` alternates object.
+ * @throws Error when the config has no `origin`.
+ */
+export function hreflangAlternates(config, path, locale) {
+    const { origin } = config;
+    if (!origin) {
+        throw new Error("hreflangAlternates requires `origin` to be set in the I18n config (e.g. new I18n({ ..., origin: 'https://example.com' })).");
+    }
+    // Tolerate a caller passing the already-prefixed pathname (routers often hand you `/nl/x`):
+    // reduce it to the bare form so alternates are built from a single canonical path.
+    const bare = stripLocalePrefix(config, path);
+    // A non-localized path has a single real URL - do not fabricate per-locale alternates for it.
+    if (!isLocalizedPath(config, bare)) {
+        const url = `${origin}${bare}`;
+        return { canonical: url, languages: { "x-default": url } };
+    }
+    const urlFor = (code) => {
+        const prefix = prefixFor(config, code);
+        // At the root, a prefixed locale is its own bare URL (`/nl`, not `/nl/`); only a locale
+        // with no prefix keeps the bare `/`.
+        return `${origin}${prefix}${bare === "/" && prefix ? "" : bare}`;
+    };
+    const languages = {};
+    for (const info of config.locales) {
+        languages[info.htmlLang] = urlFor(info.code);
+    }
+    languages["x-default"] = urlFor(config.default);
+    return { canonical: urlFor(locale), languages };
+}

package/dist/i18n/translate.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The resolver: turns a {@link LanguageText}/{@link LanguageTextFn} into a plain string for a
+ * given locale. Kept framework-free (types-only import) so the identical call shape works on the
+ * server, in the browser, and at the edge.
+ */
+import type { LanguageText, Translator } from "./types.js";
+/**
+ * Build a {@link Translator} bound to a single locale. The returned function reads the entry for
+ * `locale` and, if it is a builder function, applies the arguments. Usually reached through
+ * `i18n.translator(locale)` (which pins the locale to the instance's union) rather than directly.
+ *
+ * @typeParam L - the locale union the text objects are keyed by.
+ * @param locale - the locale every returned call resolves against.
+ * @returns the overloaded translator function.
+ */
+export declare function createTranslator<L extends string>(locale: L): Translator<L>;
+/**
+ * Resolve a single static text without building a bound {@link Translator} - handy for one-off
+ * lookups. For parameterized text or repeated resolution, prefer `i18n.translator(locale)`.
+ *
+ * @typeParam L - the locale union the text object is keyed by.
+ * @param text - the {@link LanguageText} to resolve.
+ * @param locale - the locale to resolve against.
+ * @returns the string for that locale.
+ */
+export declare function translate<L extends string>(text: LanguageText<L>, locale: L): string;

package/dist/i18n/translate.js

@@ -0,0 +1,28 @@
+/**
+ * Build a {@link Translator} bound to a single locale. The returned function reads the entry for
+ * `locale` and, if it is a builder function, applies the arguments. Usually reached through
+ * `i18n.translator(locale)` (which pins the locale to the instance's union) rather than directly.
+ *
+ * @typeParam L - the locale union the text objects are keyed by.
+ * @param locale - the locale every returned call resolves against.
+ * @returns the overloaded translator function.
+ */
+export function createTranslator(locale) {
+    function boundTranslate(text, ...args) {
+        const value = text[locale];
+        return typeof value === "function" ? value(...args) : value;
+    }
+    return boundTranslate;
+}
+/**
+ * Resolve a single static text without building a bound {@link Translator} - handy for one-off
+ * lookups. For parameterized text or repeated resolution, prefer `i18n.translator(locale)`.
+ *
+ * @typeParam L - the locale union the text object is keyed by.
+ * @param text - the {@link LanguageText} to resolve.
+ * @param locale - the locale to resolve against.
+ * @returns the string for that locale.
+ */
+export function translate(text, locale) {
+    return text[locale];
+}