npm - @daanvandenbergh/i18nkit - Versions diffs - 1.0.0 - Mend

@daanvandenbergh/i18nkit 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (35) hide show

package/README.md +285 -0
package/dist/i18n/catalog.d.ts +18 -0
package/dist/i18n/catalog.js +17 -0
package/dist/i18n/detect.d.ts +34 -0
package/dist/i18n/detect.js +62 -0
package/dist/i18n/i18n.d.ts +178 -0
package/dist/i18n/i18n.js +254 -0
package/dist/i18n/index.d.ts +11 -0
package/dist/i18n/index.js +10 -0
package/dist/i18n/routing.d.ts +112 -0
package/dist/i18n/routing.js +157 -0
package/dist/i18n/translate.d.ts +26 -0
package/dist/i18n/translate.js +28 -0
package/dist/i18n/types.d.ts +155 -0
package/dist/i18n/types.js +11 -0
package/dist/index.d.ts +6 -0
package/dist/index.js +6 -0
package/dist/react/LanguagePicker.d.ts +21 -0
package/dist/react/LanguagePicker.js +70 -0
package/dist/react/LocaleLink.d.ts +21 -0
package/dist/react/LocaleLink.js +23 -0
package/dist/react/flags.d.ts +21 -0
package/dist/react/flags.js +348 -0
package/dist/react/index.d.ts +10 -0
package/dist/react/index.js +10 -0
package/dist/react/provider.d.ts +58 -0
package/dist/react/provider.js +94 -0
package/dist/react/styles.css +150 -0
package/package.json +77 -0
package/skills/i18nkit-add-locale/SKILL.md +182 -0
package/skills/i18nkit-add-locale/reference/translation-rules.md +207 -0
package/skills/i18nkit-add-locale/scripts/scan.sh +148 -0
package/skills/i18nkit-sweep/SKILL.md +208 -0
package/skills/i18nkit-sweep/reference/rules.md +174 -0
package/skills/i18nkit-sweep/scripts/find_candidates.sh +99 -0

package/README.md ADDED Viewed

