@lssm/lib.translation-runtime 3.0.1

package/README.md

@@ -0,0 +1,166 @@
+# @lssm/lib.translation-runtime
+
+Framework-independent runtime for ContractSpec translation contracts.
+
+`@lssm/lib.contracts-spec` remains the canonical source of truth for `TranslationSpec` contracts, metadata, ownership, versions, locale variants, validation, fallback declarations, and override policy. This package consumes those specs at runtime to resolve, format, cache, load, diagnose, and serialize translations across server code, React, React Native, CLIs, and tests.
+
+## Boundaries
+
+- **Spec layer:** `@lssm/lib.contracts-spec/translations`
+- **Runtime layer:** this package
+- **Formatter engine:** `MessageFormatter`, with `createIntlMessageFormatter()` backed by FormatJS/`intl-messageformat`
+- **Adapters:** React/design-system/i18next integrations consume this runtime and are optional downstream layers
+
+## Example
+
+```ts
+import { createTranslationRuntime } from "@lssm/lib.translation-runtime";
+import { enMessages, frMessages } from "./catalogs";
+
+const runtime = createTranslationRuntime({
+  defaultLocale: "en-US",
+  requestedLocales: ["fr-FR", "en-US"],
+  specs: [enMessages, frMessages],
+});
+
+runtime.t("cart.itemCount", { count: 3 });
+```
+
+## SSR and hydration — factory stack (preferred)
+
+Use the factory-stack snapshot surface from `@lssm/lib.contracts-spec/translations` for new integrations. It produces a versioned, framework-neutral `I18nFactoryHydrationPayload` that never aliases live catalog references:
+
+```ts
+import {
+  createI18nFactory,
+  createI18nFactoryFromHydrationPayload,
+} from "@lssm/lib.contracts-spec/translations";
+import { loadShardDelta, createStaticBundleLoader } from "@lssm/lib.translation-runtime/loader";
+
+// Server (RSC / route handler)
+const factory = createI18nFactory({
+  catalogs: [enMessages, frMessages, esMessages],
+  supportedLocales: ["en", "fr", "es"],
+  defaultLocale: "en",
+});
+const payload = factory.hydrationPayload(undefined, requestLocale);
+// Transfer payload to the client (inline script, RSC stream, etc.)
+
+// Client — rehydrate without refetching or renegotiating locale
+const instance = createI18nFactoryFromHydrationPayload(payload);
+instance.t("greeting", { name: "Alice" });
+
+// Navigation: lazy-load only new shards
+const loader = createStaticBundleLoader(allCatalogs);
+await loadShardDelta({ loaded: sharedSpecKeys, required: pageSpecKeys, locales: [locale] }, loader);
+```
+
+`validateI18nFactorySnapshot(snapshot)` returns human-readable error strings for partial or unknown snapshots before hydration.
+
+## SSR and hydration — deprecated runtime (compat only)
+
+> **Deprecated.** `createTranslationRuntime` is dead-but-present. `createTranslationRuntimeFromPreferences` remains as a compat shim. Do not add new call sites to the active SSR render path. Engine deletion is a residual follow-up; see `.omc/plans/ralplan-translation-catalog-sharding-ssr.md`.
+
+```ts
+import { createTranslationRuntime } from "@lssm/lib.translation-runtime";
+// … (legacy pattern preserved for compat)
+```
+
+`createTranslationSnapshotStreamChunk(snapshot)` returns a cloned payload safe to enqueue before later async catalog loads mutate the request runtime. `validateTranslationHydrationPayload(payload)` returns `invalid_snapshot` diagnostics for unsupported payloads before hydration.
+
+## Shard-scoped catalog loading
+
+`src/loader.ts` accepts an optional `specKeys?` array on `TranslationBundleLoadRequest` to load a subset of catalogs per route. Use `loadShardDelta` to fetch only the incremental shards needed on navigation:
+
+```ts
+import { computeShardDelta, loadShardDelta } from "@lssm/lib.translation-runtime/loader";
+
+const delta = computeShardDelta(alreadyLoadedSpecKeys, requiredSpecKeys);
+// delta = requiredSpecKeys not yet loaded
+
+const newCatalogs = await loadShardDelta(
+  { loaded: alreadyLoadedSpecKeys, required: requiredSpecKeys, locales: [locale] },
+  bundleLoader,
+);
+```
+
+Absent `specKeys` ⇒ all keys pass (existing `{specKey, locales}` semantics unchanged).
+
+## Optimization surfaces (Model A — per-request inline payload)
+
+> **Scope: per-request inline HTML reduction.** Catalogs remain bundled and cached in the JS bundle (shipped once per deploy). These optimizations reduce the per-request inline `<script>` hydration payload — NOT total transferred bytes. The ~90% total-bytes win requires Model B (catalog code-splitting + load-bearing inline payload). See `.omc/plans/ralplan-translation-catalog-sharding-ssr.md` § "Optimization Wave — ARCHITECTURE DECISION: Model A".
+
+### O2/O3 — Slim inline payload + value-pool dedup
+
+Enable slim mode on your scoped hydration builder to strip spec metadata from each shard before serialization. The value-pool dedup step folds message values appearing ≥2× into a `values[]` pool; expansion is automatic on rehydration.
+
+**Realized:** `/` en 96.6 KB → 37.8 KB (−61%); `/companyos/founder` en 93.9 KB → 35.6 KB (−62%); fr routes ~−60%. No-flash (AC1) re-proven through slim+dedup path. CI budget gates: single-locale ≤ 64 KB, with-fallback ≤ 128 KB.
+
+O3 adds only ~2% over O2 (five lanes have disjoint key namespaces; ~53 pooled value strings). The projected ~41 KB en-fallback win requires a shared-base architecture follow-up.
+
+### O4 — Precompiled ICU AST fast-path (`./precompile` subpath)
+
+At bundle build time, call `buildPrecompiledIcuCatalogFromSpecs(specs)` from `@lssm/lib.translation-runtime/precompile` over your `TranslationSpec[]` set. This produces a `PrecompiledIcuCatalog` with FormatJS IR AST entries for every message. Pass `createPrecompiledIcuLookup(catalog)` as the `precompiled` option to `createIntlMessageFormatter` to activate the parse-skip fast-path:
+
+```ts
+// build step (runs once at bundle time, e.g. in your bundler plugin)
+import {
+  buildPrecompiledIcuCatalogFromSpecs,
+  createPrecompiledIcuLookup,
+  serializePrecompiledIcuCatalog,
+} from "@lssm/lib.translation-runtime/precompile";
+
+const catalog = buildPrecompiledIcuCatalogFromSpecs([enMessages, frMessages]);
+// optionally serialize and ship as a build asset
+const serialized = serializePrecompiledIcuCatalog(catalog);
+
+// runtime (wire the formatter with the precompiled lookup)
+import { parsePrecompiledIcuCatalog, createPrecompiledIcuLookup } from "@lssm/lib.translation-runtime/precompile";
+import { createIntlMessageFormatter } from "@lssm/lib.translation-runtime/formatters/intl-messageformat";
+
+const precompiled = createPrecompiledIcuLookup(parsePrecompiledIcuCatalog(serialized));
+const formatter = createIntlMessageFormatter({ precompiled });
+// formatter skips ICU re-parsing for any message with a precompiled entry
+```
+
+Additive opt-in — messages without a precompiled entry fall back to the standard parser transparently. **Scope: formatter-path latency win only.** Factory proof routes use `{placeholder}` interpolation (no ICU); O4 benefits apply to ICU-heavy catalogs (plural/select/date/number).
+
+### O5b (#17) — Scoped-hydration intersection (wired, currently no-op)
+
+> **App-layer wiring — not a `translation-runtime` export.** `intersectScopedI18nHydration` and `isEffectiveReachabilityMap` are implemented in `web-application-monolith`'s scoped hydration path (`packages/apps/web-application-monolith/src/i18n/scoped-hydration.reachability.ts` and `reachability-map.loader.ts`). They compose with the loader's `loadShardDelta` but are not themselves library APIs. Do not import them from `@lssm/lib.translation-runtime`.
+
+Wired into `getRequestI18n` and fail-safe (pruned keys resolve via the bundled combined runtime — no flash). Currently no-op (77/129 `t()` call sites use dynamic dispatch; scanner emits retain-all map). Auto-activates if a precise reachability map ships. Zero regression.
+
+### O5 (#14) — Dead-key audit tool (`@lssm/tool.i18n-prune`)
+
+`@lssm/tool.i18n-prune` in `packages/tools/` walks `t('key')` call sites against a `RouteShardManifest` and reports dead keys per route. Use it in CI to surface dead-key drift. It does not drive the runtime inline payload under Model A.
+
+## Optional i18next adapter
+
+i18next is an optional downstream adapter, not the canonical ContractSpec model. Import it through the dedicated subpath so core runtime consumers do not load i18next:
+
+```ts
+import { createInstance } from "i18next";
+import {
+  createI18nextInitOptions,
+  exportTranslationSnapshotToI18next,
+} from "@lssm/lib.translation-runtime/i18next";
+
+const exported = exportTranslationSnapshotToI18next(runtime.snapshot(), {
+  assumeIcuFormatter: true,
+});
+const { options, diagnostics } = createI18nextInitOptions(exported);
+const i18next = createInstance();
+
+await i18next.init(options);
+```
+
+The adapter exports resources as `{ [locale]: { [namespace]: { [messageKey]: string } } }`. `TranslationSpec.locale` becomes the i18next language, while the namespace defaults to the stable `TranslationSpec.meta.key`. Flat ContractSpec keys such as `"cart.items"` remain flat because generated init options set `keySeparator: false`.
+
+ContractSpec ICU messages are exported intact. i18next does not use ICU as its default JSON format, so apps that call `i18next.t()` for ICU plural/select/selectordinal messages must install and configure an ICU-capable i18next format plugin such as `i18next-icu`. The adapter reports `i18next_icu_plugin_required` unless you explicitly acknowledge that formatting layer.
+
+For SSR, export from the same runtime snapshot used by the server render and reuse those resources/options on the client. Do not let client-only language detection renegotiate the first hydrated render. For React Native, pass the host-selected locale explicitly; the adapter does not use DOM APIs or browser storage.
+
+## React Native
+
+The core runtime uses no DOM APIs. Locale detection is host-owned; pass device or user locales into `requestedLocales`. Ensure the host JS engine provides the required `Intl` APIs or install platform polyfills before using the default formatter.

