@pie-element/shared-i18n 0.0.0-stage → 0.1.1-next.20261016234357

package/README.md

@@ -1,3 +1,167 @@
-# Temporary Holding Version
+# @pie-element/shared-i18n
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Interface strings for PIE elements and the libraries they render through: one typed catalog per
+package, `en-US` resident in the bundle, every other locale loaded on demand, and one page-wide
+registry that a host call reaches across every bundled copy of this engine.
+
+The engine is a port of pie-players' `players-shared/src/i18n`. The two repositories share its
+semantics (tag resolution, lookup order, plural handling, host messages) and no code.
+
+`@pie-lib/translator` stays in place for every package not yet migrated;
+[`docs/prds/interface-i18n/PRD.md`](../../../docs/prds/interface-i18n/PRD.md) has the design and
+the migration order.
+
+## Locale resolution
+
+An element translates in the language its item declares in `model.language` (`en_US`, `es_ES`,
+`es-MX`), and in `en-US` when the item declares none. That is `@pie-lib/translator`'s source, kept
+so a migrated element renders as it did; the PRD moves interface strings to a locale the host
+publishes, with `en-US` as the default. The browser locale is never consulted.
+
+A tag resolves by RFC 4647 lookup, then by its primary subtag: `es_MX` reads `es-MX`, then `es`. A
+tag nothing ships renders English key by key, unless a host registered messages for it.
+
+Each key is looked up in order: host messages for the locale, the shipped catalog for the locale,
+host messages for `en-US`, the shipped `en-US` catalog. A miss on all four returns the key.
+
+## For a host
+
+```ts
+import { loadLocale, registerMessages } from '@pie-element/shared-i18n';
+
+// Rename one label, or serve a locale no package ships.
+registerMessages('@pie-lib/correct-answer-toggle', 'en-US', { showCorrectAnswer: 'Reveal answer' });
+registerMessages('@pie-lib/correct-answer-toggle', 'fr-CA', { showCorrectAnswer: 'Afficher la réponse' });
+
+// Optional: load a locale before mounting, so nothing renders while it loads.
+await loadLocale('es-MX');
+```
+
+`registerMessages` applies to every copy of the package on the page and to copies evaluated later;
+an element already rendered picks the messages up on its next render. A plural group replaces the
+shipped group whole, so a host's wording never mixes with the shipped forms.
+
+## For an element
+
+The delivery element holds its first render until the locale is resident, then stamps its own host:
+
+```ts
+import { isLocaleReady, loadLocale, stampElementLanguage } from '@pie-element/shared-i18n';
+import { catalogs } from '../i18n/index.js';
+
+private _rerender() {
+  const language = this._model?.language;
+  if (!isLocaleReady(language)) {
+    void loadLocale(language).then(() => this._rerender());
+    return;
+  }
+  stampElementLanguage(this, language);
+  // …render; `catalogs.forLocale(language).t('multipleChoiceQuestion')`
+}
+```
+
+`isLocaleReady` and `loadLocale` cover every catalog set evaluated on the page, so one wait covers
+the libraries the element renders through. `loadLocale` never rejects: a failed chunk is reported
+once and renders English.
+
+`stampElementLanguage` sets `lang` and `dir` on the element's host for a declared language and
+removes both otherwise. The host wraps authored content, and content that declares no language
+inherits the page's instead of being asserted English. It never writes `document.documentElement`.
+
+## For a library component
+
+A library component cannot assume the element rendering it waited for the locale: an element still
+on `@pie-lib/translator` never calls `loadLocale`. It passes its re-render to `forLocale`, which
+starts the load and calls back once:
+
+```tsx
+relabel = () => this.forceUpdate();
+
+render() {
+  const i18n = catalogs.forLocale(this.props.language, this.relabel);
+  const showMessage = this.props.showMessage ?? i18n.t('showCorrectAnswer');
+}
+```
+
+Under a migrated element the locale is already resident and the callback never runs. Under an
+unmigrated one the component renders one English frame, then the locale. A label the caller passes
+wins over the catalog.
+
+## Catalogs
+
+Each package keeps its strings in `src/i18n/`:
+
+| File | Holds |
+|---|---|
+| `en-US.ts` | The source catalog, imported statically. Its shape types every key. |
+| `<tag>.ts` | One file per shipped locale, `satisfies MessageCatalog`. |
+| `index.ts` | `defineCatalogs({ packageName, source, loaders })`. |
+| `catalog-manifest.json` | Each locale's status and provenance. |
+
+```ts
+export const catalogs = defineCatalogs({
+  packageName: '@pie-element/multiple-choice',
+  source: enUS,
+  loaders: { es: () => import(/* webpackMode: "eager" */ './es.js') },
+});
+```
+
+The `webpackMode: "eager"` comment survives the Vite build into `dist/i18n/index.js`. The browser
+ESM build splits the locale into its own chunk; the webpack bundles built from npm, which load
+chunks relative to the host page and cannot fetch one, inline it. The IIFE build drops every loader
+(`tools/vite/iife-english-only-catalogs.ts`) and ships English; its host registers any other locale
+with `registerMessages`.
+
+A key missing from `en-US.ts` is a compile error. A key assembled at runtime from an id the catalog
+cannot enumerate goes through `dynamicMessageKey(key)`.
+
+Conventions:
+
+- `{placeholder}` slots interpolate, with the same names in every locale. i18next's `{{name}}`
+  renders literally and fails the gate.
+- A plural group is an object of CLDR categories with `other` required. `Intl.PluralRules` selects,
+  so a locale may carry forms English lacks (Arabic `few`, Polish `many`). Call `plural()`, never a
+  `count === 1` branch.
+- Keys ending `A11y` are for assistive technology only.
+- Author whole phrases. Concatenating fragments, or lower-casing one, is an English-only transform.
+- Developer diagnostics (`throw`, `console`) stay English and stay out of catalogs.
+
+## Adding or changing a key
+
+1. Add or change it in `en-US.ts`.
+2. Add it to every locale file. A missing key falls back to English silently, so the gate fails it.
+3. For a `reviewed` locale, translate the key, then move the anchor:
+   `bun scripts/write-i18n-english-snapshot.mjs packages/<group>/<pkg>/src/i18n es`.
+
+`bun run verify:i18n-catalogs`, part of `bun run lint`, checks every `src/i18n` directory: locale
+file, loader and manifest entry present together; key parity both ways; leaf kind; `other` in every
+plural group; placeholder parity per form; no `{{slot}}`.
+
+Freshness follows the manifest status. `generated` is machine output nobody reviewed: it records the
+hash of the English it came from, fails on any English change, and regenerates whole. `reviewed`
+carries human work regeneration must not clobber: the manifest holds the English each key was
+reviewed against, and only the keys whose English moved fail.
+
+## Locales
+
+| Tag | Status | Serves |
+|---|---|---|
+| `en-US` | source | every tag nothing else matches |
+| `es` | reviewed, carried from `@pie-lib/translator` | every `es-*` tag; Latin American wording |
+
+## Build artifacts
+
+`tests/interface-i18n-artifacts.test.ts` holds each migrated element's built bundles to the
+contract: English in the static graph of the browser delivery and print views and in the IIFE,
+every other shipped locale outside that graph and absent from the IIFE, no i18next in either, and
+every loader eager. A newly migrated element joins its `migratedElements` list.
+
+## Module layout
+
+| Module | Owns |
+|---|---|
+| `provider.ts` | `SimpleI18n`: lookup, interpolation, plurals, direction, formatting |
+| `catalogs.ts` | `defineCatalogs`, the page registry, `isLocaleReady`, `loadLocale`, `registerMessages` |
+| `language-tags.ts` | Tag normalization and RFC 4647 matching |
+| `element-language.ts` | `lang` and `dir` for an element's host |
+| `types.ts` | Catalog, key and translator types |