@@ -0,0 +1,285 @@
+# i18nkit
+**Universal, 100% type-safe i18n for TypeScript sites.** Declare your locales once and the compiler
+guarantees every string is translated into every language - add a locale and TypeScript lights up at
+every translation you still owe.
+- **Type-safe by construction** - a translation is an object with one entry per locale. Miss one and it is a compile error, not a runtime `undefined`.
+- **Framework-agnostic core** - zero dependencies, no `next`, no `react`. Runs on the server, in the browser, and at the edge.
+- **Optional React layer** - a provider, hooks, an accessible `<LanguagePicker>`, and a locale-aware `<LocaleLink>` (decoupled from any router).
+- **Parameterized text** - per-locale builder functions keep word order correct in every language.
+- **Locale detection & URL routing** included - `Accept-Language` matching, cookie resolution, and "default at bare URL, others under `/nl/…`" helpers.
+```ts
+// Add "de" to your locales...
+const i18n = new I18n({
+    locales: { en: { label: "English" }, nl: { label: "Nederlands" }, de: { label: "Deutsch" } },
+    default: "en",
+});
+// ...and every catalog missing a German string is now a compile error:
+i18n.defineTextCatalog({
+    title: { en: "Customers", nl: "Klanten" },
+    //     ~~~~~ Property 'de' is missing
+});
+```
+---
+## Install
+```bash
+npm install @daanvandenbergh/i18nkit
+```
+`react` / `react-dom` are optional peer dependencies - you only need them if you use the `/react` entry.
+## Install the Claude Code skill
+i18nkit ships an agent skill, **`i18nkit-sweep`**, that sweeps your source for user-facing strings
+that bypass the type-safe system (and, if you use `@daanvandenbergh/blogkit`, checks every post has a
+translation and its own localized hero for each locale). It is report-only by default; run it with `/i18nkit-sweep`.
+Wire it into Claude Code with a **symlink**, so it tracks the installed package version - an
+`npm update` keeps the skill current, with no copy to re-sync:
+```bash
+mkdir -p .claude/skills
+# from your project root (assumes .claude/skills/ and node_modules/ share this root):
+ln -s ../../node_modules/@daanvandenbergh/i18nkit/skills/i18nkit-sweep .claude/skills/i18nkit-sweep
+```
+If your layout differs, point the link at an absolute target resolved by node:
+```bash
+ln -s "$(dirname "$(node -p "require.resolve('@daanvandenbergh/i18nkit/package.json')")")/skills/i18nkit-sweep" \
+      "$(pwd)/.claude/skills/i18nkit-sweep"
+```
+Verify with `ls .claude/skills/i18nkit-sweep/SKILL.md`, then invoke `/i18nkit-sweep` in Claude Code.
+(The target exists once you have run `npm install`.) Developing against a local checkout of this repo?
+Link the source folder instead: `ln -s ../../skills/i18nkit-sweep .claude/skills/i18nkit-sweep`.
+## Set up once
+Create your locale set in one place and export the instance (and its `Locale` type):
+```ts
+// app/i18n.ts
+import { I18n } from "@daanvandenbergh/i18nkit";
+export const i18n = new I18n({
+    locales: {
+        en: { label: "English",    htmlLang: "en", locale: "en-GB" },
+        nl: { label: "Nederlands", htmlLang: "nl", locale: "nl-NL" },
+    },
+    default: "en",
+});
+export type Locale = keyof typeof i18n.locales; // "en" | "nl"
+```
+`htmlLang` (for `<html lang>` / URL prefixes) and `locale` (for `Intl` formatting) each default to the
+locale's key, so a BCP-47-keyed config can be as short as `en: { label: "English" }`.
+## Write translations
+Author catalogs through the instance. Every entry must cover every locale, checked at the call site:
+```ts
+// app/customers/text.ts
+import { i18n } from "../i18n";
+export const TX = i18n.defineTextCatalog({
+    title:   { en: "Customers", nl: "Klanten" },
+    // Parameterized text: a builder per locale keeps word order native to each language.
+    deleted: { en: (name: string) => `${name} deleted`, nl: (name: string) => `${name} verwijderd` },
+    range:   {
+        en: (from: number, to: number, total: number) => `Showing ${from}-${to} of ${total}`,
+        nl: (from: number, to: number, total: number) => `${from}-${to} van ${total} weergegeven`,
+    },
+});
+```
+## Resolve to strings
+Bind a translator to a locale and call it:
+```ts
+const translate = i18n.translator("nl");
+translate(TX.title);            // "Klanten"
+translate(TX.deleted, "Ada");   // "Ada verwijderd"
+translate(TX.range, 1, 20, 137); // "1-20 van 137 weergegeven"
+```
+For a one-off, skip the binding: `i18n.translate(TX.title, "nl")`. For a string that is the same in
+every language, `i18n.uniform("Acme")` builds a fully-covered entry. For a standalone parameterized
+string, `i18n.defineText({ en: (n) => …, nl: (n) => … })` enforces coverage and infers the arguments.
+## Detect the locale (server / SSR)
+The core is framework-agnostic: feed it whatever your framework gives you.
+```ts
+// Anywhere you have the request: a cookie value and/or the Accept-Language header.
+// A stored cookie choice wins; a first-time visitor (no cookie) gets their browser preference.
+// Both helpers fall back to `default` internally, so gate on the cookie's presence - don't
+// chain them with `??`/`||` (resolveLocale never returns nullish, so the fallback is dead code).
+const locale = cookieValue
+    ? i18n.resolveLocale(cookieValue)                 // honor the stored choice
+    : i18n.matchAcceptLanguage(acceptLanguageHeader); // else the visitor's preference
+```
+For example, in a Next.js Server Component:
+```ts
+import { cookies, headers } from "next/headers";
+import { i18n } from "@/app/i18n";
+export async function activeLocale() {
+    const cookie = (await cookies()).get(i18n.cookie)?.value;
+    const accept = (await headers()).get("accept-language");
+    return cookie ? i18n.resolveLocale(cookie) : i18n.matchAcceptLanguage(accept);
+}
+```
+## React
+Wrap your app in the provider, passing the resolved locale and what to do when it changes (the provider
+writes the locale cookie for you first, then calls `onChange` - do navigation/refresh there):
+```tsx
+// app/providers.tsx
+"use client";
+import { I18nProvider } from "@daanvandenbergh/i18nkit/react";
+import "@daanvandenbergh/i18nkit/styles.css"; // for <LanguagePicker>
+import { i18n } from "./i18n";
+export function Providers({ locale, children }) {
+    // e.g. in Next.js: const router = useRouter(); onChange={() => router.refresh()}
+    return (
+        <I18nProvider i18n={i18n} locale={locale} onChange={() => location.reload()}>
+            {children}
+        </I18nProvider>
+    );
+}
+```
+Read and switch the locale with the hooks, and drop in the picker:
+```tsx
+"use client";
+import { useTranslator, LanguagePicker } from "@daanvandenbergh/i18nkit/react";
+import { TX } from "./customers/text";
+export function Header() {
+    const translate = useTranslator();
+    return (
+        <header>
+            <h1>{translate(TX.title)}</h1>
+            <LanguagePicker />
+        </header>
+    );
+}
+```
+Hooks: `useTranslator()` (a translator bound to the active locale), `useLocale()`, `useSetLocale()`,
+`useI18n()`. Pass your `Locale` union as a type argument for a precise return, e.g. `useLocale<Locale>()`.
+`<LanguagePicker>` is self-contained (open state, click-away, Escape, full ARIA) and shows the endonym
+labels by default. Want flags? Pass the built-in `localeFlag` renderer - a set of ~38 inline-SVG flags in
+one flat, rounded style, keyed by locale so `en`, `pt-BR`, `de-CH` all resolve correctly (unknown locales
+just show their label, never a broken image):
+```tsx
+import { LanguagePicker, localeFlag } from "@daanvandenbergh/i18nkit/react";
+<LanguagePicker renderFlag={localeFlag} />;
+```
+Or supply your own with `renderFlag={(loc) => <MyFlag code={loc} />}`. Style it entirely through the
+`--i18nkit-*` CSS custom properties on the shipped stylesheet.
+`<LocaleLink href="/pricing">` renders `/nl/pricing` when `nl` is active. It renders a plain `<a>` by
+default, or pass your framework's link via `as`: `<LocaleLink href="/pricing" as={NextLink} />`.
+## URL routing
+Config-driven helpers for the "default locale at bare URLs, others under `/<htmlLang>/…`" scheme
+(configure `nonLocalizedPrefixes` and `origin` on the instance):
+```ts
+i18n.prefixFor("nl");                       // "/nl"   ("" for the default)
+i18n.localizeHref("/pricing", "nl");        // "/nl/pricing"
+i18n.localizeHref("/pricing", "en");        // "/pricing"  (default = bare)
+i18n.switchLocalePath("/nl/pricing", "en"); // "/pricing"
+i18n.stripLocalePrefix("/nl/pricing");      // "/pricing"
+i18n.hreflangAlternates("/pricing", "nl");  // { canonical, languages: { en, nl, "x-default" } }
+```
+Pass `strategy: "prefix-all"` to prefix every locale, including the default -
+`i18n.localizeHref("/pricing", "en")` then returns `"/en/pricing"`, so no locale lives at a bare URL.
+The default, `"prefix-except-default"`, keeps the default locale at bare URLs as shown above.
+**URL casing.** If a locale's `htmlLang` carries a region or script subtag (`en-GB`, `pt-BR`,
+`zh-Hant`), the generated URL prefix is lowercased - `htmlLang: "en-GB"` produces `/en-gb/pricing`,
+the conventional casing for URLs - while `htmlLangFor(locale)` still returns `"en-GB"` for the
+`<html lang>` attribute and hreflang keys. Segment parsing (`localeForSegment`, `stripLocalePrefix`)
+is case-insensitive, so an inbound `/en-GB/…` or `/en-gb/…` both resolve. Plain lowercase primary
+subtags (`en`, `nl`, `de`) are unaffected.
+### Middleware
+i18nkit stays out of your request pipeline: the helpers above are framework-agnostic, so you write
+the redirect in your framework's own middleware and compose it from the instance. Detection is just
+`resolveLocale` (cookie) and `matchAcceptLanguage` (header). Under `"prefix-all"` a bare URL maps to
+no locale, so middleware **must** redirect it to a prefix or the site 404s on `/`:
+```ts
+// Next.js middleware.ts - prefix-all
+import { NextResponse, type NextRequest } from "next/server";
+import { i18n } from "./i18n";
+export function middleware(req: NextRequest) {
+    const { pathname } = req.nextUrl;
+    if (!i18n.isLocalizedPath(pathname)) return NextResponse.next();  // /api/* -> pass through
+    if (i18n.localeForSegment(pathname.split("/")[1] ?? "")) return NextResponse.next(); // /en/x -> serve
+    // bare URL: detect (cookie, else Accept-Language) and redirect to that locale's prefix
+    const cookie = req.cookies.get(i18n.cookie)?.value;
+    const locale = cookie
+        ? i18n.resolveLocale(cookie)
+        : i18n.matchAcceptLanguage(req.headers.get("accept-language"));
+    const url = req.nextUrl.clone();
+    url.pathname = i18n.localizeHref(pathname, locale);
+    return NextResponse.redirect(url);
+}
+```
+Under `"prefix-except-default"` the same shape applies, minus the redirect - a bare URL is already the
+default locale's real page, so you serve it as-is (optionally reading the locale for SSR).
+## API reference
+Everything hangs off the `I18n` instance.
+| Member | Purpose |
+| --- | --- |
+| `new I18n({ locales, default, cookie?, origin?, nonLocalizedPrefixes?, strategy? })` | Create the instance; infers the locale union from `locales`. `strategy` picks the default-locale URL scheme (`"prefix-except-default"` default, or `"prefix-all"`). |
+| `.locales` / `.list` / `.default` / `.cookie` | Resolved locale map / ordered array / default locale / cookie name. |
+| `.defineTextCatalog(catalog)` | Author a catalog; every entry must cover every locale. |
+| `.defineText(text)` | Author one static or parameterized text with full coverage. |
+| `.uniform(value)` | A text that is the same string in every locale. |
+| `.translator(locale)` | A `Translator` bound to `locale`. |
+| `.translate(text, locale)` | Resolve one static text (no binding). |
+| `.resolveLocale(raw)` / `.matchAcceptLanguage(header)` | Detect the locale from a cookie value / `Accept-Language`. |
+| `.htmlLangFor(locale)` / `.intlLocaleFor(locale)` | BCP-47 `<html lang>` subtag / full `Intl` locale. |
+| `.prefixFor` / `.localizeHref` / `.switchLocalePath` / `.stripLocalePrefix` / `.localeForSegment` / `.isLocalizedPath` / `.hreflangAlternates` | URL routing helpers. |
+`@daanvandenbergh/i18nkit/react`: `I18nProvider`, `useI18n`, `useLocale`, `useTranslator`, `useSetLocale`,
+`LanguagePicker`, `localeFlag`, `Flag`, `LocaleLink`. `@daanvandenbergh/i18nkit/styles.css`: the picker stylesheet.
+## Type-safety notes
+- **A missing translation is always a compile error.** This is the guarantee: grow your locale set and every incomplete `defineTextCatalog` / `defineText` fails to compile.
+- **Caveat:** a *typo'd, unknown* locale key (e.g. `de` when your set is `en`/`nl`) is silently accepted inside a `define*` call - TypeScript's generic constraints don't run excess-property checks. Missing keys - the case that matters for coverage - are always caught.