package/dist/adapters/i18next-export.d.ts

@@ -0,0 +1,2 @@
+import type { ContractSpecI18nextExport, ContractSpecI18nextExportOptions, ContractSpecI18nextSourceSpec } from './i18next-types.js';
+export declare function buildI18nextExport(sources: readonly ContractSpecI18nextSourceSpec[], options: ContractSpecI18nextExportOptions): ContractSpecI18nextExport;

package/dist/adapters/i18next-helpers.d.ts

@@ -0,0 +1,8 @@
+import type { TranslationSpec } from '@lssm/lib.contracts-spec/translations';
+import type { ContractSpecI18nextDiagnostic, ContractSpecI18nextExportOptions, ContractSpecI18nextFallbackLng, ContractSpecI18nextNamespace, ContractSpecI18nextNamespaceStrategy } from './i18next-types.js';
+export declare function namespaceForSpec(spec: TranslationSpec, strategy?: ContractSpecI18nextNamespaceStrategy): string;
+export declare function buildSpecFallbackChain(spec: TranslationSpec, defaultLocale: string): string[];
+export declare function canonicalLocale(locale: string, diagnostics: ContractSpecI18nextDiagnostic[], specKey?: string): string;
+export declare function deriveFallbackLng(namespaces: readonly ContractSpecI18nextNamespace[], options: ContractSpecI18nextExportOptions, diagnostics: ContractSpecI18nextDiagnostic[]): ContractSpecI18nextFallbackLng | undefined;
+export declare function hasIncompatibleFallbackChains(namespaces: readonly ContractSpecI18nextNamespace[]): boolean;
+export declare function unique(values: readonly string[]): string[];

package/dist/adapters/i18next-types.d.ts

@@ -0,0 +1,93 @@
+import type { Locale, MessageVariant, PlaceholderDef, PluralRuleSet, TranslationSpec } from '@lssm/lib.contracts-spec/translations';
+import type { TextDirection } from '../direction.js';
+import type { OverrideScope } from '../overrides.js';
+export type I18nextResourceStore = Record<string, Record<string, Record<string, string>>>;
+export type ContractSpecI18nextNamespaceStrategy = 'domain' | 'specKey' | ((spec: TranslationSpec) => string);
+export type ContractSpecI18nextFallbackLng = false | string | string[] | Record<string, string[]>;
+export interface ContractSpecI18nextExportOptions {
+    namespace?: ContractSpecI18nextNamespaceStrategy;
+    defaultLocale?: Locale;
+    lng?: Locale;
+    fallbackLng?: ContractSpecI18nextFallbackLng;
+    assumeIcuFormatter?: boolean;
+    includeFallbackLng?: boolean;
+}
+export interface ContractSpecI18nextInitOptions {
+    lng?: Locale;
+    fallbackLng?: ContractSpecI18nextFallbackLng;
+    partialBundledLanguages?: boolean;
+    keySeparator?: false | string;
+    defaultNS?: string;
+}
+export interface ContractSpecI18nextInstallOptions {
+    deep?: boolean;
+    overwrite?: boolean;
+}
+export interface I18nextResourceWriter {
+    addResourceBundle(lng: string, ns: string, resources: Record<string, string>, deep?: boolean, overwrite?: boolean): unknown;
+}
+export interface ContractSpecI18nextNamespace {
+    specKey: string;
+    version: string;
+    domain: string;
+    namespace: string;
+    locale: string;
+    direction: TextDirection;
+    fallbackChain: string[];
+    syntax: 'plain' | 'icu';
+    owners?: TranslationSpec['meta']['owners'];
+    tags?: TranslationSpec['meta']['tags'];
+    source?: string;
+    scope?: OverrideScope;
+}
+export interface ContractSpecI18nextMessageMetadata {
+    specKey: string;
+    version: string;
+    locale: string;
+    namespace: string;
+    messageKey: string;
+    description?: string;
+    context?: string;
+    placeholders?: PlaceholderDef[];
+    variants?: MessageVariant[];
+    maxLength?: number;
+    tags?: string[];
+    pluralRules?: PluralRuleSet[];
+    source?: string;
+    scope?: OverrideScope;
+}
+export type ContractSpecI18nextMessageMetadataMap = Record<string, Record<string, Record<string, ContractSpecI18nextMessageMetadata>>>;
+export type ContractSpecI18nextDiagnosticCode = 'i18next_fallback_projection_lossy' | 'i18next_icu_plugin_required' | 'i18next_invalid_locale' | 'i18next_metadata_omitted' | 'i18next_namespace_collision' | 'i18next_resource_collision';
+export interface ContractSpecI18nextDiagnostic {
+    code: ContractSpecI18nextDiagnosticCode;
+    level: 'info' | 'warning' | 'error';
+    message: string;
+    locale?: string;
+    namespace?: string;
+    specKey?: string;
+    messageKey?: string;
+}
+export interface ContractSpecI18nextManifest {
+    defaultLocale?: string;
+    locales: string[];
+    namespaces: ContractSpecI18nextNamespace[];
+    messages: ContractSpecI18nextMessageMetadataMap;
+    diagnostics: ContractSpecI18nextDiagnostic[];
+}
+export interface ContractSpecI18nextExport {
+    resources: I18nextResourceStore;
+    manifest: ContractSpecI18nextManifest;
+    ns: string[];
+    lng?: string;
+    defaultNS?: string;
+    fallbackLng?: ContractSpecI18nextFallbackLng;
+}
+export interface ContractSpecI18nextInitOptionsResult {
+    options: Record<string, unknown>;
+    diagnostics: ContractSpecI18nextDiagnostic[];
+}
+export interface ContractSpecI18nextSourceSpec {
+    spec: TranslationSpec;
+    source?: string;
+    scope?: OverrideScope;
+}

package/dist/adapters/i18next.d.ts

@@ -0,0 +1,8 @@
+import type { TranslationSpec } from '@lssm/lib.contracts-spec/translations';
+import type { TranslationRuntimeSnapshot } from '../snapshot.js';
+import type { ContractSpecI18nextExport, ContractSpecI18nextExportOptions, ContractSpecI18nextInitOptions, ContractSpecI18nextInitOptionsResult, ContractSpecI18nextInstallOptions, I18nextResourceWriter } from './i18next-types.js';
+export type * from './i18next-types.js';
+export declare function exportContractSpecToI18next(specs: readonly TranslationSpec[], options?: ContractSpecI18nextExportOptions): ContractSpecI18nextExport;
+export declare function exportTranslationSnapshotToI18next(snapshot: TranslationRuntimeSnapshot, options?: ContractSpecI18nextExportOptions): ContractSpecI18nextExport;
+export declare function createI18nextInitOptions(exported: ContractSpecI18nextExport, options?: ContractSpecI18nextInitOptions): ContractSpecI18nextInitOptionsResult;
+export declare function addContractSpecResourceBundles(instance: I18nextResourceWriter, exported: ContractSpecI18nextExport, options?: ContractSpecI18nextInstallOptions): void;