package/dist/catalogs.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Per-package catalogs and the page-wide registry that ties them together.
+ *
+ * The package that renders a string owns it: an element and each library on its render path
+ * define their own catalogs with `defineCatalogs`. The `en-US` catalog is a static import of the
+ * defining module, so the typical English render needs no load; every other locale is a loader
+ * the bundler can split.
+ *
+ * An element renders through libraries whose catalogs it does not know, so readiness is asked of
+ * the page: `isLocaleReady` and `loadLocale` cover every catalog set evaluated on it. The
+ * registry lives on `globalThis` under `Symbol.for`, because every IIFE bundle and every
+ * webpack-built player bundle carries its own copy of this engine, and one host call has to
+ * reach all of them.
+ */
+import type { CatalogLoader, MessageCatalog, NestedKeys, Translator } from './types.js';
+export interface CatalogsOptions<C extends MessageCatalog> {
+    /** The npm package that owns these strings; host messages are registered against it. */
+    packageName: string;
+    /** The `en-US` catalog, imported statically by the defining module. */
+    source: C;
+    /**
+     * Every other shipped locale by BCP-47 tag. Write each as
+     * `() => import(/* webpackMode: "eager" *\/ './es-ES.js')`: Vite's browser build still splits
+     * it, the IIFE build drops it, and the multi-element webpack builds, which load chunks relative
+     * to the host page, inline it instead of emitting a chunk they cannot fetch.
+     */
+    loaders?: Readonly<Record<string, CatalogLoader>>;
+}
+export interface Catalogs<C extends MessageCatalog> {
+    readonly packageName: string;
+    /** Shipped locale tags, `en-US` first. */
+    readonly locales: readonly string[];
+    /**
+     * A translator fixed to `locale`, `en-US` when none is given. Synchronous: it renders what is
+     * resident and English for any key it lacks.
+     *
+     * With `onLoad`, a locale that is not resident starts loading and `onLoad` runs once the load
+     * settles. A library component passes its re-render, because the element rendering it may
+     * never call `loadLocale`; an element that does call it first renders no English frame.
+     */
+    forLocale(locale?: string | null, onLoad?: () => void): Translator<NestedKeys<C>>;
+    /** Whether `locale` would load a catalog for this package. */
+    needsLoad(locale: string): boolean;
+    /** Load `locale` for this package; a failed load is reported once and then served as English. */
+    load(locale: string): Promise<void>;
+}
+/** Define one package's catalogs and register them on the page. */
+export declare function defineCatalogs<C extends MessageCatalog>(options: CatalogsOptions<C>): Catalogs<C>;
+/** Whether every catalog set on the page renders `locale` without a load. */
+export declare function isLocaleReady(locale: string | null | undefined): boolean;
+/** Load `locale` for every catalog set on the page. Never rejects; a failure renders English. */
+export declare function loadLocale(locale: string | null | undefined): Promise<void>;
+/**
+ * Supply or override one package's messages for one locale, deep-merged over what it ships.
+ *
+ * The runtime injection channel: a host renames a label, or serves a locale no package ships,
+ * without a rebuild. It applies to every copy of that package on the page and to copies
+ * evaluated later. An element already rendered picks the messages up on its next render.
+ */
+export declare function registerMessages(packageName: string, locale: string, messages: MessageCatalog): void;