package/dist/i18n/catalog.d.ts ADDED Viewed

@@ -0,0 +1,18 @@
+/**
+ * Catalog construction helpers. The type-level machinery that enforces per-locale coverage lives
+ * in {@link import("./types.js").LanguageTextCatalog} and is applied by the `I18n` instance's
+ * `defineTextCatalog`/`defineText` methods; this file holds the one runtime helper that builds a
+ * text object, {@link uniform}.
+ */
+import type { LanguageText } from "./types.js";
+/**
+ * Build a {@link LanguageText} whose value is identical in every locale - for a brand word or a
+ * symbol that is the same across languages (e.g. `"Acme"`, `"←"`). Reached as `i18n.uniform(value)`,
+ * which supplies the instance's locale codes.
+ *
+ * @typeParam L - the locale union to cover.
+ * @param value - the string to use for every locale.
+ * @param codes - every locale code in `L`.
+ * @returns a {@link LanguageText} carrying `value` under each code.
+ */
+export declare function uniform<L extends string>(value: string, codes: readonly L[]): LanguageText<L>;

package/dist/i18n/catalog.js ADDED Viewed

@@ -0,0 +1,17 @@
+/**
+ * Build a {@link LanguageText} whose value is identical in every locale - for a brand word or a
+ * symbol that is the same across languages (e.g. `"Acme"`, `"←"`). Reached as `i18n.uniform(value)`,
+ * which supplies the instance's locale codes.
+ *
+ * @typeParam L - the locale union to cover.
+ * @param value - the string to use for every locale.
+ * @param codes - every locale code in `L`.
+ * @returns a {@link LanguageText} carrying `value` under each code.
+ */
+export function uniform(value, codes) {
+    const out = {};
+    for (const code of codes) {
+        out[code] = value;
+    }
+    return out;
+}