package/dist/adapters/i18next.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/browser/diagnostics.js

@@ -0,0 +1 @@
+class i{items=[];report(e){this.items.push(e)}list(){return[...this.items]}clear(){this.items.length=0}}export{i as TranslationDiagnosticsCollector};

package/dist/browser/direction.js

@@ -0,0 +1 @@
+var r=new Set(["ar","arc","dv","fa","ha","he","ks","ku","ps","ur","yi"]);function a(t){let e=n(t);return r.has(e)?"rtl":"ltr"}function n(t){try{return new Intl.Locale(t).language.toLowerCase()}catch{return t.split("-")[0]?.toLowerCase()??t.toLowerCase()}}export{n as getLanguageSubtag,a as getTextDirection};

package/dist/browser/fallback.js

@@ -0,0 +1 @@
+var g=new Set(["ar","arc","dv","fa","ha","he","ks","ku","ps","ur","yi"]);function L(e){let o=p(e);return g.has(o)?"rtl":"ltr"}function p(e){try{return new Intl.Locale(e).language.toLowerCase()}catch{return e.split("-")[0]?.toLowerCase()??e.toLowerCase()}}function r(e){let o=e.trim();if(!o)return{input:e,valid:!1,error:"Locale is empty"};try{let t=Intl.getCanonicalLocales(o)[0];return t?{input:e,locale:t,valid:!0}:{input:e,valid:!1,error:"Locale did not canonicalize"}}catch(t){return{input:e,valid:!1,error:t instanceof Error?t.message:"Invalid locale"}}}function s(e=[]){let o=[];for(let t of e){let a=r(t);if(a.locale&&!o.includes(a.locale))o.push(a.locale)}return o}function y(e){let o=r(e.defaultLocale).locale??e.defaultLocale,t=s(e.requestedLocales),a=s(e.supportedLocales),c=s(e.fallbackLocales),l=a.length?a:[o];for(let n of t){let u=i(n,o,c).find((d)=>l.includes(d));if(u)return f(u,t,l,o,c)}return f(o,t,l,o,c)}function i(e,o,t=[]){let a=[],c=(l)=>{if(!l)return;let n=r(l).locale??l;if(!a.includes(n))a.push(n)};c(e);for(let l of h(e))c(l);for(let l of t)c(l);return c(o),a}function h(e){let t=(r(e).locale??e).split("-"),a=[];while(t.length>1)t.pop(),a.push(t.join("-"));return a}function f(e,o,t,a,c){return{locale:e,requestedLocales:o,supportedLocales:t,fallbackChain:i(e,a,c),direction:L(e),defaultLocale:a}}function v(e,o){return i(e,o.defaultLocale,o.locales??[])}export{v as resolveFallbackChain};

package/dist/browser/formatters/intl-messageformat.js

@@ -0,0 +1 @@
+import{parse as f,TYPE as a}from"@formatjs/icu-messageformat-parser";import M from"intl-messageformat";function w(e={}){let o=e.cache??new Map,l=e.precompiled;return{compile({id:n,locale:s,message:i,ast:c}){let t=`${s}\x00${n}\x00${i}`,r=o.get(t);if(r)return r;let m=c??l?.({id:n,locale:s,message:i}),d=new M(m??i,s),u={format(g){let p=d.format(g);return Array.isArray(p)?p.join(""):String(p)}};return o.set(t,u),u},validate(n){try{let s=f(n);return F(s)}catch(s){return{valid:!1,error:s instanceof Error?s.message:"Invalid ICU message",arguments:[],plurals:[],selects:[],selectOrdinals:[]}}}}}function F(e){let o=new Set,l=new Set,n=new Set,s=new Set,i=(c)=>{for(let t of c){let r="value"in t?String(t.value):void 0;if(r&&v(t.type))o.add(r);if(r&&t.type===a.select)n.add(r);if(r&&t.type===a.plural)if(o.add(r),"pluralType"in t&&t.pluralType==="ordinal")s.add(r);else l.add(r);if("options"in t)for(let m of Object.values(t.options))i(m.value)}};return i(e),{valid:!0,arguments:[...o],plurals:[...l],selects:[...n],selectOrdinals:[...s]}}function v(e){return e===a.argument||e===a.number||e===a.date||e===a.time||e===a.select||e===a.plural||e===a.pound||e===a.tag}export{w as createIntlMessageFormatter};

package/dist/browser/i18next.js

@@ -0,0 +1 @@
+var v=new Set(["ar","arc","dv","fa","ha","he","ks","ku","ps","ur","yi"]);function x(e){let t=O(e);return v.has(t)?"rtl":"ltr"}function O(e){try{return new Intl.Locale(e).language.toLowerCase()}catch{return e.split("-")[0]?.toLowerCase()??e.toLowerCase()}}function g(e){let t=e.trim();if(!t)return{input:e,valid:!1,error:"Locale is empty"};try{let n=Intl.getCanonicalLocales(t)[0];return n?{input:e,locale:n,valid:!0}:{input:e,valid:!1,error:"Locale did not canonicalize"}}catch(n){return{input:e,valid:!1,error:n instanceof Error?n.message:"Invalid locale"}}}function S(e=[]){let t=[];for(let n of e){let a=g(n);if(a.locale&&!t.includes(a.locale))t.push(a.locale)}return t}function j(e){let t=g(e.defaultLocale).locale??e.defaultLocale,n=S(e.requestedLocales),a=S(e.supportedLocales),o=S(e.fallbackLocales),c=a.length?a:[t];for(let s of n){let r=d(s,t,o).find((l)=>c.includes(l));if(r)return I(r,n,c,t,o)}return I(t,n,c,t,o)}function d(e,t,n=[]){let a=[],o=(c)=>{if(!c)return;let s=g(c).locale??c;if(!a.includes(s))a.push(s)};o(e);for(let c of M(e))o(c);for(let c of n)o(c);return o(t),a}function M(e){let n=(g(e).locale??e).split("-"),a=[];while(n.length>1)n.pop(),a.push(n.join("-"));return a}function I(e,t,n,a,o){return{locale:e,requestedLocales:t,supportedLocales:n,fallbackChain:d(e,a,o),direction:x(e),defaultLocale:a}}function C(e,t="specKey"){if(typeof t==="function")return t(e);return t==="domain"?e.meta.domain:e.meta.key}function b(e,t){let n=e.fallbacks??(e.fallback?[e.fallback]:[]);return d(e.locale,t,n)}function m(e,t,n){let a=g(e);if(a.locale)return a.locale;return t.push({code:"i18next_invalid_locale",level:"warning",message:a.error??`Invalid locale ${e}`,locale:e,specKey:n}),e}function y(e,t,n){if(t.fallbackLng!==void 0)return t.fallbackLng;if(t.includeFallbackLng===!1)return;if(!e.length)return;let a=new Map;for(let c of e){let s=c.fallbackChain.filter((r)=>r!==c.locale),i=a.get(c.locale);if(i&&i.join("\x00")!==s.join("\x00")){n.push({code:"i18next_fallback_projection_lossy",level:"warning",message:`Multiple fallback chains exist for locale ${c.locale}; keeping authoritative chains in the ContractSpec manifest.`,locale:c.locale,namespace:c.namespace,specKey:c.specKey});return}a.set(c.locale,s)}let o=Object.fromEntries([...a.entries()].filter(([,c])=>c.length>0));if(!Object.keys(o).length)return;return o}function k(e){let t=new Map;for(let n of e){let a=n.fallbackChain.filter((c)=>c!==n.locale).join("\x00"),o=t.get(n.locale);if(o&&o!==a)return!0;t.set(n.locale,a)}return!1}function h(e){return[...new Set(e)]}function L(e,t){let n={},a={},o=[],c=[],s=new Map;for(let i of e){let{spec:r}=i,l=m(r.locale,c,r.meta.key),p=t.defaultLocale??r.defaultLocale??r.fallback??l,u=C(r,t.namespace),f=r.formatter?.syntax??"icu";R(s,u,r,c),E(n,a,l,u),o.push({specKey:r.meta.key,version:r.meta.version,domain:r.meta.domain,namespace:u,locale:l,direction:r.direction??x(l),fallbackChain:b(r,p),syntax:f,owners:r.meta.owners,tags:r.meta.tags,source:i.source,scope:i.scope}),w(f,t,l,u,r.meta.key,c),N(n,a,l,u,i,c)}return D(n,a,o,t,c)}function R(e,t,n,a){let o=e.get(t);if(o&&o!==n.meta.key)a.push({code:"i18next_namespace_collision",level:"warning",message:`Namespace ${t} is shared by ${o} and ${n.meta.key}.`,namespace:t,specKey:n.meta.key});else e.set(t,n.meta.key)}function w(e,t,n,a,o,c){if(e!=="icu"||t.assumeIcuFormatter)return;c.push({code:"i18next_icu_plugin_required",level:"warning",message:"ContractSpec ICU message exported to i18next; use an ICU-capable i18next format plugin for runtime formatting parity.",locale:n,namespace:a,specKey:o})}function E(e,t,n,a){e[n]??={},e[n][a]??={},t[n]??={},t[n][a]??={}}function N(e,t,n,a,o,c){let{spec:s}=o,i=e[n]?.[a],r=t[n]?.[a];if(!i||!r)return;for(let[l,p]of Object.entries(s.messages)){let u=i[l],f=r[l];if(u!==void 0&&(u!==p.value||f?.version!==s.meta.version||f?.source!==o.source||f?.scope!==o.scope)){c.push({code:"i18next_resource_collision",level:"error",message:`Message ${l} collides in ${n}/${a}.`,locale:n,namespace:a,specKey:s.meta.key,messageKey:l});continue}i[l]=p.value,r[l]={specKey:s.meta.key,version:s.meta.version,locale:n,namespace:a,messageKey:l,description:p.description,context:p.context,placeholders:p.placeholders,variants:p.variants,maxLength:p.maxLength,tags:p.tags,pluralRules:s.pluralRules,source:o.source,scope:o.scope}}}function D(e,t,n,a,o){let c=Object.keys(e).sort(),s=h(n.map((r)=>r.namespace)).sort(),i=y(n,a,o);return{resources:e,manifest:{defaultLocale:a.defaultLocale?m(a.defaultLocale,o):void 0,locales:c,namespaces:n,messages:t,diagnostics:o},ns:s,lng:a.lng?m(a.lng,o):void 0,defaultNS:s[0],fallbackLng:i}}function P(e,t={}){return L(e.map((n)=>({spec:n})),t)}function H(e,t={}){let n=e.sources?.length?e.sources.map(({scope:a,source:o,spec:c})=>({scope:a,source:o,spec:c})):e.specs.map((a)=>({spec:a}));return L(n,{defaultLocale:e.defaultLocale,lng:e.locale,fallbackLng:e.fallbackChain,...t})}function J(e,t={}){let n=[],a=t.fallbackLng??e.fallbackLng;if(!a&&k(e.manifest.namespaces))n.push({code:"i18next_fallback_projection_lossy",level:"warning",message:"ContractSpec has per-bundle fallback chains that cannot be represented as one i18next fallbackLng value."});let o={resources:e.resources,ns:e.ns,keySeparator:t.keySeparator??!1},c=t.defaultNS??e.defaultNS;if(c)o.defaultNS=c;let s=t.lng??e.lng??e.manifest.defaultLocale;if(s)o.lng=s;if(a)o.fallbackLng=a;if(t.partialBundledLanguages!==void 0)o.partialBundledLanguages=t.partialBundledLanguages;return{options:o,diagnostics:n}}function Q(e,t,n={}){let a=n.deep??!0,o=n.overwrite??!0;for(let[c,s]of Object.entries(t.resources))for(let[i,r]of Object.entries(s))e.addResourceBundle(c,i,r,a,o)}export{Q as addContractSpecResourceBundles,J as createI18nextInitOptions,P as exportContractSpecToI18next,H as exportTranslationSnapshotToI18next};