package/dist/element-language.d.ts

@@ -0,0 +1,21 @@
+/**
+ * `lang` and `dir` for an element's own host, which wraps the item's authored content.
+ *
+ * Both are stamped only for a language the item declares in a usable tag. An item that declares
+ * none, or declares something that is not a language tag (`Spanish`), leaves both off and inherits
+ * the page's: imported content in another language often declares nothing, and a default would
+ * assert English over it. pie-players' content-language design makes the same rule.
+ *
+ * Nothing here touches `document.documentElement`, which belongs to the page.
+ */
+import type { TextDirection } from './types.js';
+export interface LanguageAttributes {
+    lang: string;
+    dir: TextDirection;
+}
+/** The canonical tag for a declared language, or `undefined` when it is not a usable tag. */
+export declare function canonicalLanguageTag(language: string | null | undefined): string | undefined;
+/** `lang` and `dir` for an item that declares `language`; `undefined` when it declares none. */
+export declare function elementLanguageAttributes(language: string | null | undefined): LanguageAttributes | undefined;
+/** Stamp `lang` and `dir` for a declared language on the element's own host, and clear both otherwise. */
+export declare function stampElementLanguage(host: Element, language: string | null | undefined): void;

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { type Catalogs, type CatalogsOptions, defineCatalogs, isLocaleReady, loadLocale, registerMessages, } from './catalogs.js';
+export { canonicalLanguageTag, elementLanguageAttributes, type LanguageAttributes, stampElementLanguage, } from './element-language.js';
+export { findBestLanguageMatch, languageTagLookupSequence, languageTagsEqual, normalizeLanguageTag, toLanguageTag, } from './language-tags.js';
+export { DEFAULT_LOCALE, dynamicMessageKey, localeDirection, SimpleI18n } from './provider.js';
+export type { CatalogLoader, DynamicMessageKey, I18nConfig, I18nServiceApi, InterpolationValues, MessageCatalog, MessageNode, NestedKeys, PluralOptions, PluralTranslation, TextDirection, Translator, } from './types.js';

package/dist/index.js

