@adminiumjs/i18n 0.1.2 → 0.2.2-rc.0

package/dist/locales.d.ts

@@ -1,10 +1,32 @@
 /**
- * Canonical locale registry (10-i18n-theming.md §2.1) — the single
- * source of truth for the 8 BRIEF locales. Canonical ids use the underscore
- * form (`en_US`); BCP-47 tags are derived for everything `Intl`- and
- * i18next-facing. `dir` is derived from the locale, never independently
- * settable (02-design-system.md §4.2) — adding a future RTL locale (he_IL,
- * fa_IR) is a registry data change, not a code change.
+ * Canonical locale registry (10-i18n-theming.md §2.1) plus the runtime
+ * overlay that lets an admin add locales the build never saw
+ * (23-runtime-translations.md §5).
+ *
+ * Two id types, and the split is load-bearing:
+ *
+ *  - {@link BuiltinLocaleId} is the closed union of the eight COMPILED
+ *    locales. Everything that must stay exhaustive keys off it —
+ *    `REVIEW_STATUS`, the parity gate, `gen-resources.mjs`, `lazy.ts` — so a
+ *    ninth *compiled* locale is still a compile error, and no runtime locale
+ *    can ever reach a build-time gate.
+ *  - {@link LocaleId} additionally admits runtime ids. `(string & {})` keeps
+ *    literal autocomplete for the eight while accepting anything a custom
+ *    locale row can hold.
+ *
+ * Every lookup helper here is TOTAL: none of them throws on an unknown id.
+ * That is deliberate. Once locales are data, the orphan case — a deleted
+ * locale still referenced by a user pref, a restored backup, an imported
+ * config bundle — is the NORMAL aftermath of the feature, not an edge case,
+ * and these helpers run inside a theme subscriber. `emitTheme` isolates each
+ * listener now (23 §4.4), so a throw here no longer errors the React commit —
+ * it is logged and swallowed, and this subscriber simply does not finish. That
+ * is a quieter failure, not a smaller one: ThemeProvider stamps `dir`/`lang`
+ * BEFORE it emits, so the page turns RTL while every string stays in the old
+ * language, and nothing on screen says why.
+ *
+ * `dir` is still derived from the locale, never independently settable
+ * (02-design-system.md §4.2).
  */
 export interface LocaleEntry {
     /** Canonical underscore id stored in `adminium_settings`/`adminium_user_prefs`. */
@@ -24,6 +46,23 @@ export interface LocaleEntry {
      */
     fontHint: 'latin' | 'arabic' | 'cjk';
 }
+/** A runtime locale entry, plus the fields only the DB registry knows. */
+export interface RuntimeLocaleEntry extends LocaleEntry {
+    /** False for admin-created locales. */
+    builtin: boolean;
+    /** Offered in pickers? (23 §3.1 `enabled`.) */
+    enabled: boolean;
+    /** Picker ordering. */
+    sortOrder: number;
+    /**
+     * The REAL BCP-47 tag whose `Intl` behaviour this locale borrows (23 §5.6).
+     * For a built-in this is just `tag`; for a custom locale it is the admin's
+     * choice, because `tag` itself may be something `Intl` has never heard of.
+     */
+    intlTag: string;
+    /** Plural categories frozen at create time from `intlTag`. */
+    pluralCategories: readonly string[];
+}
 export declare const LOCALES: readonly [{
     readonly id: "en_US";
     readonly tag: "en-US";
@@ -81,19 +120,73 @@ export declare const LOCALES: readonly [{
     readonly dir: "rtl";
     readonly fontHint: "arabic";
 }];
-export type LocaleId = (typeof LOCALES)[number]['id'];
-export declare const LOCALE_IDS: readonly LocaleId[];
+/** The eight COMPILED locales — the exhaustive axis (23 §5.1). */
+export type BuiltinLocaleId = (typeof LOCALES)[number]['id'];
+/**
+ * Any locale id the running instance may hold — the eight compiled ones plus
+ * whatever an admin created. `(string & {})` preserves literal autocomplete
+ * for the eight instead of collapsing to a bare `string`.
+ */
+export type LocaleId = BuiltinLocaleId | (string & {});
+export declare const BUILTIN_LOCALE_IDS: readonly BuiltinLocaleId[];
+/** @deprecated Prefer {@link BUILTIN_LOCALE_IDS} (or the runtime list) by name. */
+export declare const LOCALE_IDS: readonly ("en_US" | "de_DE" | "fr_FR" | "cs_CZ" | "da_DK" | "zh_CN" | "zh_TW" | "ar_EG")[];
+/**
+ * Canonical id shape: a language subtag plus up to two more (script, region),
+ * e.g. `en_US`, `sw_KE`, `zh_Hant_TW`. Three subtags is why the DB column is
+ * `varchar(35)` and why {@link tagFromLocaleId} replaces EVERY underscore.
+ */
+export declare const LOCALE_ID_RE: RegExp;
+/** Replace the runtime registry wholesale (boot, and every version bump). */
+export declare function setRuntimeLocales(entries: readonly RuntimeLocaleEntry[]): void;
+/** Drop the runtime registry — tests, and teardown. */
+export declare function resetRuntimeLocales(): void;
+/** Every locale the instance knows: compiled defaults merged under runtime rows. */
+export declare function allLocales(): readonly RuntimeLocaleEntry[];
+/** The locales a picker may offer, in picker order (23 §3.1 `enabled`). */
+export declare function availableLocales(): readonly RuntimeLocaleEntry[];
+/** True for one of the eight COMPILED locales. */
+export declare function isBuiltinLocaleId(value: unknown): value is BuiltinLocaleId;
+/**
+ * True for anything shaped like a locale id. This is a SHAPE check, not a
+ * membership check: a cached preference may name a locale this build does not
+ * compile in, and rejecting it would strand the user on en-US. Use
+ * {@link isBuiltinLocaleId} when compiled membership is what you mean.
+ */
 export declare function isLocaleId(value: unknown): value is LocaleId;
+/**
+ * `en_US` → `en-US`, `zh_Hant_TW` → `zh-Hant-TW`.
+ *
+ * Replaces EVERY underscore. A single-replacement version leaves
+ * `zh-Hant_TW`, which is not a valid BCP-47 tag, and the formatter layer
+ * coalesces invalid tags to `en-US` — silently degrading exactly the way the
+ * admin-chosen `intlTag` exists to prevent.
+ */
+export declare function tagFromLocaleId(id: string): string;
+/**
+ * The presentation record for a locale: compiled entry, else runtime entry,
+ * else a synthesized one. Total by contract — see the file header for why
+ * throwing here is a white screen.
+ */
 export declare function localeEntry(id: LocaleId): LocaleEntry;
-/** `'rtl'` iff the registry says so (`ar_EG` today) — data-driven, not hardcoded. */
+/** `'rtl'` iff the registry says so — data-driven, never hardcoded to `ar_EG`. */
 export declare function dirForLocale(id: LocaleId): 'ltr' | 'rtl';
 export declare function isRtlLocale(id: LocaleId): boolean;
-/** `ar_EG` → `ar-EG` for `Intl.*`, i18next, and the `lang` attribute. */
+/** `ar_EG` → `ar-EG` for i18next and the `lang` attribute. */
 export declare function tagForLocale(id: LocaleId): string;
 /**
- * Best-effort inverse of {@link tagForLocale}: exact tag match, then a
- * language-only match (`de` → `de_DE`), else `en_US`. Used to map
- * `i18next.language` / `navigator.language` back to a canonical id.
+ * The tag to hand `Intl.*` and `IntlMessageFormat` (23 §4.5). For a compiled
+ * locale this is just the tag; for a custom locale it is the admin-chosen
+ * borrow tag, because the locale's own tag may be something no ICU
+ * implementation has data for.
+ */
+export declare function intlTagForLocale(id: LocaleId): string;
+/** Plural categories to validate a message against (frozen at create time). */
+export declare function pluralCategoriesForLocale(id: LocaleId): readonly string[];
+/**
+ * Best-effort inverse of {@link tagForLocale}: exact compiled tag, then a
+ * runtime tag, then a language-only compiled match (`de` → `de_DE`), else
+ * `en_US`. Maps `i18next.language` / `navigator.language` back to an id.
  */
 export declare function localeFromTag(tag: string): LocaleId;
 //# sourceMappingURL=locales.d.ts.map

package/dist/locales.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"locales.d.ts","sourceRoot":"","sources":["../src/locales.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,WAAW,WAAW;IAC1B,mFAAmF;IACnF,EAAE,EAAE,MAAM,CAAC;IACX,kEAAkE;IAClE,GAAG,EAAE,MAAM,CAAC;IACZ,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,+DAA+D;IAC/D,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,KAAK,GAAG,KAAK,CAAC;IACnB;;;;;OAKG;IACH,QAAQ,EAAE,OAAO,GAAG,QAAQ,GAAG,KAAK,CAAC;CACtC;AAED,eAAO,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EASuB,CAAC;AAE5C,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC;AAEtD,eAAO,MAAM,UAAU,EAA0C,SAAS,QAAQ,EAAE,CAAC;AAKrF,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAE5D;AAED,wBAAgB,WAAW,CAAC,EAAE,EAAE,QAAQ,GAAG,WAAW,CAIrD;AAED,qFAAqF;AACrF,wBAAgB,YAAY,CAAC,EAAE,EAAE,QAAQ,GAAG,KAAK,GAAG,KAAK,CAExD;AAED,wBAAgB,WAAW,CAAC,EAAE,EAAE,QAAQ,GAAG,OAAO,CAEjD;AAED,yEAAyE;AACzE,wBAAgB,YAAY,CAAC,EAAE,EAAE,QAAQ,GAAG,MAAM,CAEjD;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,CAMnD"}
+{"version":3,"file":"locales.d.ts","sourceRoot":"","sources":["../src/locales.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,MAAM,WAAW,WAAW;IAC1B,mFAAmF;IACnF,EAAE,EAAE,MAAM,CAAC;IACX,kEAAkE;IAClE,GAAG,EAAE,MAAM,CAAC;IACZ,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,+DAA+D;IAC/D,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,KAAK,GAAG,KAAK,CAAC;IACnB;;;;;OAKG;IACH,QAAQ,EAAE,OAAO,GAAG,QAAQ,GAAG,KAAK,CAAC;CACtC;AAED,0EAA0E;AAC1E,MAAM,WAAW,kBAAmB,SAAQ,WAAW;IACrD,uCAAuC;IACvC,OAAO,EAAE,OAAO,CAAC;IACjB,+CAA+C;IAC/C,OAAO,EAAE,OAAO,CAAC;IACjB,uBAAuB;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB,8DAA8D;IAC9D,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED,eAAO,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EASuB,CAAC;AAE5C,kEAAkE;AAClE,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC;AAE7D;;;;GAIG;AACH,MAAM,MAAM,QAAQ,GAAG,eAAe,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAEvD,eAAO,MAAM,kBAAkB,EAA0C,SAAS,eAAe,EAAE,CAAC;AAEpG,mFAAmF;AACnF,eAAO,MAAM,UAAU,4FAAqB,CAAC;AAE7C;;;;GAIG;AACH,eAAO,MAAM,YAAY,QAAyC,CAAC;AAiBnE,6EAA6E;AAC7E,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,SAAS,kBAAkB,EAAE,GAAG,IAAI,CAE9E;AAED,uDAAuD;AACvD,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C;AAED,oFAAoF;AACpF,wBAAgB,UAAU,IAAI,SAAS,kBAAkB,EAAE,CA2B1D;AAED,2EAA2E;AAC3E,wBAAgB,gBAAgB,IAAI,SAAS,kBAAkB,EAAE,CAEhE;AAID,kDAAkD;AAClD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,eAAe,CAE1E;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAE5D;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAElD;AAOD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,QAAQ,GAAG,WAAW,CAErD;AAED,kFAAkF;AAClF,wBAAgB,YAAY,CAAC,EAAE,EAAE,QAAQ,GAAG,KAAK,GAAG,KAAK,CAExD;AAED,wBAAgB,WAAW,CAAC,EAAE,EAAE,QAAQ,GAAG,OAAO,CAEjD;AAED,8DAA8D;AAC9D,wBAAgB,YAAY,CAAC,EAAE,EAAE,QAAQ,GAAG,MAAM,CAEjD;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,QAAQ,GAAG,MAAM,CAErD;AAED,+EAA+E;AAC/E,wBAAgB,yBAAyB,CAAC,EAAE,EAAE,QAAQ,GAAG,SAAS,MAAM,EAAE,CAQzE;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,CASnD"}

package/dist/locales.js

@@ -1,10 +1,33 @@
+// SPDX-License-Identifier: AGPL-3.0-only
 /**
- * Canonical locale registry (10-i18n-theming.md §2.1) — the single
- * source of truth for the 8 BRIEF locales. Canonical ids use the underscore
- * form (`en_US`); BCP-47 tags are derived for everything `Intl`- and
- * i18next-facing. `dir` is derived from the locale, never independently
- * settable (02-design-system.md §4.2) — adding a future RTL locale (he_IL,
- * fa_IR) is a registry data change, not a code change.
+ * Canonical locale registry (10-i18n-theming.md §2.1) plus the runtime
+ * overlay that lets an admin add locales the build never saw
+ * (23-runtime-translations.md §5).
+ *
+ * Two id types, and the split is load-bearing:
+ *
+ *  - {@link BuiltinLocaleId} is the closed union of the eight COMPILED
+ *    locales. Everything that must stay exhaustive keys off it —
+ *    `REVIEW_STATUS`, the parity gate, `gen-resources.mjs`, `lazy.ts` — so a
+ *    ninth *compiled* locale is still a compile error, and no runtime locale
+ *    can ever reach a build-time gate.
+ *  - {@link LocaleId} additionally admits runtime ids. `(string & {})` keeps
+ *    literal autocomplete for the eight while accepting anything a custom
+ *    locale row can hold.
+ *
+ * Every lookup helper here is TOTAL: none of them throws on an unknown id.
+ * That is deliberate. Once locales are data, the orphan case — a deleted
+ * locale still referenced by a user pref, a restored backup, an imported
+ * config bundle — is the NORMAL aftermath of the feature, not an edge case,
+ * and these helpers run inside a theme subscriber. `emitTheme` isolates each
+ * listener now (23 §4.4), so a throw here no longer errors the React commit —
+ * it is logged and swallowed, and this subscriber simply does not finish. That
+ * is a quieter failure, not a smaller one: ThemeProvider stamps `dir`/`lang`
+ * BEFORE it emits, so the page turns RTL while every string stays in the old
+ * language, and nothing on screen says why.
+ *
+ * `dir` is still derived from the locale, never independently settable
+ * (02-design-system.md §4.2).
  */
 export const LOCALES = [
     { id: 'en_US', tag: 'en-US', english: 'English (US)', native: 'English (US)', dir: 'ltr', fontHint: 'latin' },
@@ -16,38 +39,145 @@ export const LOCALES = [
     { id: 'zh_TW', tag: 'zh-TW', english: 'Chinese (Traditional)', native: '繁體中文', dir: 'ltr', fontHint: 'cjk' },
     { id: 'ar_EG', tag: 'ar-EG', english: 'Arabic (Egypt)', native: 'العربية (مصر)', dir: 'rtl', fontHint: 'arabic' },
 ];
-export const LOCALE_IDS = LOCALES.map((l) => l.id);
+export const BUILTIN_LOCALE_IDS = LOCALES.map((l) => l.id);
+/** @deprecated Prefer {@link BUILTIN_LOCALE_IDS} (or the runtime list) by name. */
+export const LOCALE_IDS = BUILTIN_LOCALE_IDS;
+/**
+ * Canonical id shape: a language subtag plus up to two more (script, region),
+ * e.g. `en_US`, `sw_KE`, `zh_Hant_TW`. Three subtags is why the DB column is
+ * `varchar(35)` and why {@link tagFromLocaleId} replaces EVERY underscore.
+ */
+export const LOCALE_ID_RE = /^[a-z]{2,3}(_[A-Za-z0-9]{2,8}){0,2}$/;
 const BY_ID = new Map(LOCALES.map((l) => [l.id, l]));
 const BY_TAG = new Map(LOCALES.map((l) => [l.tag, l]));
-export function isLocaleId(value) {
+// --- runtime overlay ---------------------------------------------------------
+/**
+ * Locales the running instance knows about beyond the compiled eight. Set
+ * once from the server manifest at boot and on every i18n version bump; empty
+ * on a server/CLI that never loads it, which is exactly the pre-23 behaviour.
+ *
+ * A module-level singleton is correct here: one Adminium instance has one
+ * meta store and therefore one locale registry, same as the compiled one.
+ */
+let runtimeById = new Map();
+/** Replace the runtime registry wholesale (boot, and every version bump). */
+export function setRuntimeLocales(entries) {
+    runtimeById = new Map(entries.map((e) => [e.id, e]));
+}
+/** Drop the runtime registry — tests, and teardown. */
+export function resetRuntimeLocales() {
+    runtimeById = new Map();
+}
+/** Every locale the instance knows: compiled defaults merged under runtime rows. */
+export function allLocales() {
+    const merged = new Map();
+    for (const entry of LOCALES) {
+        merged.set(entry.id, {
+            ...entry,
+            builtin: true,
+            enabled: true,
+            sortOrder: 0,
+            intlTag: entry.tag,
+            pluralCategories: [],
+        });
+    }
+    for (const [id, entry] of runtimeById) {
+        const base = merged.get(id);
+        // A built-in row may only carry `enabled`/`sortOrder` (23 §3.1 field
+        // lock) — presentation always comes from the compiled entry, so an admin
+        // cannot flip ar_EG to ltr and corrupt a shipped bundle's rendering.
+        merged.set(id, base === undefined
+            ? entry
+            : { ...base, enabled: entry.enabled, sortOrder: entry.sortOrder, builtin: true });
+    }
+    return [...merged.values()].sort((a, b) => a.sortOrder - b.sortOrder || a.id.localeCompare(b.id));
+}
+/** The locales a picker may offer, in picker order (23 §3.1 `enabled`). */
+export function availableLocales() {
+    return allLocales().filter((l) => l.enabled);
+}
+// --- lookups (all total) -----------------------------------------------------
+/** True for one of the eight COMPILED locales. */
+export function isBuiltinLocaleId(value) {
     return typeof value === 'string' && BY_ID.has(value);
 }
+/**
+ * True for anything shaped like a locale id. This is a SHAPE check, not a
+ * membership check: a cached preference may name a locale this build does not
+ * compile in, and rejecting it would strand the user on en-US. Use
+ * {@link isBuiltinLocaleId} when compiled membership is what you mean.
+ */
+export function isLocaleId(value) {
+    return typeof value === 'string' && LOCALE_ID_RE.test(value);
+}
+/**
+ * `en_US` → `en-US`, `zh_Hant_TW` → `zh-Hant-TW`.
+ *
+ * Replaces EVERY underscore. A single-replacement version leaves
+ * `zh-Hant_TW`, which is not a valid BCP-47 tag, and the formatter layer
+ * coalesces invalid tags to `en-US` — silently degrading exactly the way the
+ * admin-chosen `intlTag` exists to prevent.
+ */
+export function tagFromLocaleId(id) {
+    return id.replaceAll('_', '-');
+}
+/** Synthesized entry for an id no registry knows — never throws. */
+function synthesize(id) {
+    return { id, tag: tagFromLocaleId(id), english: id, native: id, dir: 'ltr', fontHint: 'latin' };
+}
+/**
+ * The presentation record for a locale: compiled entry, else runtime entry,
+ * else a synthesized one. Total by contract — see the file header for why
+ * throwing here is a white screen.
+ */
 export function localeEntry(id) {
-    const entry = BY_ID.get(id);
-    if (entry === undefined)
-        throw new Error(`unknown locale id: ${JSON.stringify(id)}`);
-    return entry;
+    return BY_ID.get(id) ?? runtimeById.get(id) ?? synthesize(id);
 }
-/** `'rtl'` iff the registry says so (`ar_EG` today) — data-driven, not hardcoded. */
+/** `'rtl'` iff the registry says so — data-driven, never hardcoded to `ar_EG`. */
 export function dirForLocale(id) {
     return localeEntry(id).dir;
 }
 export function isRtlLocale(id) {
     return dirForLocale(id) === 'rtl';
 }
-/** `ar_EG` → `ar-EG` for `Intl.*`, i18next, and the `lang` attribute. */
+/** `ar_EG` → `ar-EG` for i18next and the `lang` attribute. */
 export function tagForLocale(id) {
     return localeEntry(id).tag;
 }
 /**
- * Best-effort inverse of {@link tagForLocale}: exact tag match, then a
- * language-only match (`de` → `de_DE`), else `en_US`. Used to map
- * `i18next.language` / `navigator.language` back to a canonical id.
+ * The tag to hand `Intl.*` and `IntlMessageFormat` (23 §4.5). For a compiled
+ * locale this is just the tag; for a custom locale it is the admin-chosen
+ * borrow tag, because the locale's own tag may be something no ICU
+ * implementation has data for.
+ */
+export function intlTagForLocale(id) {
+    return runtimeById.get(id)?.intlTag ?? tagForLocale(id);
+}
+/** Plural categories to validate a message against (frozen at create time). */
+export function pluralCategoriesForLocale(id) {
+    const frozen = runtimeById.get(id)?.pluralCategories;
+    if (frozen !== undefined && frozen.length > 0)
+        return frozen;
+    try {
+        return new Intl.PluralRules(intlTagForLocale(id)).resolvedOptions().pluralCategories;
+    }
+    catch {
+        return ['other'];
+    }
+}
+/**
+ * Best-effort inverse of {@link tagForLocale}: exact compiled tag, then a
+ * runtime tag, then a language-only compiled match (`de` → `de_DE`), else
+ * `en_US`. Maps `i18next.language` / `navigator.language` back to an id.
  */
 export function localeFromTag(tag) {
     const exact = BY_TAG.get(tag);
     if (exact !== undefined)
         return exact.id;
+    for (const entry of runtimeById.values()) {
+        if (entry.tag === tag)
+            return entry.id;
+    }
     const lang = tag.toLowerCase().split('-')[0] ?? '';
     const byLang = LOCALES.find((l) => l.tag.toLowerCase().startsWith(`${lang}-`) || l.tag.toLowerCase() === lang);
     return byLang?.id ?? 'en_US';

package/dist/locales.js.map

@@ -1 +1 @@
-{"version":3,"file":"locales.js","sourceRoot":"","sources":["../src/locales.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"locales.js","sourceRoot":"","sources":["../src/locales.ts"],"names":[],"mappings":"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"}

package/dist/overrides.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Runtime override layer (23-runtime-translations.md §4.3).
+ *
+ * The compiled bundle and the DB override tree are held SEPARATELY and merged
+ * in userland; the i18next resource store is written once, at `init`, and
+ * never mutated afterwards. Two facts about i18next 25 force that shape, and
+ * both were verified against its source rather than assumed:
+ *
+ *  1. `addResourceBundle` cannot DELETE a key — its `deepExtend` only ever
+ *     writes keys present in the incoming object. So the store cannot express
+ *     "reset this key to the built-in", which is the single most common admin
+ *     operation. And `removeResourceBundle` is not an escape: it calls
+ *     `removeNamespaces`, which splices the namespace out of `options.ns` for
+ *     the WHOLE instance, breaking en-US resolution and every future backend
+ *     load for that namespace.
+ *  2. The backend loader fires at most once per (language, namespace) per
+ *     instance — `queueLoad` short-circuits on `hasResourceBundle` — so
+ *     merging inside `loadBundle` is a first-load mechanism, not a
+ *     steady-state one.
+ *
+ * Therefore: merge at load, and REBUILD the instance on every version bump,
+ * swapping it in through the existing provider seam. That is the only
+ * operation this i18next version performs losslessly.
+ */
+import { type CreateI18nOptions, type I18nInstance } from './create-i18n.js';
+import { type LocaleId } from './locales.js';
+import type { Namespace, ResourceBundle } from './resources/index.js';
+/** `tag → namespace → flat dotted key → message`. Sparse: only overrides. */
+export type OverrideMap = Readonly<Record<string, Readonly<Partial<Record<Namespace, Readonly<Record<string, string>>>>>>>;
+/**
+ * Merge flat dotted overrides into a (cloned) nested bundle.
+ *
+ * An empty-string value is written through deliberately — it is the third
+ * state, "render nothing" (23 §3.3), and is why `createI18n` sets
+ * `returnEmptyString: true`.
+ */
+export declare function mergeOverrides(base: ResourceBundle | null, flat: Readonly<Record<string, string>>): ResourceBundle;
+export interface CreateI18nWithOverridesOptions extends CreateI18nOptions {
+    /** DB-sourced overrides, keyed by BCP-47 tag. */
+    overrides?: OverrideMap | undefined;
+}
+/**
+ * `createI18n` with the override layer folded in.
+ *
+ * en-US overrides are applied through the SAME merge as every other locale,
+ * never through `createI18n`'s `resources` option: that option does
+ * `target[ns] = bundle`, a whole-namespace REPLACEMENT, so routing a sparse
+ * override tree through it would delete the ~1,500 other `common` keys.
+ */
+export declare function createI18nWithOverrides(opts: CreateI18nWithOverridesOptions): Promise<I18nInstance>;
+/**
+ * Rebuild the instance with a new override set and hand it back.
+ *
+ * The caller swaps the result into whatever holds the active instance and
+ * calls `bumpI18nRevision()` — which this does for you — so subscribers
+ * re-render. Rebuilding rather than patching is the whole point: see the
+ * module header.
+ */
+export declare function rebuildWithOverrides(opts: CreateI18nWithOverridesOptions): Promise<I18nInstance>;
+/** The BCP-47 key an override map uses for a locale id. */
+export declare function overrideTag(locale: LocaleId): string;
+//# sourceMappingURL=overrides.d.ts.map

package/dist/overrides.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"overrides.d.ts","sourceRoot":"","sources":["../src/overrides.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAc,KAAK,iBAAiB,EAAE,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACzF,OAAO,EAAgB,KAAK,QAAQ,EAAE,MAAM,cAAc,CAAC;AAE3D,OAAO,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtE,6EAA6E;AAC7E,MAAM,MAAM,WAAW,GAAG,QAAQ,CAChC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CACvF,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,cAAc,GAAG,IAAI,EAC3B,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GACrC,cAAc,CAiBhB;AAED,MAAM,WAAW,8BAA+B,SAAQ,iBAAiB;IACvE,iDAAiD;IACjD,SAAS,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;CACrC;AAED;;;;;;;GAOG;AACH,wBAAsB,uBAAuB,CAC3C,IAAI,EAAE,8BAA8B,GACnC,OAAO,CAAC,YAAY,CAAC,CAkCvB;AAED;;;;;;;GAOG;AACH,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,8BAA8B,GACnC,OAAO,CAAC,YAAY,CAAC,CAIvB;AAED,2DAA2D;AAC3D,wBAAgB,WAAW,CAAC,MAAM,EAAE,QAAQ,GAAG,MAAM,CAEpD"}

package/dist/overrides.js

@@ -0,0 +1,113 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Runtime override layer (23-runtime-translations.md §4.3).
+ *
+ * The compiled bundle and the DB override tree are held SEPARATELY and merged
+ * in userland; the i18next resource store is written once, at `init`, and
+ * never mutated afterwards. Two facts about i18next 25 force that shape, and
+ * both were verified against its source rather than assumed:
+ *
+ *  1. `addResourceBundle` cannot DELETE a key — its `deepExtend` only ever
+ *     writes keys present in the incoming object. So the store cannot express
+ *     "reset this key to the built-in", which is the single most common admin
+ *     operation. And `removeResourceBundle` is not an escape: it calls
+ *     `removeNamespaces`, which splices the namespace out of `options.ns` for
+ *     the WHOLE instance, breaking en-US resolution and every future backend
+ *     load for that namespace.
+ *  2. The backend loader fires at most once per (language, namespace) per
+ *     instance — `queueLoad` short-circuits on `hasResourceBundle` — so
+ *     merging inside `loadBundle` is a first-load mechanism, not a
+ *     steady-state one.
+ *
+ * Therefore: merge at load, and REBUILD the instance on every version bump,
+ * swapping it in through the existing provider seam. That is the only
+ * operation this i18next version performs losslessly.
+ */
+import { createI18n } from './create-i18n.js';
+import { tagForLocale } from './locales.js';
+import { bumpI18nRevision } from './revision.js';
+/**
+ * Merge flat dotted overrides into a (cloned) nested bundle.
+ *
+ * An empty-string value is written through deliberately — it is the third
+ * state, "render nothing" (23 §3.3), and is why `createI18n` sets
+ * `returnEmptyString: true`.
+ */
+export function mergeOverrides(base, flat) {
+    const root = base === null ? {} : structuredClone(base);
+    for (const [path, value] of Object.entries(flat)) {
+        const parts = path.split('.');
+        let node = root;
+        for (let i = 0; i < parts.length - 1; i += 1) {
+            const part = parts[i];
+            const next = node[part];
+            // A key may override a leaf that used to be a subtree (or vice versa);
+            // replace rather than crash.
+            if (typeof next !== 'object' || next === null)
+                node[part] = {};
+            node = node[part];
+        }
+        node[parts[parts.length - 1]] = value;
+    }
+    return root;
+}
+/**
+ * `createI18n` with the override layer folded in.
+ *
+ * en-US overrides are applied through the SAME merge as every other locale,
+ * never through `createI18n`'s `resources` option: that option does
+ * `target[ns] = bundle`, a whole-namespace REPLACEMENT, so routing a sparse
+ * override tree through it would delete the ~1,500 other `common` keys.
+ */
+export async function createI18nWithOverrides(opts) {
+    const { overrides, loadBundle, resources, ...rest } = opts;
+    if (overrides === undefined || Object.keys(overrides).length === 0) {
+        return createI18n(opts);
+    }
+    const enUsOverrides = overrides['en-US'];
+    const mergedEnUs = {};
+    if (enUsOverrides !== undefined) {
+        const { EN_US_RESOURCES } = await import('./resources/index.js');
+        for (const [ns, flat] of Object.entries(enUsOverrides)) {
+            if (flat === undefined)
+                continue;
+            mergedEnUs[ns] = mergeOverrides(EN_US_RESOURCES[ns], flat);
+        }
+    }
+    return createI18n({
+        ...rest,
+        resources: {
+            ...resources,
+            // Full merged namespaces, so the whole-namespace replacement is safe.
+            ...(Object.keys(mergedEnUs).length > 0 ? { 'en-US': mergedEnUs } : {}),
+        },
+        loadBundle: async (tag, ns) => {
+            const base = loadBundle === undefined ? null : await loadBundle(tag, ns);
+            const flat = overrides[tag]?.[ns];
+            const baseBundle = base === null ? null : 'default' in base ? base.default : base;
+            if (flat === undefined)
+                return baseBundle;
+            // Merged HERE rather than after the fact, so a slow compiled chunk
+            // landing later can never clobber an override that was already applied.
+            return { default: mergeOverrides(baseBundle, flat) };
+        },
+    });
+}
+/**
+ * Rebuild the instance with a new override set and hand it back.
+ *
+ * The caller swaps the result into whatever holds the active instance and
+ * calls `bumpI18nRevision()` — which this does for you — so subscribers
+ * re-render. Rebuilding rather than patching is the whole point: see the
+ * module header.
+ */
+export async function rebuildWithOverrides(opts) {
+    const instance = await createI18nWithOverrides(opts);
+    bumpI18nRevision();
+    return instance;
+}
+/** The BCP-47 key an override map uses for a locale id. */
+export function overrideTag(locale) {
+    return tagForLocale(locale);
+}
+//# sourceMappingURL=overrides.js.map

package/dist/overrides.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"overrides.js","sourceRoot":"","sources":["../src/overrides.ts"],"names":[],"mappings":"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"}

package/dist/react.d.ts

@@ -5,6 +5,12 @@ import { type LocaleId } from './locales.js';
 export interface I18nContextValue {
     i18n: I18nInstance;
     locale: LocaleId;
+    /**
+     * Bumps whenever resolved text changes without the language changing —
+     * i.e. when runtime overrides are applied (23 §4.4). Hooks depend on it so
+     * memoized consumers re-render on an admin's edit, not only on a switch.
+     */
+    revision: number;
 }
 export interface I18nProviderProps {
     i18n: I18nInstance;

package/dist/react.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.tsx"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAGvC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAiB,KAAK,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACnE,OAAO,EAA4C,KAAK,QAAQ,EAAE,MAAM,cAAc,CAAC;AAEvF,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,YAAY,CAAC;IACnB,MAAM,EAAE,QAAQ,CAAC;CAClB;AAID,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,YAAY,CAAC;IACnB,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED,wBAAgB,YAAY,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,iBAAiB,GAAG,SAAS,CAgB7E;AAQD,kEAAkE;AAClE,wBAAgB,OAAO,IAAI,YAAY,CAEtC;AAED,gEAAgE;AAChE,wBAAgB,SAAS,IAAI,QAAQ,CAEpC;AAED,gEAAgE;AAChE,wBAAgB,MAAM,IAAI,OAAO,CAEhC;AAED,4EAA4E;AAC5E,wBAAgB,IAAI,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,CAShG;AAED,gFAAgF;AAChF,wBAAgB,YAAY,IAAI,gBAAgB,GAAG,IAAI,CAEtD;AAmBD;;;;;;GAMG;AACH,wBAAgB,SAAS,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,CAUrG;AAED,yEAAyE;AACzE,wBAAgB,MAAM,IAAI,UAAU,CAGnC;AAED,0CAA0C;AAC1C,eAAO,MAAM,aAAa,eAAS,CAAC"}
+{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.tsx"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAErD,OAAO,EAAiB,KAAK,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACnE,OAAO,EAA4C,KAAK,QAAQ,EAAE,MAAM,cAAc,CAAC;AAGvF,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,YAAY,CAAC;IACnB,MAAM,EAAE,QAAQ,CAAC;IACjB;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAC;CAClB;AAID,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,YAAY,CAAC;IACnB,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED,wBAAgB,YAAY,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,iBAAiB,GAAG,SAAS,CAqB7E;AAQD,kEAAkE;AAClE,wBAAgB,OAAO,IAAI,YAAY,CAEtC;AAED,gEAAgE;AAChE,wBAAgB,SAAS,IAAI,QAAQ,CAEpC;AAED,gEAAgE;AAChE,wBAAgB,MAAM,IAAI,OAAO,CAEhC;AAED,4EAA4E;AAC5E,wBAAgB,IAAI,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,CAUhG;AAED,gFAAgF;AAChF,wBAAgB,YAAY,IAAI,gBAAgB,GAAG,IAAI,CAEtD;AAKD;;;;;;GAMG;AACH,wBAAgB,SAAS,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,CAarG;AAED,yEAAyE;AACzE,wBAAgB,MAAM,IAAI,UAAU,CAGnC;AAED,0CAA0C;AAC1C,eAAO,MAAM,aAAa,eAAS,CAAC"}