package/dist/browser/index.js

@@ -0,0 +1,28 @@
+class x{items=[];report(e){this.items.push(e)}list(){return[...this.items]}clear(){this.items.length=0}}var C=new Set(["ar","arc","dv","fa","ha","he","ks","ku","ps","ur","yi"]);function h(e){let t=b(e);return C.has(t)?"rtl":"ltr"}function b(e){try{return new Intl.Locale(e).language.toLowerCase()}catch{return e.split("-")[0]?.toLowerCase()??e.toLowerCase()}}function u(e){let t=e.trim();if(!t)return{input:e,valid:!1,error:"Locale is empty"};try{let a=Intl.getCanonicalLocales(t)[0];return a?{input:e,locale:a,valid:!0}:{input:e,valid:!1,error:"Locale did not canonicalize"}}catch(a){return{input:e,valid:!1,error:a instanceof Error?a.message:"Invalid locale"}}}function f(e=[]){let t=[];for(let a of e){let o=u(a);if(o.locale&&!t.includes(o.locale))t.push(o.locale)}return t}function X(e){let t=u(e.defaultLocale).locale??e.defaultLocale,a=f(e.requestedLocales),o=f(e.supportedLocales),r=f(e.fallbackLocales),n=o.length?o:[t];for(let l of a){let s=g(l,t,r).find((d)=>n.includes(d));if(s)return R(s,a,n,t,r)}return R(t,a,n,t,r)}function g(e,t,a=[]){let o=[],r=(n)=>{if(!n)return;let l=u(n).locale??n;if(!o.includes(l))o.push(l)};r(e);for(let n of k(e))r(n);for(let n of a)r(n);return r(t),o}function k(e){let a=(u(e).locale??e).split("-"),o=[];while(a.length>1)a.pop(),o.push(a.join("-"));return o}function R(e,t,a,o,r){return{locale:e,requestedLocales:t,supportedLocales:a,fallbackChain:g(e,o,r),direction:h(e),defaultLocale:o}}function te(e,t){return g(e,t.defaultLocale,t.locales??[])}import{parse as N,TYPE as p}from"@formatjs/icu-messageformat-parser";import O from"intl-messageformat";function ne(e={}){let t=e.cache??new Map,a=e.precompiled;return{compile({id:o,locale:r,message:n,ast:l}){let i=`${r}\x00${o}\x00${n}`,s=t.get(i);if(s)return s;let d=l??a?.({id:o,locale:r,message:n}),c=new O(d??n,r),m={format(P){let L=c.format(P);return Array.isArray(L)?L.join(""):String(L)}};return t.set(i,m),m},validate(o){try{let r=N(o);return M(r)}catch(r){return{valid:!1,error:r instanceof Error?r.message:"Invalid ICU message",arguments:[],plurals:[],selects:[],selectOrdinals:[]}}}}}function M(e){let t=new Set,a=new Set,o=new Set,r=new Set,n=(l)=>{for(let i of l){let s="value"in i?String(i.value):void 0;if(s&&D(i.type))t.add(s);if(s&&i.type===p.select)o.add(s);if(s&&i.type===p.plural)if(t.add(s),"pluralType"in i&&i.pluralType==="ordinal")r.add(s);else a.add(s);if("options"in i)for(let d of Object.values(i.options))n(d.value)}};return n(e),{valid:!0,arguments:[...t],plurals:[...a],selects:[...o],selectOrdinals:[...r]}}function D(e){return e===p.argument||e===p.number||e===p.date||e===p.time||e===p.select||e===p.plural||e===p.pound||e===p.tag}function ie(e){return{async load(t){return e.filter((a)=>E(a.meta.key,t)&&t.locales.includes(a.locale))}}}function E(e,t){let a=t.specKey!==void 0,o=t.specKeys!==void 0&&t.specKeys.length>0;if(!a&&!o)return!0;if(a&&e===t.specKey)return!0;if(o&&t.specKeys?.includes(e))return!0;return!1}function _(e,t){let a=new Set(e),o=[],r=new Set;for(let n of t){if(a.has(n)||r.has(n))continue;r.add(n),o.push(n)}return o}async function le(e,t){let a=_(t.loaded,t.required);if(a.length===0)return[];return e.load({specKeys:a,locales:t.locales})}function pe(e){return[...e].sort((t,a)=>(t.priority??I(t.scope))-(a.priority??I(a.scope)))}function I(e){switch(e){case"base":return 0;case"package":return 10;case"project":return 20;case"tenant":return 30;case"user":return 40;case"request":return 50}}import A from"intl-messageformat";var y="contractspec.icu.precompiled",T=1;function S(e,t){return`${e}\x00${t}`}function F(e,t){return new A(e,t).getAst()}function w(e){let t={};for(let{locale:a,message:o}of e){let r=S(a,o);if(t[r])continue;t[r]={locale:a,message:o,ast:F(o,a)}}return{kind:y,version:T,entries:t}}function me(e){let t=[];for(let a of e)for(let o of Object.values(a.messages))t.push({locale:a.locale,message:o.value});return w(t)}function fe(e){return JSON.stringify(e)}function ge(e){let t=JSON.parse(e),a=q(t);if(a.length>0)throw Error(a.join("; "));return t}function q(e){let t=[];if(!e||e.kind!==y)t.push("Precompiled ICU catalog kind is invalid.");if(e?.version!==T)t.push("Precompiled ICU catalog version is unsupported.");if(!e?.entries||typeof e.entries!=="object")t.push("Precompiled ICU catalog entries must be an object.");return t}function Le(e){return({locale:t,message:a})=>e.entries[S(t,a)]?.ast}var ye={id:"docs.tech.translation-runtime.icu-precompile",title:"Precompiled ICU AST fast-path",summary:"Build-time ICU AST precompilation with an additive runtime parse-skip fast-path.",kind:"reference",visibility:"public",route:"/docs/tech/translation-runtime/icu-precompile",tags:["i18n","icu","performance","translation-runtime"],body:`# Precompiled ICU AST fast-path
+
+Precompiles ICU message strings into the exact \`MessageFormatElement[]\` AST that
+\`intl-messageformat\` produces, so the runtime can skip the per-call parse.
+
+- \`precompileIcuMessage(message, locale)\` returns the AST via
+  \`IntlMessageFormat#getAst()\` — identical to the on-the-fly string path, so
+  formatted output is byte-identical (verified by golden tests across plural,
+  select, selectordinal, number, currency, date, and time for en/fr/es/ar-EG).
+- \`buildPrecompiledIcuCatalog\` / \`buildPrecompiledIcuCatalogFromSpecs\` produce a
+  serializable \`PrecompiledIcuCatalog\` (\`kind\` =
+  \`${y}\`, \`version\` = \`${T}\`) as a
+  build-time asset.
+- \`createPrecompiledIcuLookup(catalog)\` yields a lookup the formatter consumes.
+
+Wire the lookup via \`createIntlMessageFormatter({ precompiled })\`, or pass a
+per-call \`ast\` on \`compile()\`. When neither is present the formatter parses the
+message string exactly as before — the surface is **ADDITIVE**.
+
+Scope: this precompiles the ICU MessageFormat argument grammar
+(plural/select/selectordinal/number/date/time + number skeletons such as
+currency). List and relative-time rendering is performed by \`Intl.ListFormat\` /
+\`Intl.RelativeTimeFormat\` outside the message AST and has no per-call message
+parse to precompile. The \`createI18nFactory\` stack uses simple \`{key}\`
+interpolation (no ICU parse) and is therefore unaffected by this fast-path.
+
+Compatibility classification: **ADDITIVE**.
+`};var K=["app","workspace","team","user","request"],U={app:"appLocale",workspace:"workspaceLocale",team:"teamLocale",user:"userLocale",request:"requestLocale"};function Re(e={},t={}){let a=u(t.fallbackLocale??e.defaultLocale??e.appLocale??"en").locale??"en",o=u(e.defaultLocale??e.appLocale??a).locale??a,r={},n=[];for(let c of K){let m=H(e[U[c]]);if(!m)continue;r[c]=m,n.push({source:c,locale:m,metadata:e.sources?.[c]})}let l=f(e.requestedLocales??[]),i=f(t.additionalRequestedLocales??[]),s=[...n].reverse().map((c)=>c.locale),d=V([...l,...i,...s,o]);return{defaultLocale:o,requestedLocales:d,preferenceLocales:r,sources:[...l.map((c)=>({source:"requested",locale:c})),...n]}}function H(e){if(!e)return;return u(e).locale}function V(e){return[...new Set(e)]}var Se="contractspec.translation-runtime.hydration",ve=1;function j(e){return JSON.stringify(e)}function B(e){return JSON.parse(e)}function v(e){return{kind:"contractspec.translation-runtime.hydration",version:1,snapshot:J(e)}}function Pe(e){return JSON.stringify(e)}function xe(e){let t=JSON.parse(e),a=z(t);if(a.length>0)throw Error(a.map((o)=>o.message).join("; "));return v(t.snapshot)}function Ce(e){return{type:"translation-runtime-snapshot",payload:v(e)}}function z(e){let t=[];if(!e||e.kind!=="contractspec.translation-runtime.hydration")t.push({code:"invalid_snapshot",level:"error",message:"Translation hydration payload kind is invalid."});if(e?.version!==1)t.push({code:"invalid_snapshot",level:"error",message:"Translation hydration payload version is unsupported.",context:{version:e?.version}});return t.push(...Y(e?.snapshot)),t}function Y(e){let t=[];if(!e)return[{code:"invalid_snapshot",level:"error",message:"Translation runtime snapshot is missing."}];if(!e.locale)t.push({code:"invalid_snapshot",level:"error",message:"Translation runtime snapshot locale is missing."});if(!e.defaultLocale)t.push({code:"invalid_snapshot",level:"error",message:"Translation runtime snapshot defaultLocale is missing."});for(let[a,o]of[["fallbackChain",e.fallbackChain],["supportedLocales",e.supportedLocales],["specs",e.specs]])if(!Array.isArray(o))t.push({code:"invalid_snapshot",level:"error",message:`Translation runtime snapshot ${a} must be an array.`,context:{field:a}});return t}function J(e){return B(j(e))}export{y as PRECOMPILED_ICU_KIND,T as PRECOMPILED_ICU_VERSION,ye as PrecompiledIcuDocBlock,Se as TRANSLATION_RUNTIME_HYDRATION_KIND,ve as TRANSLATION_RUNTIME_HYDRATION_VERSION,x as TranslationDiagnosticsCollector,g as buildLocaleFallbackChain,w as buildPrecompiledIcuCatalog,me as buildPrecompiledIcuCatalogFromSpecs,u as canonicalizeLocale,f as canonicalizeLocales,_ as computeShardDelta,ne as createIntlMessageFormatter,Le as createPrecompiledIcuLookup,ie as createStaticBundleLoader,v as createTranslationHydrationPayload,Ce as createTranslationSnapshotStreamChunk,I as defaultOverridePriority,b as getLanguageSubtag,h as getTextDirection,le as loadShardDelta,X as negotiateLocale,ge as parsePrecompiledIcuCatalog,xe as parseTranslationHydrationPayload,B as parseTranslationSnapshot,F as precompileIcuMessage,te as resolveFallbackChain,Re as resolveTranslationPreferenceContext,fe as serializePrecompiledIcuCatalog,Pe as serializeTranslationHydrationPayload,j as serializeTranslationSnapshot,pe as sortOverrideLayers,q as validatePrecompiledIcuCatalog,z as validateTranslationHydrationPayload,Y as validateTranslationSnapshot};