@@ -0,0 +1,309 @@
+//#region src/language-tags.ts
+function e(e) {
+	return e ? e.trim().replace(/_/g, "-").split(/[.@]/)[0].toLowerCase() : "";
+}
+function t(e) {
+	return e ? e.trim().replace(/_/g, "-") : "";
+}
+function n(t, n) {
+	let r = e(t);
+	return r ? r === e(n) : !1;
+}
+function r(t) {
+	let n = e(t);
+	if (!n) return [];
+	let r = n.split("-"), i = [];
+	for (let e = r.length; e > 0; e--) {
+		let t = r.slice(0, e);
+		t.length > 1 && t[t.length - 1].length === 1 || i.push(t.join("-"));
+	}
+	return i;
+}
+function i(t, n) {
+	for (let i of r(t)) {
+		let t = n.find((t) => e(t) === i);
+		if (t != null) return t;
+	}
+}
+//#endregion
+//#region src/provider.ts
+var a = "en-US";
+function o(e) {
+	return e;
+}
+var s = /* @__PURE__ */ new Set([
+	"ar",
+	"ckb",
+	"dv",
+	"fa",
+	"he",
+	"iw",
+	"ks",
+	"ku",
+	"nqo",
+	"ps",
+	"sd",
+	"syr",
+	"ug",
+	"ur",
+	"yi"
+]), c = /* @__PURE__ */ new Set([
+	"zero",
+	"one",
+	"two",
+	"few",
+	"many",
+	"other"
+]);
+function l(e) {
+	if (typeof e != "object" || !e) return !1;
+	let t = Object.keys(e);
+	return t.length > 0 && t.every((e) => c.has(e));
+}
+function u(t) {
+	try {
+		let e = new Intl.Locale(t).textInfo;
+		if (e?.direction === "rtl" || e?.direction === "ltr") return e.direction;
+	} catch {}
+	let n = e(t).split("-")[0] ?? "";
+	return s.has(n) ? "rtl" : "ltr";
+}
+var d = class n {
+	static {
+		this.pluralRules = /* @__PURE__ */ new Map();
+	}
+	constructor(e) {
+		this.listeners = /* @__PURE__ */ new Set(), this.config = { ...e }, this.fallbackLocale = t(e.fallbackLocale) || "en-US", this.catalogs = /* @__PURE__ */ new Map([[a, e.source]]), this.customMessages = { ...e.customMessages ?? {} }, this.loading = /* @__PURE__ */ new Map(), this.locale = this.resolveLocaleTag(e.locale) ?? "en-US";
+	}
+	getLocale() {
+		return this.locale;
+	}
+	async setLocale(e) {
+		let n = this.resolveLocaleTag(e);
+		if (!n) {
+			this.locale = t(e) || "en-US", this.notify();
+			return;
+		}
+		await this.ensureLoaded(n), this.locale = n, this.notify();
+	}
+	t(e, t) {
+		let n = this.lookup(e);
+		return n === void 0 ? (this.config.onMissingKey?.(e, this.locale), e) : p(n, t);
+	}
+	plural(e, t) {
+		let n = this.lookupNode(e);
+		return n === void 0 || !l(n) ? this.t(e, t) : p(n[this.selectPluralCategory(t.count)] ?? n.other, t);
+	}
+	getDirection() {
+		return u(this.locale);
+	}
+	getAvailableLocales() {
+		return [.../* @__PURE__ */ new Set([
+			...this.catalogs.keys(),
+			...this.config.availableLocales ?? [],
+			...Object.keys(this.customMessages)
+		])];
+	}
+	isLocaleLoaded(e) {
+		let t = this.resolveLocaleTag(e);
+		return t !== void 0 && this.catalogs.has(t);
+	}
+	needsLoad(e) {
+		let t = this.resolveLocaleTag(e);
+		return t !== void 0 && !this.catalogs.has(t) && this.config.availableLocales?.includes(t) === !0;
+	}
+	subscribe(e) {
+		return this.listeners.add(e), () => {
+			this.listeners.delete(e);
+		};
+	}
+	hasKey(e) {
+		return this.lookup(e) !== void 0;
+	}
+	addCustomMessages(e, n) {
+		let r = t(e);
+		this.customMessages[r] = m(this.customMessages[r] ?? {}, n), this.notify();
+	}
+	withLocale(e) {
+		let r = this.resolveLocaleTag(e) ?? t(e);
+		if (r === this.locale) return this;
+		let i = new n({
+			...this.config,
+			locale: r
+		});
+		return i.locale = r || "en-US", i.catalogs = this.catalogs, i.customMessages = this.customMessages, i.loading = this.loading, i;
+	}
+	formatNumber(e, t) {
+		try {
+			return new Intl.NumberFormat(this.locale, t).format(e);
+		} catch {
+			return new Intl.NumberFormat(a, t).format(e);
+		}
+	}
+	formatDate(e, t) {
+		try {
+			return new Intl.DateTimeFormat(this.locale, t).format(e);
+		} catch {
+			return new Intl.DateTimeFormat(a, t).format(e);
+		}
+	}
+	async ensureLoaded(e) {
+		if (this.catalogs.has(e) || !this.config.availableLocales?.includes(e)) return;
+		let t = this.loading.get(e);
+		if (t) {
+			await t;
+			return;
+		}
+		let n = this.loadCatalog(e);
+		this.loading.set(e, n);
+		try {
+			await n;
+		} finally {
+			this.loading.delete(e);
+		}
+	}
+	resolveLocaleTag(t) {
+		if (!t) return;
+		let n = this.getAvailableLocales(), r = i(t, n);
+		if (r) return r;
+		let a = e(t).split("-")[0];
+		if (a) return n.find((t) => e(t).split("-")[0] === a);
+	}
+	async loadCatalog(e) {
+		let t = this.config.loadCatalog;
+		if (t) try {
+			this.catalogs.set(e, await t(e));
+		} catch (t) {
+			throw Error(`Failed to load i18n catalog for locale: ${e}`, { cause: t });
+		}
+	}
+	lookupNode(e) {
+		let t = [
+			this.customMessages[this.locale],
+			this.catalogs.get(this.locale),
+			this.customMessages[this.fallbackLocale],
+			this.catalogs.get(this.fallbackLocale)
+		];
+		for (let n of t) {
+			let t = f(n, e);
+			if (t !== void 0) return t;
+		}
+	}
+	lookup(e) {
+		let t = this.lookupNode(e);
+		if (typeof t == "string") return t;
+		if (t !== void 0 && l(t)) return t.other;
+	}
+	selectPluralCategory(e) {
+		let t = n.pluralRules.get(this.locale);
+		if (!t) {
+			try {
+				t = new Intl.PluralRules(this.locale);
+			} catch {
+				return e === 1 ? "one" : "other";
+			}
+			n.pluralRules.set(this.locale, t);
+		}
+		return t.select(e);
+	}
+	notify() {
+		for (let e of this.listeners) e();
+	}
+};
+function f(e, t) {
+	if (!e) return;
+	let n = e;
+	for (let e of t.split(".")) if (typeof n != "object" || !n || (n = n[e], n === void 0)) return;
+	return n;
+}
+function p(e, t) {
+	return t ? e.replace(/\{(\w+)\}/g, (e, n) => {
+		let r = t[n];
+		return r == null ? e : String(r);
+	}) : e;
+}
+function m(e, t) {
+	let n = { ...e };
+	for (let [e, r] of Object.entries(t)) {
+		let t = n[e];
+		r && typeof r == "object" && t && typeof t == "object" ? n[e] = m(t, r) : n[e] = r;
+	}
+	return n;
+}
+//#endregion
+//#region src/catalogs.ts
+var h = Symbol.for("pie-element.i18n.registry");
+function g() {
+	let e = globalThis;
+	return e[h] || (e[h] = {
+		sets: /* @__PURE__ */ new Set(),
+		messages: /* @__PURE__ */ new Map()
+	}), e[h];
+}
+function _(e) {
+	let t = e.loaders ?? {}, n = g(), r = new d({
+		source: e.source,
+		availableLocales: [a, ...Object.keys(t)],
+		loadCatalog: async (e) => (await t[e]()).default
+	});
+	for (let { locale: t, messages: i } of n.messages.get(e.packageName) ?? []) r.addCustomMessages(t, i);
+	let i = /* @__PURE__ */ new Map(), o = /* @__PURE__ */ new Map(), s = /* @__PURE__ */ new Set(), c = (e) => {
+		let t = e || "en-US", n = i.get(t);
+		return n || (n = r.withLocale(t), i.set(t, n)), n;
+	}, l = {
+		packageName: e.packageName,
+		locales: [a, ...Object.keys(t)],
+		forLocale: (e, t) => (t && e && l.needsLoad(e) && l.load(e).then(t), c(e)),
+		needsLoad: (e) => !s.has(e) && r.needsLoad(e),
+		load: (t) => {
+			if (!l.needsLoad(t)) return Promise.resolve();
+			let n = o.get(t);
+			return n || (n = c(t).setLocale(t).catch((n) => {
+				s.add(t), console.warn(`[${e.packageName}]`, n);
+			}).finally(() => o.delete(t)), o.set(t, n)), n;
+		},
+		addCustomMessages: (e, t) => {
+			r.addCustomMessages(e, t), i.clear();
+		}
+	};
+	return n.sets.add(l), l;
+}
+function v(e) {
+	if (!e) return !0;
+	for (let t of g().sets) if (t.needsLoad(e)) return !1;
+	return !0;
+}
+async function y(e) {
+	e && await Promise.all([...g().sets].map((t) => t.load(e)));
+}
+function b(e, t, n) {
+	let r = g(), i = r.messages.get(e) ?? [];
+	i.push({
+		locale: t,
+		messages: n
+	}), r.messages.set(e, i);
+	for (let i of r.sets) i.packageName === e && i.addCustomMessages(t, n);
+}
+//#endregion
+//#region src/element-language.ts
+function x(e) {
+	let n = t(e).split(/[.@]/)[0];
+	if (/^[a-z]{2,3}(-|$)/i.test(n)) try {
+		return Intl.getCanonicalLocales(n)[0];
+	} catch {
+		return;
+	}
+}
+function S(e) {
+	let t = x(e);
+	return t ? {
+		lang: t,
+		dir: u(t)
+	} : void 0;
+}
+function C(e, t) {
+	let n = S(t);
+	n ? (e.setAttribute("lang", n.lang), e.setAttribute("dir", n.dir)) : (e.removeAttribute("lang"), e.removeAttribute("dir"));
+}
+//#endregion
+export { a as DEFAULT_LOCALE, d as SimpleI18n, x as canonicalLanguageTag, _ as defineCatalogs, o as dynamicMessageKey, S as elementLanguageAttributes, i as findBestLanguageMatch, v as isLocaleReady, r as languageTagLookupSequence, n as languageTagsEqual, y as loadLocale, u as localeDirection, e as normalizeLanguageTag, b as registerMessages, C as stampElementLanguage, t as toLanguageTag };