package/dist/i18n/detect.d.ts ADDED Viewed

@@ -0,0 +1,34 @@
+/**
+ * Pure locale detection, config-driven and framework-free: narrow an untrusted value (a cookie or
+ * `[lang]` segment) to a real locale, and pick the best locale from an HTTP `Accept-Language`
+ * header. Reached as `i18n.resolveLocale(...)` / `i18n.matchAcceptLanguage(...)`, but exported
+ * standalone too so edge middleware can call them without constructing an instance.
+ */
+import type { ResolvedLocale } from "./types.js";
+/**
+ * Narrow an untrusted value (a cookie value, or a locale code from anywhere) to a known locale,
+ * falling back to `fallback` when it is missing or unrecognized. Matches on the locale `code`
+ * (exact); for matching a URL segment against a locale's `htmlLang`, use `localeForSegment` in
+ * the routing module instead.
+ *
+ * @typeParam L - the locale union.
+ * @param raw - the candidate value, e.g. from a cookie.
+ * @param locales - every resolved locale of the instance.
+ * @param fallback - the locale to return when `raw` is missing or unknown.
+ * @returns a guaranteed-valid locale.
+ */
+export declare function resolveLocale<L extends string>(raw: string | undefined, locales: readonly ResolvedLocale<L>[], fallback: L): L;
+/**
+ * Detect the best-matching locale from an HTTP `Accept-Language` header, so a first-time visitor
+ * with no cookie lands in their own language. Tags are ranked by their `q` weight (default 1) and
+ * matched on the primary subtag against each locale's `htmlLang` (so `en-GB` and `en-US` both
+ * match `en`). Falls back to `fallback` when the header is absent or names only unsupported
+ * languages.
+ *
+ * @typeParam L - the locale union.
+ * @param header - the raw `Accept-Language` header value (or null/undefined).
+ * @param locales - every resolved locale of the instance.
+ * @param fallback - the locale to return when nothing matches.
+ * @returns the best supported locale.
+ */
+export declare function matchAcceptLanguage<L extends string>(header: string | null | undefined, locales: readonly ResolvedLocale<L>[], fallback: L): L;