package/dist/browser/loader.js

@@ -0,0 +1 @@
+function c(a){return{async load(e){return a.filter((n)=>s(n.meta.key,e)&&e.locales.includes(n.locale))}}}function s(a,e){let n=e.specKey!==void 0,t=e.specKeys!==void 0&&e.specKeys.length>0;if(!n&&!t)return!0;if(n&&a===e.specKey)return!0;if(t&&e.specKeys?.includes(a))return!0;return!1}function l(a,e){let n=new Set(a),t=[],o=new Set;for(let r of e){if(n.has(r)||o.has(r))continue;o.add(r),t.push(r)}return t}async function d(a,e){let n=l(e.loaded,e.required);if(n.length===0)return[];return a.load({specKeys:n,locales:e.locales})}export{l as computeShardDelta,c as createStaticBundleLoader,d as loadShardDelta};

package/dist/browser/locale.js

@@ -0,0 +1 @@
+var g=new Set(["ar","arc","dv","fa","ha","he","ks","ku","ps","ur","yi"]);function u(e){let t=p(e);return g.has(t)?"rtl":"ltr"}function p(e){try{return new Intl.Locale(e).language.toLowerCase()}catch{return e.split("-")[0]?.toLowerCase()??e.toLowerCase()}}function r(e){let t=e.trim();if(!t)return{input:e,valid:!1,error:"Locale is empty"};try{let o=Intl.getCanonicalLocales(t)[0];return o?{input:e,locale:o,valid:!0}:{input:e,valid:!1,error:"Locale did not canonicalize"}}catch(o){return{input:e,valid:!1,error:o instanceof Error?o.message:"Invalid locale"}}}function i(e=[]){let t=[];for(let o of e){let a=r(o);if(a.locale&&!t.includes(a.locale))t.push(a.locale)}return t}function m(e){let t=r(e.defaultLocale).locale??e.defaultLocale,o=i(e.requestedLocales),a=i(e.supportedLocales),c=i(e.fallbackLocales),n=a.length?a:[t];for(let l of o){let s=f(l,t,c).find((d)=>n.includes(d));if(s)return L(s,o,n,t,c)}return L(t,o,n,t,c)}function f(e,t,o=[]){let a=[],c=(n)=>{if(!n)return;let l=r(n).locale??n;if(!a.includes(l))a.push(l)};c(e);for(let n of h(e))c(n);for(let n of o)c(n);return c(t),a}function h(e){let o=(r(e).locale??e).split("-"),a=[];while(o.length>1)o.pop(),a.push(o.join("-"));return a}function L(e,t,o,a,c){return{locale:e,requestedLocales:t,supportedLocales:o,fallbackChain:f(e,a,c),direction:u(e),defaultLocale:a}}export{f as buildLocaleFallbackChain,r as canonicalizeLocale,i as canonicalizeLocales,m as negotiateLocale};