package/dist/language-tags.d.ts

@@ -0,0 +1,31 @@
+/**
+ * BCP-47 language tag comparison, ported from pie-players
+ * (`players-shared/src/i18n/language-tags.ts`) so both repositories resolve a tag the same way.
+ *
+ * Content producers disagree on syntax: the authoring surface offers POSIX `es_ES`, the
+ * Learnosity transform emits POSIX, QTI carries BCP-47 `xml:lang`. Comparison runs on the
+ * normalized form; rendering uses `toLanguageTag`.
+ */
+/**
+ * Canonical comparison key: POSIX underscores become hyphens, a POSIX charset or modifier
+ * suffix (`es_ES.UTF-8`, `es_ES@euro`) is stripped, and the result is lowercased. Empty for
+ * nullish or blank input, which callers read as "declares no language".
+ */
+export declare function normalizeLanguageTag(tag: string | null | undefined): string;
+/**
+ * A tag in BCP-47 syntax with its authored casing kept, so `es_ES` renders as `es-ES`: the
+ * form for a `lang` attribute or an `Intl` API. Empty for nullish or blank input.
+ */
+export declare function toLanguageTag(tag: string | null | undefined): string;
+/** Whether two tags denote the same locale, ignoring separator style and case. */
+export declare function languageTagsEqual(a: string | null | undefined, b: string | null | undefined): boolean;
+/**
+ * The RFC 4647 lookup sequence for a tag, most specific first: `es-MX` yields
+ * `["es-mx", "es"]`. Truncation never stops on a singleton subtag (RFC 4647 §3.4).
+ */
+export declare function languageTagLookupSequence(tag: string | null | undefined): string[];
+/**
+ * Best available tag for a request by RFC 4647 lookup, or `undefined`. Ranked by the
+ * request's specificity, so `es-MX` prefers an `es-MX` candidate over an `es` one.
+ */
+export declare function findBestLanguageMatch(requested: string | null | undefined, available: readonly (string | null | undefined)[]): string | undefined;