package/dist/i18n/detect.js ADDED Viewed

@@ -0,0 +1,62 @@
+/**
+ * Narrow an untrusted value (a cookie value, or a locale code from anywhere) to a known locale,
+ * falling back to `fallback` when it is missing or unrecognized. Matches on the locale `code`
+ * (exact); for matching a URL segment against a locale's `htmlLang`, use `localeForSegment` in
+ * the routing module instead.
+ *
+ * @typeParam L - the locale union.
+ * @param raw - the candidate value, e.g. from a cookie.
+ * @param locales - every resolved locale of the instance.
+ * @param fallback - the locale to return when `raw` is missing or unknown.
+ * @returns a guaranteed-valid locale.
+ */
+export function resolveLocale(raw, locales, fallback) {
+    return locales.some((info) => info.code === raw) ? raw : fallback;
+}
+/**
+ * Detect the best-matching locale from an HTTP `Accept-Language` header, so a first-time visitor
+ * with no cookie lands in their own language. Tags are ranked by their `q` weight (default 1) and
+ * matched on the primary subtag against each locale's `htmlLang` (so `en-GB` and `en-US` both
+ * match `en`). Falls back to `fallback` when the header is absent or names only unsupported
+ * languages.
+ *
+ * @typeParam L - the locale union.
+ * @param header - the raw `Accept-Language` header value (or null/undefined).
+ * @param locales - every resolved locale of the instance.
+ * @param fallback - the locale to return when nothing matches.
+ * @returns the best supported locale.
+ */
+export function matchAcceptLanguage(header, locales, fallback) {
+    if (!header) {
+        return fallback;
+    }
+    const ranked = header
+        .split(",")
+        .map((part) => {
+        const [tag, ...params] = part.trim().split(";");
+        // Parameter names are case-insensitive (RFC 7231), so accept `q=` and `Q=`.
+        const qParam = params.find((p) => p.trim().toLowerCase().startsWith("q="));
+        const q = qParam ? Number.parseFloat(qParam.trim().slice(2)) : 1;
+        const full = tag.trim().toLowerCase();
+        // Clamp to the RFC 7231 range [0,1]: a malformed `q>1` (`q=1.5`, `q=1e3`) must not
+        // outrank a legitimate `q=1`, and a negative q clamps to 0 (dropped by the filter
+        // below). An unparseable weight (`q=abc` -> NaN) still drops the tag.
+        return { full, primary: full.split("-")[0], q: Number.isNaN(q) ? 0 : Math.min(Math.max(q, 0), 1) };
+    })
+        .filter((entry) => entry.primary && entry.q > 0)
+        .sort((a, b) => b.q - a.q);
+    for (const { full, primary } of ranked) {
+        // Prefer an exact tag match, so `en-GB` beats a bare `en` locale and `zh-Hant` is kept
+        // distinct from `zh-Hans`; only then fall back to matching on the primary subtag (so a
+        // bare `en` request still finds an `en-GB` locale).
+        const exact = locales.find((info) => info.htmlLang.toLowerCase() === full);
+        if (exact) {
+            return exact.code;
+        }
+        const primaryHit = locales.find((info) => info.htmlLang.toLowerCase().split("-")[0] === primary);
+        if (primaryHit) {
+            return primaryHit.code;
+        }
+    }
+    return fallback;
+}