package/dist/browser/overrides.js

@@ -0,0 +1 @@
+function a(e){return[...e].sort((r,t)=>(r.priority??s(r.scope))-(t.priority??s(t.scope)))}function s(e){switch(e){case"base":return 0;case"package":return 10;case"project":return 20;case"tenant":return 30;case"user":return 40;case"request":return 50}}export{s as defaultOverridePriority,a as sortOverrideLayers};

package/dist/browser/precompile.js

@@ -0,0 +1,28 @@
+import n from"intl-messageformat";var s="contractspec.icu.precompiled",a=1;function c(t,e){return`${t}\x00${e}`}function l(t,e){return new n(t,e).getAst()}function p(t){let e={};for(let{locale:r,message:o}of t){let i=c(r,o);if(e[i])continue;e[i]={locale:r,message:o,ast:l(o,r)}}return{kind:s,version:a,entries:e}}function d(t){let e=[];for(let r of t)for(let o of Object.values(r.messages))e.push({locale:r.locale,message:o.value});return p(e)}function g(t){return JSON.stringify(t)}function I(t){let e=JSON.parse(t),r=m(e);if(r.length>0)throw Error(r.join("; "));return e}function m(t){let e=[];if(!t||t.kind!==s)e.push("Precompiled ICU catalog kind is invalid.");if(t?.version!==a)e.push("Precompiled ICU catalog version is unsupported.");if(!t?.entries||typeof t.entries!=="object")e.push("Precompiled ICU catalog entries must be an object.");return e}function f(t){return({locale:e,message:r})=>t.entries[c(e,r)]?.ast}var P={id:"docs.tech.translation-runtime.icu-precompile",title:"Precompiled ICU AST fast-path",summary:"Build-time ICU AST precompilation with an additive runtime parse-skip fast-path.",kind:"reference",visibility:"public",route:"/docs/tech/translation-runtime/icu-precompile",tags:["i18n","icu","performance","translation-runtime"],body:`# Precompiled ICU AST fast-path
+
+Precompiles ICU message strings into the exact \`MessageFormatElement[]\` AST that
+\`intl-messageformat\` produces, so the runtime can skip the per-call parse.
+
+- \`precompileIcuMessage(message, locale)\` returns the AST via
+  \`IntlMessageFormat#getAst()\` — identical to the on-the-fly string path, so
+  formatted output is byte-identical (verified by golden tests across plural,
+  select, selectordinal, number, currency, date, and time for en/fr/es/ar-EG).
+- \`buildPrecompiledIcuCatalog\` / \`buildPrecompiledIcuCatalogFromSpecs\` produce a
+  serializable \`PrecompiledIcuCatalog\` (\`kind\` =
+  \`${s}\`, \`version\` = \`${a}\`) as a
+  build-time asset.
+- \`createPrecompiledIcuLookup(catalog)\` yields a lookup the formatter consumes.
+
+Wire the lookup via \`createIntlMessageFormatter({ precompiled })\`, or pass a
+per-call \`ast\` on \`compile()\`. When neither is present the formatter parses the
+message string exactly as before — the surface is **ADDITIVE**.
+
+Scope: this precompiles the ICU MessageFormat argument grammar
+(plural/select/selectordinal/number/date/time + number skeletons such as
+currency). List and relative-time rendering is performed by \`Intl.ListFormat\` /
+\`Intl.RelativeTimeFormat\` outside the message AST and has no per-call message
+parse to precompile. The \`createI18nFactory\` stack uses simple \`{key}\`
+interpolation (no ICU parse) and is therefore unaffected by this fast-path.
+
+Compatibility classification: **ADDITIVE**.
+`};export{s as PRECOMPILED_ICU_KIND,a as PRECOMPILED_ICU_VERSION,P as PrecompiledIcuDocBlock,p as buildPrecompiledIcuCatalog,d as buildPrecompiledIcuCatalogFromSpecs,f as createPrecompiledIcuLookup,I as parsePrecompiledIcuCatalog,l as precompileIcuMessage,g as serializePrecompiledIcuCatalog,m as validatePrecompiledIcuCatalog};

package/dist/browser/preferences.js

@@ -0,0 +1 @@
+var m=new Set(["ar","arc","dv","fa","ha","he","ks","ku","ps","ur","yi"]);function p(e){let o=R(e);return m.has(o)?"rtl":"ltr"}function R(e){try{return new Intl.Locale(e).language.toLowerCase()}catch{return e.split("-")[0]?.toLowerCase()??e.toLowerCase()}}function l(e){let o=e.trim();if(!o)return{input:e,valid:!1,error:"Locale is empty"};try{let a=Intl.getCanonicalLocales(o)[0];return a?{input:e,locale:a,valid:!0}:{input:e,valid:!1,error:"Locale did not canonicalize"}}catch(a){return{input:e,valid:!1,error:a instanceof Error?a.message:"Invalid locale"}}}function i(e=[]){let o=[];for(let a of e){let n=l(a);if(n.locale&&!o.includes(n.locale))o.push(n.locale)}return o}function C(e){let o=l(e.defaultLocale).locale??e.defaultLocale,a=i(e.requestedLocales),n=i(e.supportedLocales),t=i(e.fallbackLocales),r=n.length?n:[o];for(let s of a){let u=T(s,o,t).find((f)=>r.includes(f));if(u)return g(u,a,r,o,t)}return g(o,a,r,o,t)}function T(e,o,a=[]){let n=[],t=(r)=>{if(!r)return;let s=l(r).locale??r;if(!n.includes(s))n.push(s)};t(e);for(let r of P(e))t(r);for(let r of a)t(r);return t(o),n}function P(e){let a=(l(e).locale??e).split("-"),n=[];while(a.length>1)a.pop(),n.push(a.join("-"));return n}function g(e,o,a,n,t){return{locale:e,requestedLocales:o,supportedLocales:a,fallbackChain:T(e,n,t),direction:p(e),defaultLocale:n}}var h=["app","workspace","team","user","request"],x={app:"appLocale",workspace:"workspaceLocale",team:"teamLocale",user:"userLocale",request:"requestLocale"};function E(e={},o={}){let a=l(o.fallbackLocale??e.defaultLocale??e.appLocale??"en").locale??"en",n=l(e.defaultLocale??e.appLocale??a).locale??a,t={},r=[];for(let c of h){let L=q(e[x[c]]);if(!L)continue;t[c]=L,r.push({source:c,locale:L,metadata:e.sources?.[c]})}let s=i(e.requestedLocales??[]),d=i(o.additionalRequestedLocales??[]),u=[...r].reverse().map((c)=>c.locale),f=y([...s,...d,...u,n]);return{defaultLocale:n,requestedLocales:f,preferenceLocales:t,sources:[...s.map((c)=>({source:"requested",locale:c})),...r]}}function q(e){if(!e)return;return l(e).locale}function y(e){return[...new Set(e)]}export{E as resolveTranslationPreferenceContext};

package/dist/browser/snapshot.js

@@ -0,0 +1 @@
+var c="contractspec.translation-runtime.hydration",T=1;function s(n){return JSON.stringify(n)}function e(n){return JSON.parse(n)}function i(n){return{kind:"contractspec.translation-runtime.hydration",version:1,snapshot:p(n)}}function u(n){return JSON.stringify(n)}function d(n){let a=JSON.parse(n),t=r(a);if(t.length>0)throw Error(t.map((o)=>o.message).join("; "));return i(a.snapshot)}function m(n){return{type:"translation-runtime-snapshot",payload:i(n)}}function r(n){let a=[];if(!n||n.kind!=="contractspec.translation-runtime.hydration")a.push({code:"invalid_snapshot",level:"error",message:"Translation hydration payload kind is invalid."});if(n?.version!==1)a.push({code:"invalid_snapshot",level:"error",message:"Translation hydration payload version is unsupported.",context:{version:n?.version}});return a.push(...l(n?.snapshot)),a}function l(n){let a=[];if(!n)return[{code:"invalid_snapshot",level:"error",message:"Translation runtime snapshot is missing."}];if(!n.locale)a.push({code:"invalid_snapshot",level:"error",message:"Translation runtime snapshot locale is missing."});if(!n.defaultLocale)a.push({code:"invalid_snapshot",level:"error",message:"Translation runtime snapshot defaultLocale is missing."});for(let[t,o]of[["fallbackChain",n.fallbackChain],["supportedLocales",n.supportedLocales],["specs",n.specs]])if(!Array.isArray(o))a.push({code:"invalid_snapshot",level:"error",message:`Translation runtime snapshot ${t} must be an array.`,context:{field:t}});return a}function p(n){return e(s(n))}export{c as TRANSLATION_RUNTIME_HYDRATION_KIND,T as TRANSLATION_RUNTIME_HYDRATION_VERSION,i as createTranslationHydrationPayload,m as createTranslationSnapshotStreamChunk,d as parseTranslationHydrationPayload,e as parseTranslationSnapshot,u as serializeTranslationHydrationPayload,s as serializeTranslationSnapshot,r as validateTranslationHydrationPayload,l as validateTranslationSnapshot};