package/dist/provider.d.ts

@@ -0,0 +1,83 @@
+/**
+ * The provider, ported from pie-players' `SimpleI18n`
+ * (`players-shared/src/i18n/provider.ts`): the same resolution order, fallback chain, plural
+ * selection and `{placeholder}` syntax, so a string resolves identically on either side of the
+ * player/element boundary.
+ *
+ * Two differences, both from catalog ownership. The `en-US` catalog arrives as `config.source`
+ * rather than a static import, because each element package owns its strings. And the browser
+ * locale is never consulted at all: pie-players exports a detector a host may opt into; an
+ * element has no host to opt in for it.
+ */
+import type { DynamicMessageKey, I18nConfig, I18nServiceApi, InterpolationValues, MessageCatalog, NestedKeys, PluralOptions, TextDirection } from './types.js';
+/** The locale every fallback chain terminates at. */
+export declare const DEFAULT_LOCALE = "en-US";
+/**
+ * Assert that a runtime-assembled string is a message key, for a key built from an id the
+ * catalog cannot enumerate. Unchecked: pair it with `hasKey` where a miss must not reach the
+ * screen.
+ */
+export declare function dynamicMessageKey(key: string): DynamicMessageKey;
+/** Writing direction of a locale tag. */
+export declare function localeDirection(locale: string): TextDirection;
+/**
+ * Catalogs are BCP-47 keyed and resolved through RFC 4647 lookup, and plural categories come
+ * from `Intl.PluralRules`. Never writes `lang` or `dir` anywhere: stamping is the component's
+ * job, on its own host.
+ */
+export declare class SimpleI18n<C extends MessageCatalog = MessageCatalog> implements I18nServiceApi<NestedKeys<C>> {
+    /** Shared across instances and views: `Intl.PluralRules` is not cheap. */
+    private static readonly pluralRules;
+    private locale;
+    private readonly fallbackLocale;
+    /** Shared by reference with every `withLocale` view. */
+    private catalogs;
+    private customMessages;
+    private loading;
+    private readonly listeners;
+    private readonly config;
+    constructor(config: I18nConfig<C>);
+    getLocale(): string;
+    /**
+     * Resolve the request against the catalogs this provider can serve, load the winner if it is
+     * not resident, then notify, in that order, so a re-render reads a catalog already in place.
+     */
+    setLocale(locale: string): Promise<void>;
+    t(key: NestedKeys<C> | DynamicMessageKey, values?: InterpolationValues): string;
+    /** A category the catalog does not carry resolves to `other`. */
+    plural(key: NestedKeys<C> | DynamicMessageKey, options: PluralOptions): string;
+    getDirection(): TextDirection;
+    /** Resident catalogs, whatever the loader declares, and any locale with host messages. */
+    getAvailableLocales(): string[];
+    isLocaleLoaded(locale: string): boolean;
+    /**
+     * Whether `setLocale(locale)` would load anything: false once the shipped catalog is resident,
+     * and for a locale nothing ships, which the fallback chain answers synchronously.
+     */
+    needsLoad(locale: string): boolean;
+    subscribe(listener: () => void): () => void;
+    hasKey(key: NestedKeys<C> | DynamicMessageKey): boolean;
+    /** Deep-merged, so a deployment overrides a single label without restating a catalog. */
+    addCustomMessages(locale: string, messages: MessageCatalog): void;
+    /**
+     * A view fixed to another locale. Catalogs, in-flight loads and custom messages are shared by
+     * reference, so two elements on one page render different locales from one parsed catalog
+     * each.
+     */
+    withLocale(locale: string): SimpleI18n<C>;
+    formatNumber(value: number, options?: Intl.NumberFormatOptions): string;
+    formatDate(date: Date, options?: Intl.DateTimeFormatOptions): string;
+    /** Load a declared locale's catalog once, however many views ask concurrently. */
+    private ensureLoaded;
+    /**
+     * RFC 4647 lookup first, so `es-MX` reaches an `es` catalog; then primary-subtag widening,
+     * so a bare `es` or a POSIX `es_ES` reaches a regional catalog.
+     */
+    private resolveLocaleTag;
+    private loadCatalog;
+    /** Host overrides for the active locale win, then its catalog, then the fallback pair. */
+    private lookupNode;
+    private lookup;
+    private selectPluralCategory;
+    private notify;
+}