package/dist/i18n/i18n.d.ts ADDED Viewed

@@ -0,0 +1,178 @@
+import type { I18nConfig, LanguageText, LanguageTextCatalog, LanguageTextFn, ResolvedLocale, RoutingStrategy, Translator } from "./types.js";
+/**
+ * Recover the locale union of an {@link I18n} instance type, for annotating helpers that receive
+ * one: `function greet(i18n: I18n<Locale>, l: LocaleOf<typeof i18n>) {}`. In app code the simpler
+ * `type Locale = keyof typeof i18n.locales` is usually enough.
+ *
+ * @typeParam T - an `I18n<L>` instance type.
+ */
+export type LocaleOf<T> = T extends I18n<infer L> ? L : never;
+/**
+ * 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 declare class I18n<L extends string> {
+    #private;
+    /** Every configured locale, fully resolved, keyed by code. `keyof this.locales` is the locale union. */
+    readonly locales: Record<L, ResolvedLocale<L>>;
+    /** Every configured locale in declaration order - the order the picker lists them. */
+    readonly list: readonly ResolvedLocale<L>[];
+    /** The fallback locale for detection/resolution (unknown cookie, unmatched `Accept-Language`). */
+    readonly default: L;
+    /** The cookie name the picker writes and locale detection reads. */
+    readonly cookie: string;
+    /** The absolute site origin for {@link hreflangAlternates}, or undefined if not configured. */
+    readonly origin: string | undefined;
+    /** Path prefixes that are never localized. */
+    readonly nonLocalizedPrefixes: readonly string[];
+    /** The URL scheme for the default locale (`"prefix-except-default"` or `"prefix-all"`). */
+    readonly strategy: RoutingStrategy;
+    /**
+     * 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: I18nConfig<L>);
+    /**
+     * 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<const C extends LanguageTextCatalog<L>>(catalog: C): C;
+    /**
+     * Define one standalone text - a static per-locale map, or a per-locale builder for
+     * parameterized copy. Every locale in `L` must be present or it is a compile error. Identity
+     * at runtime; the overloads preserve literal/argument types.
+     *
+     * @param text - the {@link LanguageText} or {@link LanguageTextFn}.
+     * @returns the same object, precisely typed.
+     */
+    defineText<const T extends LanguageText<L>>(text: T): T;
+    defineText<A extends readonly unknown[]>(text: LanguageTextFn<L, A>): LanguageTextFn<L, A>;
+    /**
+     * 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: string): LanguageText<L>;
+    /**
+     * 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: L): Translator<L>;
+    /**
+     * 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: LanguageText<L>, locale: L): string;
+    /**
+     * 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: string | undefined): L;
+    /**
+     * 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: string | null | undefined): L;
+    /**
+     * The BCP-47 `<html lang>` subtag for a locale (e.g. `"nl"`).
+     *
+     * @param locale - the locale.
+     * @returns its `htmlLang`.
+     */
+    htmlLangFor(locale: L): string;
+    /**
+     * 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: L): string;
+    /**
+     * The URL prefix for a locale: `""` for the default locale, `"/<htmlLang>"` otherwise.
+     *
+     * @param locale - the locale.
+     * @returns the leading URL segment.
+     */
+    prefixFor(locale: L): string;
+    /**
+     * 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: string): L | null;
+    /**
+     * 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: string): boolean;
+    /**
+     * 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: string, locale: L): string;
+    /**
+     * 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: string, next: L): string;
+    /**
+     * Strip any locale prefix from a pathname (`/nl/x` -> `/x`).
+     *
+     * @param pathname - the current pathname.
+     * @returns the unprefixed pathname.
+     */
+    stripLocalePrefix(pathname: string): string;
+    /**
+     * 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: string, locale: L): {
+        canonical: string;
+        languages: Record<string, string>;
+    };
+}