package/dist/diagnostics.d.ts

@@ -0,0 +1,21 @@
+import type { Locale, MessageKey } from '@lssm/lib.contracts-spec/translations';
+export type TranslationDiagnosticLevel = 'info' | 'warning' | 'error';
+export type TranslationDiagnosticCode = 'fallback_used' | 'formatter_error' | 'invalid_locale' | 'invalid_snapshot' | 'loader_error' | 'missing_message' | 'missing_spec' | 'override_used';
+export interface TranslationDiagnostic {
+    code: TranslationDiagnosticCode;
+    level: TranslationDiagnosticLevel;
+    message: string;
+    specKey?: string;
+    messageKey?: MessageKey;
+    locale?: Locale;
+    fallbackLocale?: Locale;
+    source?: string;
+    context?: Record<string, unknown>;
+}
+export type TranslationDiagnosticReporter = (diagnostic: TranslationDiagnostic) => void;
+export declare class TranslationDiagnosticsCollector {
+    private readonly items;
+    report(diagnostic: TranslationDiagnostic): void;
+    list(): TranslationDiagnostic[];
+    clear(): void;
+}

package/dist/diagnostics.js

@@ -0,0 +1,2 @@
+// @bun
+class i{items=[];report(e){this.items.push(e)}list(){return[...this.items]}clear(){this.items.length=0}}export{i as TranslationDiagnosticsCollector};

package/dist/direction.d.ts

@@ -0,0 +1,3 @@
+export type TextDirection = 'ltr' | 'rtl';
+export declare function getTextDirection(locale: string): TextDirection;
+export declare function getLanguageSubtag(locale: string): string;

package/dist/direction.js

@@ -0,0 +1,2 @@
+// @bun
+var r=new Set(["ar","arc","dv","fa","ha","he","ks","ku","ps","ur","yi"]);function a(t){let e=n(t);return r.has(e)?"rtl":"ltr"}function n(t){try{return new Intl.Locale(t).language.toLowerCase()}catch{return t.split("-")[0]?.toLowerCase()??t.toLowerCase()}}export{n as getLanguageSubtag,a as getTextDirection};

package/dist/fallback.d.ts

@@ -0,0 +1,6 @@
+import type { Locale } from '@lssm/lib.contracts-spec/translations';
+export interface FallbackPolicy {
+    defaultLocale: Locale;
+    locales?: readonly Locale[];
+}
+export declare function resolveFallbackChain(locale: Locale, policy: FallbackPolicy): Locale[];

package/dist/fallback.js

@@ -0,0 +1,2 @@
+// @bun
+var g=new Set(["ar","arc","dv","fa","ha","he","ks","ku","ps","ur","yi"]);function L(e){let o=p(e);return g.has(o)?"rtl":"ltr"}function p(e){try{return new Intl.Locale(e).language.toLowerCase()}catch{return e.split("-")[0]?.toLowerCase()??e.toLowerCase()}}function r(e){let o=e.trim();if(!o)return{input:e,valid:!1,error:"Locale is empty"};try{let t=Intl.getCanonicalLocales(o)[0];return t?{input:e,locale:t,valid:!0}:{input:e,valid:!1,error:"Locale did not canonicalize"}}catch(t){return{input:e,valid:!1,error:t instanceof Error?t.message:"Invalid locale"}}}function s(e=[]){let o=[];for(let t of e){let a=r(t);if(a.locale&&!o.includes(a.locale))o.push(a.locale)}return o}function y(e){let o=r(e.defaultLocale).locale??e.defaultLocale,t=s(e.requestedLocales),a=s(e.supportedLocales),c=s(e.fallbackLocales),l=a.length?a:[o];for(let n of t){let u=i(n,o,c).find((d)=>l.includes(d));if(u)return f(u,t,l,o,c)}return f(o,t,l,o,c)}function i(e,o,t=[]){let a=[],c=(l)=>{if(!l)return;let n=r(l).locale??l;if(!a.includes(n))a.push(n)};c(e);for(let l of h(e))c(l);for(let l of t)c(l);return c(o),a}function h(e){let t=(r(e).locale??e).split("-"),a=[];while(t.length>1)t.pop(),a.push(t.join("-"));return a}function f(e,o,t,a,c){return{locale:e,requestedLocales:o,supportedLocales:t,fallbackChain:i(e,a,c),direction:L(e),defaultLocale:a}}function v(e,o){return i(e,o.defaultLocale,o.locales??[])}export{v as resolveFallbackChain};

package/dist/formatter.d.ts

@@ -0,0 +1,32 @@
+import type { MessageFormatElement } from '@formatjs/icu-messageformat-parser';
+import type { Locale } from '@lssm/lib.contracts-spec/translations';
+export type RuntimePrimitive = string | number | boolean | Date | null | undefined;
+export type RuntimeValue = RuntimePrimitive | ((chunks: string[]) => string);
+export type RuntimeValues = Record<string, RuntimeValue>;
+export interface CompiledMessage {
+    format(values?: RuntimeValues): string;
+}
+export interface MessageFormatValidationResult {
+    valid: boolean;
+    error?: string;
+    arguments: string[];
+    plurals: string[];
+    selects: string[];
+    selectOrdinals: string[];
+}
+export interface CompileMessageOptions {
+    id: string;
+    locale: Locale;
+    message: string;
+    /**
+     * Optional precompiled AST for `message` at `locale`.
+     *
+     * Additive fast-path: when provided, formatters may construct from the AST
+     * directly and skip parsing `message`. When omitted, behavior is unchanged.
+     */
+    ast?: MessageFormatElement[];
+}
+export interface MessageFormatter {
+    compile(options: CompileMessageOptions): CompiledMessage;
+    validate(message: string): MessageFormatValidationResult;
+}

package/dist/formatter.js

@@ -0,0 +1 @@
+// @bun

package/dist/formatters/intl-messageformat.d.ts

@@ -0,0 +1,12 @@
+import type { CompiledMessage, MessageFormatter } from '../formatter.js';
+import type { PrecompiledIcuLookup } from '../precompile.js';
+export interface IntlMessageFormatterOptions {
+    cache?: Map<string, CompiledMessage>;
+    /**
+     * Optional precompiled-AST lookup. When it resolves an AST for a message,
+     * the formatter constructs from the AST and skips parsing the string.
+     * Additive: when absent or returning `undefined`, behavior is unchanged.
+     */
+    precompiled?: PrecompiledIcuLookup;
+}
+export declare function createIntlMessageFormatter(options?: IntlMessageFormatterOptions): MessageFormatter;

package/dist/formatters/intl-messageformat.js

@@ -0,0 +1,2 @@
+// @bun
+import{parse as f,TYPE as a}from"@formatjs/icu-messageformat-parser";import M from"intl-messageformat";function w(e={}){let o=e.cache??new Map,l=e.precompiled;return{compile({id:n,locale:s,message:i,ast:c}){let t=`${s}\x00${n}\x00${i}`,r=o.get(t);if(r)return r;let m=c??l?.({id:n,locale:s,message:i}),d=new M(m??i,s),u={format(g){let p=d.format(g);return Array.isArray(p)?p.join(""):String(p)}};return o.set(t,u),u},validate(n){try{let s=f(n);return F(s)}catch(s){return{valid:!1,error:s instanceof Error?s.message:"Invalid ICU message",arguments:[],plurals:[],selects:[],selectOrdinals:[]}}}}}function F(e){let o=new Set,l=new Set,n=new Set,s=new Set,i=(c)=>{for(let t of c){let r="value"in t?String(t.value):void 0;if(r&&v(t.type))o.add(r);if(r&&t.type===a.select)n.add(r);if(r&&t.type===a.plural)if(o.add(r),"pluralType"in t&&t.pluralType==="ordinal")s.add(r);else l.add(r);if("options"in t)for(let m of Object.values(t.options))i(m.value)}};return i(e),{valid:!0,arguments:[...o],plurals:[...l],selects:[...n],selectOrdinals:[...s]}}function v(e){return e===a.argument||e===a.number||e===a.date||e===a.time||e===a.select||e===a.plural||e===a.pound||e===a.tag}export{w as createIntlMessageFormatter};