package/dist/types.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Catalog and provider types, kept free of runtime values so a component can import the whole
+ * contract with `import type`.
+ *
+ * Mirrors pie-players' `players-shared/src/i18n/types.ts`, generic over the catalog: there each
+ * key derives from the one `en-US` catalog the repository ships, here every element and library
+ * owns its own catalog and its keys derive from that.
+ */
+/**
+ * Plural forms keyed by CLDR plural category. Only `other` is required: `Intl.PluralRules`
+ * selects the category for the active locale, and a category the catalog lacks resolves to
+ * `other`.
+ */
+export interface PluralTranslation {
+    zero?: string;
+    one?: string;
+    two?: string;
+    few?: string;
+    many?: string;
+    other: string;
+}
+/** A catalog node: a leaf string, a plural group, or a namespace. */
+export type MessageNode = string | PluralTranslation | {
+    [key: string]: MessageNode;
+};
+/** A whole catalog, as one locale module default-exports it. */
+export type MessageCatalog = {
+    [key: string]: MessageNode;
+};
+type PluralCategoryKey = keyof PluralTranslation;
+/**
+ * Dot-notation keys of a catalog shape. A plural group terminates the path at the group, so
+ * `plural('maxSelections', …)` is typed and `'maxSelections.other'` is not. A group is
+ * recognized by every one of its keys being a CLDR category.
+ */
+export type NestedKeys<T> = {
+    [K in keyof T & string]: T[K] extends string ? K : keyof T[K] extends PluralCategoryKey ? K : T[K] extends object ? K | `${K}.${NestedKeys<T[K]>}` : K;
+}[keyof T & string];
+/**
+ * A key assembled at runtime from an id the catalog cannot enumerate. Branded, so the only way
+ * to produce one is `dynamicMessageKey` and a mistyped literal stays a compile error. The brand
+ * is a named property because a `unique symbol` is not identity-compatible across two emitted
+ * copies of this declaration.
+ */
+export type DynamicMessageKey = string & {
+    readonly __pieDynamicMessageKey: true;
+};
+/** Interpolation values substituted into `{placeholder}` slots. */
+export type InterpolationValues = Record<string, string | number | boolean | null | undefined>;
+/** Options for `plural`; `count` also interpolates. */
+export interface PluralOptions extends InterpolationValues {
+    count: number;
+}
+/** Writing direction of a locale. */
+export type TextDirection = 'ltr' | 'rtl';
+/** Loader for one shipped locale's catalog module. */
+export type CatalogLoader = () => Promise<{
+    default: MessageCatalog;
+}>;
+/** Provider configuration. */
+export interface I18nConfig<C extends MessageCatalog = MessageCatalog> {
+    /** The `en-US` catalog, bundled statically: the fallback for every key and the source of key types. */
+    source: C;
+    /** Initial locale. Defaults to `en-US`; never detected from the browser. */
+    locale?: string;
+    /** Locale every missing key falls back to. Defaults to `en-US`. */
+    fallbackLocale?: string;
+    /** Loader for a shipped locale. Omitted, only `source` and `customMessages` are available. */
+    loadCatalog?: (locale: string) => Promise<MessageCatalog>;
+    /** Locale tags `loadCatalog` can serve. */
+    availableLocales?: readonly string[];
+    /**
+     * Host-supplied messages keyed by locale tag, consulted ahead of the shipped catalog for the
+     * same locale: a host can rename one label without a fork, and supply a locale nobody ships.
+     */
+    customMessages?: Record<string, MessageCatalog>;
+    /** Called once per missing key per lookup. */
+    onMissingKey?: (key: string, locale: string) => void;
+}
+/**
+ * What a component translates through, typed by its own catalog's keys. Framework-free, so
+ * React and Svelte components share it.
+ */
+export interface Translator<K extends string = string> {
+    /** Active locale tag, canonicalized to the resolved catalog's tag. */
+    getLocale(): string;
+    /** Translate a key, interpolating `{placeholder}` slots; a miss returns the key. */
+    t(key: K | DynamicMessageKey, values?: InterpolationValues): string;
+    /** Translate a plural group, selecting the CLDR category for `options.count`. */
+    plural(key: K | DynamicMessageKey, options: PluralOptions): string;
+    /** Writing direction of the active locale. */
+    getDirection(): TextDirection;
+    /** Whether a key resolves in the active locale or its fallback chain. */
+    hasKey(key: K | DynamicMessageKey): boolean;
+}
+/** The full service surface of the bundled provider. */
+export interface I18nServiceApi<K extends string = string> extends Translator<K> {
+    /** Switch locale, loading its catalog first; subscribers are notified once it is in place. */
+    setLocale(locale: string): Promise<void>;
+    /** Locale tags this provider can serve. */
+    getAvailableLocales(): string[];
+    /** Whether a locale's catalog is already resident. */
+    isLocaleLoaded(locale: string): boolean;
+    /** Whether `setLocale(locale)` would load a catalog. */
+    needsLoad(locale: string): boolean;
+    /** Observe locale and catalog changes. Returns an unsubscribe function. */
+    subscribe(listener: () => void): () => void;
+    /** Add or override messages for one locale, deep-merged. */
+    addCustomMessages(locale: string, messages: MessageCatalog): void;
+    /** A view fixed to another locale, sharing catalogs, loads and custom messages. */
+    withLocale(locale: string): I18nServiceApi<K>;
+    formatNumber(value: number, options?: Intl.NumberFormatOptions): string;
+    formatDate(date: Date, options?: Intl.DateTimeFormatOptions): string;
+}
+export {};

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "@pie-element/shared-i18n",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1-next.20261016234357",
+  "description": "Interface-string i18n engine for PIE elements: typed per-package catalogs, lazy locales, RFC 4647 resolution",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "rm -rf dist tsconfig.tsbuildinfo && vite build && tsc --emitDeclarationOnly",
+    "dev": "vite build --watch",
+    "test": "vitest",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {},
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pie-framework/pie-elements-ng.git",
+    "directory": "packages/shared/i18n"
+  },
+  "homepage": "https://github.com/pie-framework/pie-elements-ng#readme",
+  "bugs": {
+    "url": "https://github.com/pie-framework/pie-elements-ng/issues"
+  }
+}