package/dist/i18next.d.ts

@@ -0,0 +1 @@
+export * from './adapters/i18next.js';

package/dist/i18next.js

@@ -0,0 +1,2 @@
+// @bun
+var v=new Set(["ar","arc","dv","fa","ha","he","ks","ku","ps","ur","yi"]);function x(e){let t=O(e);return v.has(t)?"rtl":"ltr"}function O(e){try{return new Intl.Locale(e).language.toLowerCase()}catch{return e.split("-")[0]?.toLowerCase()??e.toLowerCase()}}function g(e){let t=e.trim();if(!t)return{input:e,valid:!1,error:"Locale is empty"};try{let n=Intl.getCanonicalLocales(t)[0];return n?{input:e,locale:n,valid:!0}:{input:e,valid:!1,error:"Locale did not canonicalize"}}catch(n){return{input:e,valid:!1,error:n instanceof Error?n.message:"Invalid locale"}}}function S(e=[]){let t=[];for(let n of e){let a=g(n);if(a.locale&&!t.includes(a.locale))t.push(a.locale)}return t}function j(e){let t=g(e.defaultLocale).locale??e.defaultLocale,n=S(e.requestedLocales),a=S(e.supportedLocales),o=S(e.fallbackLocales),c=a.length?a:[t];for(let s of n){let r=d(s,t,o).find((l)=>c.includes(l));if(r)return I(r,n,c,t,o)}return I(t,n,c,t,o)}function d(e,t,n=[]){let a=[],o=(c)=>{if(!c)return;let s=g(c).locale??c;if(!a.includes(s))a.push(s)};o(e);for(let c of M(e))o(c);for(let c of n)o(c);return o(t),a}function M(e){let n=(g(e).locale??e).split("-"),a=[];while(n.length>1)n.pop(),a.push(n.join("-"));return a}function I(e,t,n,a,o){return{locale:e,requestedLocales:t,supportedLocales:n,fallbackChain:d(e,a,o),direction:x(e),defaultLocale:a}}function C(e,t="specKey"){if(typeof t==="function")return t(e);return t==="domain"?e.meta.domain:e.meta.key}function b(e,t){let n=e.fallbacks??(e.fallback?[e.fallback]:[]);return d(e.locale,t,n)}function m(e,t,n){let a=g(e);if(a.locale)return a.locale;return t.push({code:"i18next_invalid_locale",level:"warning",message:a.error??`Invalid locale ${e}`,locale:e,specKey:n}),e}function y(e,t,n){if(t.fallbackLng!==void 0)return t.fallbackLng;if(t.includeFallbackLng===!1)return;if(!e.length)return;let a=new Map;for(let c of e){let s=c.fallbackChain.filter((r)=>r!==c.locale),i=a.get(c.locale);if(i&&i.join("\x00")!==s.join("\x00")){n.push({code:"i18next_fallback_projection_lossy",level:"warning",message:`Multiple fallback chains exist for locale ${c.locale}; keeping authoritative chains in the ContractSpec manifest.`,locale:c.locale,namespace:c.namespace,specKey:c.specKey});return}a.set(c.locale,s)}let o=Object.fromEntries([...a.entries()].filter(([,c])=>c.length>0));if(!Object.keys(o).length)return;return o}function k(e){let t=new Map;for(let n of e){let a=n.fallbackChain.filter((c)=>c!==n.locale).join("\x00"),o=t.get(n.locale);if(o&&o!==a)return!0;t.set(n.locale,a)}return!1}function h(e){return[...new Set(e)]}function L(e,t){let n={},a={},o=[],c=[],s=new Map;for(let i of e){let{spec:r}=i,l=m(r.locale,c,r.meta.key),p=t.defaultLocale??r.defaultLocale??r.fallback??l,u=C(r,t.namespace),f=r.formatter?.syntax??"icu";R(s,u,r,c),E(n,a,l,u),o.push({specKey:r.meta.key,version:r.meta.version,domain:r.meta.domain,namespace:u,locale:l,direction:r.direction??x(l),fallbackChain:b(r,p),syntax:f,owners:r.meta.owners,tags:r.meta.tags,source:i.source,scope:i.scope}),w(f,t,l,u,r.meta.key,c),N(n,a,l,u,i,c)}return D(n,a,o,t,c)}function R(e,t,n,a){let o=e.get(t);if(o&&o!==n.meta.key)a.push({code:"i18next_namespace_collision",level:"warning",message:`Namespace ${t} is shared by ${o} and ${n.meta.key}.`,namespace:t,specKey:n.meta.key});else e.set(t,n.meta.key)}function w(e,t,n,a,o,c){if(e!=="icu"||t.assumeIcuFormatter)return;c.push({code:"i18next_icu_plugin_required",level:"warning",message:"ContractSpec ICU message exported to i18next; use an ICU-capable i18next format plugin for runtime formatting parity.",locale:n,namespace:a,specKey:o})}function E(e,t,n,a){e[n]??={},e[n][a]??={},t[n]??={},t[n][a]??={}}function N(e,t,n,a,o,c){let{spec:s}=o,i=e[n]?.[a],r=t[n]?.[a];if(!i||!r)return;for(let[l,p]of Object.entries(s.messages)){let u=i[l],f=r[l];if(u!==void 0&&(u!==p.value||f?.version!==s.meta.version||f?.source!==o.source||f?.scope!==o.scope)){c.push({code:"i18next_resource_collision",level:"error",message:`Message ${l} collides in ${n}/${a}.`,locale:n,namespace:a,specKey:s.meta.key,messageKey:l});continue}i[l]=p.value,r[l]={specKey:s.meta.key,version:s.meta.version,locale:n,namespace:a,messageKey:l,description:p.description,context:p.context,placeholders:p.placeholders,variants:p.variants,maxLength:p.maxLength,tags:p.tags,pluralRules:s.pluralRules,source:o.source,scope:o.scope}}}function D(e,t,n,a,o){let c=Object.keys(e).sort(),s=h(n.map((r)=>r.namespace)).sort(),i=y(n,a,o);return{resources:e,manifest:{defaultLocale:a.defaultLocale?m(a.defaultLocale,o):void 0,locales:c,namespaces:n,messages:t,diagnostics:o},ns:s,lng:a.lng?m(a.lng,o):void 0,defaultNS:s[0],fallbackLng:i}}function P(e,t={}){return L(e.map((n)=>({spec:n})),t)}function H(e,t={}){let n=e.sources?.length?e.sources.map(({scope:a,source:o,spec:c})=>({scope:a,source:o,spec:c})):e.specs.map((a)=>({spec:a}));return L(n,{defaultLocale:e.defaultLocale,lng:e.locale,fallbackLng:e.fallbackChain,...t})}function J(e,t={}){let n=[],a=t.fallbackLng??e.fallbackLng;if(!a&&k(e.manifest.namespaces))n.push({code:"i18next_fallback_projection_lossy",level:"warning",message:"ContractSpec has per-bundle fallback chains that cannot be represented as one i18next fallbackLng value."});let o={resources:e.resources,ns:e.ns,keySeparator:t.keySeparator??!1},c=t.defaultNS??e.defaultNS;if(c)o.defaultNS=c;let s=t.lng??e.lng??e.manifest.defaultLocale;if(s)o.lng=s;if(a)o.fallbackLng=a;if(t.partialBundledLanguages!==void 0)o.partialBundledLanguages=t.partialBundledLanguages;return{options:o,diagnostics:n}}function Q(e,t,n={}){let a=n.deep??!0,o=n.overwrite??!0;for(let[c,s]of Object.entries(t.resources))for(let[i,r]of Object.entries(s))e.addResourceBundle(c,i,r,a,o)}export{Q as addContractSpecResourceBundles,J as createI18nextInitOptions,P as exportContractSpecToI18next,H as exportTranslationSnapshotToI18next};

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export * from './diagnostics.js';
+export * from './direction.js';
+export * from './fallback.js';
+export * from './formatter.js';
+export * from './formatters/intl-messageformat.js';
+export * from './loader.js';
+export * from './locale.js';
+export * from './overrides.js';
+export * from './precompile.js';
+export * from './preferences.js';
+export * from './snapshot.js';