@c9up/rosetta 0.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 C9up
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,33 @@
+# @c9up/rosetta
+
+> Dedicated i18n module for the Ream ecosystem — translations, pluralization, locale resolution.
+
+Part of **[Ream](https://github.com/C9up/ream)** — a Rust-powered, AdonisJS-compatible Node.js framework. Independent, publishable package.
+
+## Installation
+
+```bash
+pnpm add @c9up/rosetta
+ream configure @c9up/rosetta
+```
+
+## Usage
+
+Register the provider in your app, then configure it under `config/rosetta.ts`:
+
+```ts
+// reamrc.ts
+providers: [
+  () => import('@c9up/rosetta/provider'),
+]
+```
+
+## Entry points
+
+- `@c9up/rosetta` — main API
+- `@c9up/rosetta/provider` — Ream IoC provider
+- `@c9up/rosetta/services/main` — container service accessor
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@c9up/rosetta",
+  "version": "0.1.3",
+  "description": "Rosetta — dedicated i18n module for the Ream ecosystem",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "LICENSE",
+    "README.md",
+    "dist",
+    "index.*.node",
+    "scripts",
+    "src",
+    "wasm"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./provider": {
+      "types": "./dist/RosettaProvider.d.ts",
+      "import": "./dist/RosettaProvider.js"
+    },
+    "./services/main": {
+      "types": "./dist/services/main.d.ts",
+      "import": "./dist/services/main.js"
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.15",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.2"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/C9up/rosetta.git"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "build:rust": "cargo build --release",
+    "build:napi": "cargo build --release && node scripts/copy-napi.mjs",
+    "test": "vitest run",
+    "test:rust": "cargo test",
+    "test:napi": "node scripts/verify-napi.mjs",
+    "lint": "biome check src/ tests/",
+    "build:wasm": "wasm-pack build --target web crates/rosetta-engine-wasm --out-dir ../../wasm",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/scripts/copy-napi.mjs

@@ -0,0 +1,48 @@
+import { copyFileSync, existsSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { arch, env, platform } from 'node:process'
+import { fileURLToPath } from 'node:url'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const root = join(here, '..')
+const CRATE = 'rosetta_engine_napi'
+const TAG = '[rosetta:napi]'
+
+const tripleMap = {
+  'x86_64-unknown-linux-gnu': { suffix: 'linux-x64-gnu', os: 'linux' },
+  'aarch64-unknown-linux-gnu': { suffix: 'linux-arm64-gnu', os: 'linux' },
+  'x86_64-apple-darwin': { suffix: 'darwin-x64', os: 'darwin' },
+  'aarch64-apple-darwin': { suffix: 'darwin-arm64', os: 'darwin' },
+  'x86_64-pc-windows-msvc': { suffix: 'win32-x64-msvc', os: 'win32' },
+}
+const hostSuffixMap = {
+  'linux-x64': 'linux-x64-gnu', 'linux-arm64': 'linux-arm64-gnu',
+  'darwin-x64': 'darwin-x64', 'darwin-arm64': 'darwin-arm64', 'win32-x64': 'win32-x64-msvc',
+}
+
+const triple = env.CARGO_BUILD_TARGET ?? ''
+let suffix, os, releaseDir
+if (triple) {
+  const entry = tripleMap[triple]
+  if (!entry) throw new Error(`${TAG} unsupported CARGO_BUILD_TARGET: ${triple}`)
+  suffix = entry.suffix; os = entry.os
+  releaseDir = join(root, 'target', triple, 'release')
+} else {
+  suffix = hostSuffixMap[`${platform}-${arch}`]; os = platform
+  releaseDir = join(root, 'target', 'release')
+  if (!suffix) throw new Error(`${TAG} unsupported platform/arch: ${platform}-${arch}`)
+}
+
+const candidates =
+  os === 'win32'
+    ? [join(releaseDir, `${CRATE}.dll`), join(releaseDir, `lib${CRATE}.dll`)]
+    : os === 'darwin'
+      ? [join(releaseDir, `lib${CRATE}.dylib`)]
+      : [join(releaseDir, `lib${CRATE}.so`)]
+
+const source = candidates.find((candidate) => existsSync(candidate))
+if (!source) throw new Error(`${TAG} native library not found. Looked for:\n${candidates.map((p) => `- ${p}`).join('\n')}`)
+
+const target = join(root, `index.${suffix}.node`)
+copyFileSync(source, target)
+console.log(`${TAG} copied ${source} -> ${target}`)

package/scripts/verify-napi.mjs

@@ -0,0 +1,49 @@
+import { existsSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { dirname, join } from 'node:path'
+import { arch, platform } from 'node:process'
+import { fileURLToPath } from 'node:url'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const root = join(here, '..')
+
+const suffixMap = {
+  'linux-x64': 'linux-x64-gnu',
+  'linux-arm64': 'linux-arm64-gnu',
+  'darwin-x64': 'darwin-x64',
+  'darwin-arm64': 'darwin-arm64',
+  'win32-x64': 'win32-x64-msvc',
+}
+
+const suffix = suffixMap[`${platform}-${arch}`]
+if (!suffix) {
+  throw new Error(`[rosetta:napi] unsupported platform/arch: ${platform}-${arch}`)
+}
+
+const binary = join(root, `index.${suffix}.node`)
+if (!existsSync(binary)) {
+  throw new Error(`[rosetta:napi] binary missing: ${binary}`)
+}
+
+const require2 = createRequire(import.meta.url)
+const binding = require2(binary)
+
+if (typeof binding.translate !== 'function' || typeof binding.has !== 'function') {
+  throw new Error('[rosetta:napi] invalid exports: expected translate() and has() functions')
+}
+
+const catalogs = JSON.stringify({ en: { hello: 'Hello {name}' } })
+const chain = JSON.stringify(['en'])
+const params = JSON.stringify({ name: 'Kaen' })
+
+const translated = binding.translate(catalogs, 'hello', params, chain, undefined)
+if (translated !== 'Hello Kaen') {
+  throw new Error(`[rosetta:napi] translate smoke test failed: got "${translated}"`)
+}
+
+const hasKey = binding.has(catalogs, 'hello', chain)
+if (hasKey !== true) {
+  throw new Error('[rosetta:napi] has smoke test failed')
+}
+
+console.log('[rosetta:napi] smoke test passed')

package/src/Rosetta.ts

@@ -0,0 +1,569 @@
+import { createNativeEngine, type NativeRosettaEngine } from "./native.js";
+
+export type TranslationParams = Record<
+	string,
+	string | number | boolean | Date | null | undefined
+>;
+export type MessageValue = string | number | boolean | null;
+export type MessageTree = { [key: string]: MessageValue | MessageTree };
+export type MessageCatalog = Record<string, string>;
+
+export interface TranslateOptions {
+	locale?: string;
+	defaultValue?: string;
+}
+
+export interface LocaleResolverInput {
+	header?: string | null;
+	accepted?: string[];
+}
+
+export interface RosettaLoader {
+	load(
+		locale: string,
+	): Promise<MessageTree | MessageCatalog | null | undefined>;
+}
+
+export interface RosettaOptions {
+	defaultLocale?: string;
+	supportedLocales?: string[];
+	fallbackLocale?: string;
+	fallbackLocales?: Record<string, string>;
+	messages?: Record<string, MessageTree | MessageCatalog>;
+	loaders?: RosettaLoader[];
+}
+
+/**
+ * Numeric separators for a resolved locale. Returned by
+ * `Rosetta.getNumberFormatData()` so consumers (e.g. `@c9up/atom`'s
+ * `Decimal.parseLocale`) can honor Rosetta's `fallbackLocales`
+ * chain when extracting group / decimal separators — without
+ * importing `@c9up/rosetta` directly (structural typing).
+ */
+export interface NumberFormatData {
+	decimal: string;
+	group: string;
+	minus: string;
+	plusSign: string;
+}
+
+interface StringNumberFormat extends Intl.NumberFormat {
+	format(value: number | bigint | string): string;
+}
+
+const DEFAULT_LOCALE = "en";
+
+export class RosettaLocale {
+	#manager: Rosetta;
+	#locale: string;
+
+	constructor(manager: Rosetta, locale: string) {
+		this.#manager = manager;
+		this.#locale = locale;
+	}
+
+	getLocale(): string {
+		return this.#locale;
+	}
+
+	has(key: string): boolean {
+		return this.#manager.has(key, this.#locale);
+	}
+
+	t(
+		key: string,
+		params?: TranslationParams,
+		options?: Omit<TranslateOptions, "locale">,
+	): string {
+		return this.#manager.t(key, params, { ...options, locale: this.#locale });
+	}
+
+	formatNumber(value: number, options?: Intl.NumberFormatOptions): string {
+		return this.#manager.formatNumber(value, options, this.#locale);
+	}
+
+	formatCurrency(
+		value: number,
+		currency: string,
+		options?: Intl.NumberFormatOptions,
+	): string {
+		return this.#manager.formatCurrency(value, currency, options, this.#locale);
+	}
+
+	formatDate(
+		value: Date | number | string,
+		options?: Intl.DateTimeFormatOptions,
+	): string {
+		return this.#manager.formatDate(value, options, this.#locale);
+	}
+
+	formatRelativeTime(
+		value: number,
+		unit: Intl.RelativeTimeFormatUnit,
+		options?: Intl.RelativeTimeFormatOptions,
+	): string {
+		return this.#manager.formatRelativeTime(value, unit, options, this.#locale);
+	}
+
+	getNumberFormatData(): NumberFormatData {
+		return this.#manager.getNumberFormatData(this.#locale);
+	}
+
+	formatNumberString(
+		value: string,
+		options?: Intl.NumberFormatOptions,
+	): string {
+		return this.#manager.formatNumberString(value, options, this.#locale);
+	}
+}
+
+/**
+ * Rosetta i18n manager.
+ *
+ * Framework-agnostic with request-scoped locale instances.
+ */
+export class Rosetta {
+	#messages: Map<string, MessageCatalog> = new Map();
+	#catalogsCache?: Record<string, MessageCatalog>;
+	#catalogsCacheDirty = true;
+	/** Stateful Rust engine (Story 37.9) — holds parsed catalogs in Rust memory. */
+	#nativeEngine: NativeRosettaEngine | null = createNativeEngine();
+	#locale: string;
+	#defaultLocale: string;
+	#fallbackLocale: string;
+	#fallbackLocales: Record<string, string>;
+	#supportedLocales?: Set<string>;
+	#loaders: RosettaLoader[];
+	#numberFormatDataCache: Map<string, NumberFormatData> = new Map();
+
+	constructor(options: RosettaOptions = {}) {
+		this.#defaultLocale = normalizeLocale(
+			options.defaultLocale ?? DEFAULT_LOCALE,
+		);
+		this.#locale = this.#defaultLocale;
+		this.#fallbackLocale = normalizeLocale(
+			options.fallbackLocale ?? this.#defaultLocale,
+		);
+		this.#fallbackLocales = normalizeFallbackMap(options.fallbackLocales ?? {});
+		this.#supportedLocales = options.supportedLocales
+			? new Set(options.supportedLocales.map(normalizeLocale))
+			: undefined;
+		this.#loaders = options.loaders ?? [];
+
+		if (options.messages) {
+			for (const [locale, catalog] of Object.entries(options.messages)) {
+				this.loadMessages(locale, catalog);
+			}
+		}
+	}
+
+	async boot(): Promise<void> {
+		if (!this.#supportedLocales || this.#loaders.length === 0) {
+			return;
+		}
+		for (const locale of this.#supportedLocales) {
+			await this.#loadFromLoaders(locale);
+		}
+	}
+
+	locale(locale: string): RosettaLocale {
+		return new RosettaLocale(this, normalizeLocale(locale));
+	}
+
+	loadMessages(locale: string, messages: MessageTree | MessageCatalog): this {
+		const normalizedLocale = normalizeLocale(locale);
+		const existing = this.#messages.get(normalizedLocale) ?? {};
+		const flattened = flattenMessages(messages);
+		this.#messages.set(normalizedLocale, { ...existing, ...flattened });
+		this.#catalogsCacheDirty = true;
+		return this;
+	}
+
+	async loadLocale(locale: string): Promise<this> {
+		await this.#loadFromLoaders(normalizeLocale(locale));
+		return this;
+	}
+
+	setLocale(locale: string): this {
+		this.#locale = normalizeLocale(locale);
+		return this;
+	}
+
+	getLocale(): string {
+		return this.#locale;
+	}
+
+	setDefaultLocale(locale: string): this {
+		this.#defaultLocale = normalizeLocale(locale);
+		// Invalidate the number-format-data cache: even though the
+		// cache is keyed by the *resolved* locale (so most entries
+		// stay correct across config changes), an entry produced by
+		// the previous "ultimate fallback" path may now mismatch.
+		this.#numberFormatDataCache.clear();
+		return this;
+	}
+
+	getDefaultLocale(): string {
+		return this.#defaultLocale;
+	}
+
+	setSupportedLocales(locales: string[]): this {
+		this.#supportedLocales = new Set(locales.map(normalizeLocale));
+		return this;
+	}
+
+	getSupportedLocales(): string[] | undefined {
+		return this.#supportedLocales
+			? Array.from(this.#supportedLocales)
+			: undefined;
+	}
+
+	setFallbackLocale(locale: string): this {
+		this.#fallbackLocale = normalizeLocale(locale);
+		this.#numberFormatDataCache.clear();
+		return this;
+	}
+
+	getFallbackLocale(): string {
+		return this.#fallbackLocale;
+	}
+
+	setFallbackLocales(locales: Record<string, string>): this {
+		this.#fallbackLocales = normalizeFallbackMap(locales);
+		this.#numberFormatDataCache.clear();
+		return this;
+	}
+
+	getFallbackLocales(): Record<string, string> {
+		return { ...this.#fallbackLocales };
+	}
+
+	resolveLocale(input: string | LocaleResolverInput): string {
+		const requested =
+			typeof input === "string"
+				? parseAcceptLanguage(input)
+				: (input.accepted ?? parseAcceptLanguage(input.header ?? ""));
+
+		for (const candidate of requested) {
+			const normalized = normalizeLocale(candidate);
+			const supported = this.#pickFirstSupported(
+				this.#localeChainFor(normalized),
+			);
+			if (supported) {
+				return supported;
+			}
+		}
+
+		const fallback = this.#pickFirstSupported(
+			this.#localeChainFor(this.#defaultLocale),
+		);
+		return fallback ?? this.#defaultLocale;
+	}
+
+	has(key: string, locale = this.#locale): boolean {
+		const normalizedLocale = normalizeLocale(locale);
+		const chain = this.#localeChainFor(normalizedLocale);
+
+		if (!this.#nativeEngine) {
+			throw new Error(
+				"[ROSETTA_NAPI_REQUIRED] The Rust ICU engine is required. Build it with `cd packages/rosetta && pnpm build:napi`.",
+			);
+		}
+		this.#syncNativeEngine();
+		return this.#nativeEngine.has(key, JSON.stringify(chain));
+	}
+
+	t(
+		key: string,
+		params?: TranslationParams,
+		options?: TranslateOptions,
+	): string {
+		const requestedLocale = normalizeLocale(options?.locale ?? this.#locale);
+		const chain = this.#localeChainFor(requestedLocale);
+
+		if (!this.#nativeEngine) {
+			throw new Error(
+				"[ROSETTA_NAPI_REQUIRED] The Rust ICU engine is required. Build it with `cd packages/rosetta && pnpm build:napi`.",
+			);
+		}
+		this.#syncNativeEngine();
+		const paramsJson = params ? JSON.stringify(params) : undefined;
+		return this.#nativeEngine.translate(
+			key,
+			paramsJson,
+			JSON.stringify(chain),
+			options?.defaultValue,
+		);
+	}
+
+	formatNumber(
+		value: number,
+		options?: Intl.NumberFormatOptions,
+		locale = this.#locale,
+	): string {
+		return new Intl.NumberFormat(normalizeLocale(locale), options).format(
+			value,
+		);
+	}
+
+	formatCurrency(
+		value: number,
+		currency: string,
+		options?: Intl.NumberFormatOptions,
+		locale = this.#locale,
+	): string {
+		// Spread `options` FIRST so explicit `style: "currency"` and
+		// `currency` always win — a caller's stray `{ style: "decimal" }`
+		// must not silently disable currency formatting.
+		return this.formatNumber(
+			value,
+			{ ...options, style: "currency", currency },
+			locale,
+		);
+	}
+
+	formatDate(
+		value: Date | number | string,
+		options?: Intl.DateTimeFormatOptions,
+		locale = this.#locale,
+	): string {
+		const date = value instanceof Date ? value : new Date(value);
+		return new Intl.DateTimeFormat(normalizeLocale(locale), options).format(
+			date,
+		);
+	}
+
+	formatRelativeTime(
+		value: number,
+		unit: Intl.RelativeTimeFormatUnit,
+		options?: Intl.RelativeTimeFormatOptions,
+		locale = this.#locale,
+	): string {
+		return new Intl.RelativeTimeFormat(normalizeLocale(locale), options).format(
+			value,
+			unit,
+		);
+	}
+
+	/**
+	 * Resolve the numeric separators for `locale`, honoring the
+	 * configured `fallbackLocales` chain. Returns the first locale
+	 * in the chain that `Intl.NumberFormat` actually supports.
+	 *
+	 * Cached per resolved locale so the `formatToParts` work runs
+	 * once per chain destination.
+	 */
+	getNumberFormatData(locale: string = this.#locale): NumberFormatData {
+		const resolved = this.#resolveNumberLocale(locale);
+		const cached = this.#numberFormatDataCache.get(resolved);
+		if (cached) return cached;
+		const formatter = new Intl.NumberFormat(resolved);
+		const negativeParts = formatter.formatToParts(-12345.6);
+		const positiveParts = new Intl.NumberFormat(resolved, {
+			signDisplay: "always",
+		}).formatToParts(1);
+		const data: NumberFormatData = {
+			decimal: negativeParts.find((p) => p.type === "decimal")?.value ?? ".",
+			group: negativeParts.find((p) => p.type === "group")?.value ?? ",",
+			minus: negativeParts.find((p) => p.type === "minusSign")?.value ?? "-",
+			plusSign: positiveParts.find((p) => p.type === "plusSign")?.value ?? "+",
+		};
+		this.#numberFormatDataCache.set(resolved, data);
+		return data;
+	}
+
+	/**
+	 * Format a string-valued number through `Intl.NumberFormat`'s
+	 * string-accepting overload — preserves precision on 18+-digit
+	 * values that would otherwise truncate via `Number()`.
+	 *
+	 * Locale resolution uses the same fallback chain as
+	 * `getNumberFormatData`.
+	 */
+	formatNumberString(
+		value: string,
+		options?: Intl.NumberFormatOptions,
+		locale = this.#locale,
+	): string {
+		const resolved = this.#resolveNumberLocale(locale);
+		const formatter = new Intl.NumberFormat(
+			resolved,
+			options,
+		) as StringNumberFormat;
+		return formatter.format(value);
+	}
+
+	#resolveNumberLocale(locale: string): string {
+		const chain = this.#localeChainFor(normalizeLocale(locale));
+		for (const candidate of chain) {
+			const supported = Intl.NumberFormat.supportedLocalesOf([candidate], {
+				localeMatcher: "lookup",
+			});
+			if (supported.length > 0) return supported[0];
+		}
+		// Last-resort: the configured #defaultLocale itself may not be
+		// Intl-supported (e.g. an invented private-use tag). Validate
+		// it once so the cache key is always a real Intl locale.
+		const defaultSupported = Intl.NumberFormat.supportedLocalesOf(
+			[this.#defaultLocale],
+			{ localeMatcher: "lookup" },
+		);
+		if (defaultSupported.length > 0) return defaultSupported[0];
+		// Truly unresolvable — fall back to "en", which every Intl
+		// implementation must support per ECMA-402.
+		return "en";
+	}
+
+	async #loadFromLoaders(locale: string): Promise<void> {
+		for (const loader of this.#loaders) {
+			const messages = await loader.load(locale);
+			if (messages) {
+				this.loadMessages(locale, messages);
+			}
+		}
+	}
+
+	#pickFirstSupported(candidates: string[]): string | undefined {
+		if (!this.#supportedLocales) {
+			return candidates[0];
+		}
+		return candidates.find((candidate) =>
+			this.#supportedLocales?.has(candidate),
+		);
+	}
+
+	#localeChainFor(locale: string): string[] {
+		const chain: string[] = [];
+		const visited = new Set<string>();
+		const push = (value: string) => {
+			const normalized = normalizeLocale(value);
+			if (!normalized || visited.has(normalized)) return;
+			visited.add(normalized);
+			chain.push(normalized);
+		};
+
+		push(locale);
+
+		const localeParts = locale.split("-");
+		if (localeParts.length > 1) {
+			push(localeParts[0]);
+		}
+
+		const explicitFallback = this.#fallbackLocales[locale];
+		if (explicitFallback) {
+			push(explicitFallback);
+			const explicitParts = explicitFallback.split("-");
+			if (explicitParts.length > 1) {
+				push(explicitParts[0]);
+			}
+		}
+
+		push(this.#fallbackLocale);
+		const fallbackParts = this.#fallbackLocale.split("-");
+		if (fallbackParts.length > 1) {
+			push(fallbackParts[0]);
+		}
+		push(this.#defaultLocale);
+		const defaultParts = this.#defaultLocale.split("-");
+		if (defaultParts.length > 1) {
+			push(defaultParts[0]);
+		}
+
+		return chain;
+	}
+
+	/**
+	 * Sync the Rust-resident catalog with the TS-side `#messages` map. Only
+	 * performs JSON.stringify when the dirty flag is set (a locale was loaded or
+	 * edited). On subsequent `t()` / `has()` calls with no changes, this is a
+	 * no-op — the Rust engine already holds the parsed catalog in memory.
+	 *
+	 * Story 37.9: this replaces the old `#catalogsJson()` which serialized the
+	 * entire catalog on EVERY `t()` call.
+	 */
+	#syncNativeEngine(): void {
+		if (!this.#nativeEngine) return;
+		if (!this.#catalogsCacheDirty && this.#catalogsCache) return;
+		const cache: Record<string, MessageCatalog> = {};
+		for (const [locale, catalog] of this.#messages.entries()) {
+			cache[locale] = catalog;
+		}
+		// loadCatalogs may throw (malformed JSON, lock poisoned). The dirty flag
+		// is only cleared AFTER a successful load so a retry on the next t()
+		// call re-attempts instead of silently using a stale/empty catalog.
+		this.#nativeEngine.loadCatalogs(JSON.stringify(cache));
+		this.#catalogsCache = cache;
+		this.#catalogsCacheDirty = false;
+	}
+}
+
+function normalizeLocale(locale: string): string {
+	return locale.trim().replace(/_/g, "-").toLowerCase();
+}
+
+function normalizeFallbackMap(
+	map: Record<string, string>,
+): Record<string, string> {
+	const normalized: Record<string, string> = {};
+	for (const [from, to] of Object.entries(map)) {
+		normalized[normalizeLocale(from)] = normalizeLocale(to);
+	}
+	return normalized;
+}
+
+function parseAcceptLanguage(header: string): string[] {
+	return header
+		.split(",")
+		.map((item) => item.trim())
+		.filter(Boolean)
+		.map((item) => {
+			const [localePart, ...rest] = item.split(";");
+			let quality = 1;
+			for (const part of rest) {
+				const trimmed = part.trim();
+				if (trimmed.startsWith("q=")) {
+					const n = Number(trimmed.slice(2));
+					if (Number.isFinite(n)) quality = n;
+				}
+			}
+			return { locale: normalizeLocale(localePart), quality };
+		})
+		.filter((entry) => entry.locale.length > 0)
+		.sort((a, b) => b.quality - a.quality)
+		.map((entry) => entry.locale);
+}
+
+function flattenMessages(
+	messages: MessageTree | MessageCatalog,
+): MessageCatalog {
+	const out: MessageCatalog = {};
+	walkFlatten("", messages, out);
+	return out;
+}
+
+function walkFlatten(
+	prefix: string,
+	value: MessageTree | MessageCatalog | MessageValue,
+	out: MessageCatalog,
+): void {
+	if (typeof value === "string") {
+		out[prefix] = value;
+		return;
+	}
+	if (typeof value === "number" || typeof value === "boolean") {
+		out[prefix] = String(value);
+		return;
+	}
+	if (value === null || value === undefined) {
+		return;
+	}
+
+	for (const [key, child] of Object.entries(value)) {
+		const next = prefix ? `${prefix}.${key}` : key;
+		walkFlatten(
+			next,
+			child as MessageTree | MessageCatalog | MessageValue,
+			out,
+		);
+	}
+}

package/src/RosettaProvider.ts

@@ -0,0 +1,77 @@
+import { FileSystemLoader } from "./loaders/FileSystemLoader.js";
+import { Rosetta, type RosettaOptions } from "./Rosetta.js";
+import { setI18n } from "./services/main.js";
+
+/**
+ * Duck-typed host context — rosetta stays publishable without
+ * importing `@c9up/ream`. Any framework that exposes a Container + a
+ * config store satisfies the contract.
+ */
+interface RosettaContainer {
+	singleton(token: unknown, factory: () => unknown): void;
+	resolve<T = unknown>(token: unknown): T;
+}
+interface RosettaConfigStore {
+	get<T = unknown>(key: string): T | undefined;
+}
+export interface RosettaAppContext {
+	container: RosettaContainer;
+	config: RosettaConfigStore;
+}
+
+export interface RosettaProviderConfig extends RosettaOptions {
+	/**
+	 * If set, a `FileSystemLoader` reading from this directory is
+	 * appended to `options.loaders`. Most apps only need this and the
+	 * `supportedLocales` list — the provider's `boot()` calls
+	 * `rosetta.boot()` so catalogs are warm before the first request.
+	 */
+	rootDir?: string;
+}
+
+/**
+ * RosettaProvider — registers a shared `Rosetta` instance under
+ * `Rosetta` + `"i18n"` tokens, then awaits its boot so the configured
+ * locale catalogs are loaded by the time the first request lands.
+ *
+ *   // reamrc.ts
+ *   providers: [() => import('@c9up/rosetta/provider')]
+ *
+ *   // config/i18n.ts
+ *   import { resolve } from 'node:path'
+ *   export default {
+ *     defaultLocale: 'en',
+ *     supportedLocales: ['en', 'fr'],
+ *     rootDir: resolve('./resources/lang'),
+ *   }
+ *
+ *   // anywhere
+ *   import i18n from '@c9up/rosetta/services/main'
+ *   const t = i18n.locale('fr').t('greeting', { name: 'Alice' })
+ */
+export default class RosettaProvider {
+	constructor(protected app: RosettaAppContext) {}
+
+	register(): void {
+		this.app.container.singleton(Rosetta, () => {
+			const config = this.app.config.get<RosettaProviderConfig>("i18n");
+			const options: RosettaOptions = { ...(config ?? {}) };
+			if (config?.rootDir) {
+				const fsLoader = new FileSystemLoader({ rootDir: config.rootDir });
+				options.loaders = [...(options.loaders ?? []), fsLoader];
+			}
+			return new Rosetta(options);
+		});
+		this.app.container.singleton("i18n", () =>
+			this.app.container.resolve<Rosetta>(Rosetta),
+		);
+	}
+
+	async boot(): Promise<void> {
+		const rosetta = this.app.container.resolve<Rosetta>(Rosetta);
+		await rosetta.boot();
+		setI18n(rosetta);
+	}
+
+	async shutdown(): Promise<void> {}
+}

package/src/index.ts

@@ -0,0 +1,19 @@
+/**
+ * @c9up/rosetta — framework-agnostic internationalization module.
+ */
+
+export type { FileSystemLoaderOptions } from "./loaders/FileSystemLoader.js";
+export { FileSystemLoader } from "./loaders/FileSystemLoader.js";
+export { isNativeAvailable } from "./native.js";
+export type {
+	LocaleResolverInput,
+	MessageCatalog,
+	MessageTree,
+	NumberFormatData,
+	RosettaLoader,
+	RosettaLocale,
+	RosettaOptions,
+	TranslateOptions,
+	TranslationParams,
+} from "./Rosetta.js";
+export { Rosetta } from "./Rosetta.js";

package/src/loaders/FileSystemLoader.ts

@@ -0,0 +1,191 @@
+import * as fsp from "node:fs/promises";
+import * as path from "node:path";
+import type { MessageCatalog, MessageTree, RosettaLoader } from "../Rosetta.js";
+
+/** IANA BCP 47 locale ID pattern — allows `en`, `en-US`, `zh-Hant-TW`, etc. */
+const SAFE_LOCALE_PATTERN = /^[a-zA-Z]{2,8}(-[a-zA-Z0-9]{2,8})*$/;
+
+export interface FileSystemLoaderOptions {
+	rootDir: string;
+}
+
+export class FileSystemLoader implements RosettaLoader {
+	#rootDir: string;
+
+	constructor(options: FileSystemLoaderOptions) {
+		this.#rootDir = options.rootDir;
+	}
+
+	async load(locale: string): Promise<MessageTree | MessageCatalog | null> {
+		// Validate locale to prevent path traversal. A locale like
+		// `../../etc/passwd` would escape the rootDir without this check.
+		if (!SAFE_LOCALE_PATTERN.test(locale)) return null;
+
+		for (const ext of ["json", "yaml", "yml"]) {
+			const fullPath = path.join(this.#rootDir, `${locale}.${ext}`);
+			// Defense-in-depth: verify the resolved path is still inside rootDir
+			// even after the regex check (belt + suspenders).
+			if (!path.resolve(fullPath).startsWith(path.resolve(this.#rootDir)))
+				return null;
+
+			try {
+				const raw = await fsp.readFile(fullPath, "utf8");
+				return ext === "json"
+					? (JSON.parse(raw) as MessageTree | MessageCatalog)
+					: parseYaml(raw);
+			} catch (err: unknown) {
+				// ENOENT = file doesn't exist → try next extension. Any other error
+				// (permission denied, invalid JSON, disk failure) is a real problem
+				// that must surface — silently swallowing it would turn a config bug
+				// into a "missing translation" ghost that's impossible to debug in prod.
+				const code = (err as NodeJS.ErrnoException)?.code;
+				if (code === "ENOENT") continue;
+				throw err;
+			}
+		}
+		return null;
+	}
+}
+
+/**
+ * Minimal YAML parser for locale files. Supports:
+ * - Nested keys via indentation
+ * - Quoted and unquoted scalar values
+ * - Colons in values (URLs like `https://example.com`)
+ * - Multiline block scalars: `|` (literal) and `>` (folded)
+ * - Comments (`#`)
+ *
+ * Does NOT support: anchors/aliases (`&`/`*`), flow sequences (`[a, b]`),
+ * flow mappings (`{a: 1}`), complex keys, merge keys (`<<`), or tags (`!!`).
+ * For production apps with complex locale files, replace with `js-yaml`.
+ */
+function parseYaml(input: string): MessageTree {
+	const root: MessageTree = {};
+	const stack: Array<{ indent: number; node: MessageTree }> = [
+		{ indent: -1, node: root },
+	];
+	const lines = input.split(/\r?\n/);
+	let i = 0;
+
+	while (i < lines.length) {
+		const rawLine = lines[i];
+		i++;
+		if (!rawLine.trim() || rawLine.trim().startsWith("#")) continue;
+
+		// Match `key:` with an optional value. The key stops at the first unquoted
+		// colon that is NOT inside a URL scheme (`://`). We use a simpler heuristic:
+		// split on the first `:` followed by a space or end-of-line. This correctly
+		// handles `url: https://example.com` because the `: ` after `url` is the
+		// first split point, and `://` inside the value has no preceding space.
+		const match = rawLine.match(/^(\s*)([^:#\s][^:]*?)\s*:\s*(.*)$/);
+		if (!match) continue;
+
+		const indent = match[1].length;
+		const key = match[2].trim();
+		let valueRaw = match[3].trim();
+
+		while (stack.length > 1 && indent <= stack[stack.length - 1].indent) {
+			stack.pop();
+		}
+		const parent = stack[stack.length - 1].node;
+
+		// Block scalar: `|` (literal) or `>` (folded).
+		if (valueRaw === "|" || valueRaw === ">") {
+			const block = parseBlockScalar(lines, i, indent, valueRaw === ">");
+			parent[key] = block.value;
+			i = block.nextIndex;
+			continue;
+		}
+
+		if (!valueRaw) {
+			const child: MessageTree = {};
+			parent[key] = child;
+			stack.push({ indent, node: child });
+			continue;
+		}
+
+		// Strip inline comments: `value # comment` → `value`. But only if the `#`
+		// is preceded by whitespace (to avoid stripping inside URLs like `#fragment`).
+		const commentIdx = valueRaw.search(/\s+#/);
+		if (commentIdx > 0) valueRaw = valueRaw.slice(0, commentIdx).trim();
+
+		parent[key] = parseScalar(valueRaw);
+	}
+
+	return root;
+}
+
+/**
+ * Consume a `|` (literal) or `>` (folded) block scalar starting at `startIndex`.
+ * Returns the joined value and the index of the first line past the block.
+ */
+function parseBlockScalar(
+	lines: string[],
+	startIndex: number,
+	indent: number,
+	fold: boolean,
+): { value: string; nextIndex: number } {
+	const blockLines: string[] = [];
+	const blockIndent = indent + 2;
+	let i = startIndex;
+	while (i < lines.length) {
+		const bl = lines[i];
+		// A line with less indent (or empty after content) ends the block.
+		if (bl.trim() && bl.search(/\S/) < blockIndent) break;
+		blockLines.push(bl.slice(blockIndent) || "");
+		i++;
+	}
+	// Trim trailing empty lines.
+	while (blockLines.length > 0 && blockLines[blockLines.length - 1] === "") {
+		blockLines.pop();
+	}
+	return {
+		value: fold ? foldParagraphs(blockLines) : blockLines.join("\n"),
+		nextIndex: i,
+	};
+}
+
+/**
+ * Fold a `>` block scalar: consecutive non-blank lines join with a space, blank
+ * lines become hard newlines (paragraph breaks per the YAML spec).
+ */
+function foldParagraphs(blockLines: string[]): string {
+	const paragraphs: string[] = [];
+	let current: string[] = [];
+	for (const bl of blockLines) {
+		if (bl === "") {
+			if (current.length > 0) paragraphs.push(current.join(" "));
+			current = [];
+			paragraphs.push("");
+		} else {
+			current.push(bl);
+		}
+	}
+	if (current.length > 0) paragraphs.push(current.join(" "));
+	return paragraphs.join("\n");
+}
+
+function parseScalar(value: string): string | number | boolean | null {
+	if (value.startsWith('"') && value.endsWith('"')) {
+		// Double-quoted: process YAML escape sequences (\n, \t, \\, \', \")
+		return value
+			.slice(1, -1)
+			.replace(/\\n/g, "\n")
+			.replace(/\\t/g, "\t")
+			.replace(/\\\\/g, "\\")
+			.replace(/\\'/g, "'")
+			.replace(/\\"/g, '"');
+	}
+	if (value.startsWith("'") && value.endsWith("'")) {
+		// Single-quoted: only '' escape (doubled apostrophe → single)
+		return value.slice(1, -1).replace(/''/g, "'");
+	}
+	if (value === "true") return true;
+	if (value === "false") return false;
+	if (value === "null") return null;
+
+	const n = Number(value);
+	if (Number.isFinite(n) && value !== "") return n;
+
+	return value;
+}

package/src/native.ts

@@ -0,0 +1,162 @@
+/**
+ * Universal engine loader — auto-detects Node (NAPI) vs Browser (WASM).
+ *
+ * Node gets the stateful `RosettaEngine` class (resident catalog in Rust memory).
+ * Browser gets the stateless WASM functions (re-parse catalog per call — acceptable
+ * because browser apps typically have smaller catalogs than server-rendered i18n).
+ */
+
+export interface NativeRosettaEngine {
+	loadCatalogs(catalogsJson: string): void;
+	translate(
+		key: string,
+		paramsJson: string | undefined,
+		chainJson: string,
+		defaultValue: string | undefined,
+	): string;
+	has(key: string, chainJson: string): boolean;
+}
+
+interface NativeModule {
+	RosettaEngine: new () => NativeRosettaEngine;
+	translate: (
+		catalogsJson: string,
+		key: string,
+		paramsJson: string | undefined,
+		chainJson: string,
+		defaultValue: string | undefined,
+	) => string;
+	has: (catalogsJson: string, key: string, chainJson: string) => boolean;
+}
+
+let native: NativeModule | undefined;
+interface WasmStatelessApi {
+	translate(
+		catalogsJson: string,
+		key: string,
+		paramsJson: string | undefined,
+		chainJson: string,
+		defaultValue: string | undefined,
+	): string;
+	has(catalogsJson: string, key: string, chainJson: string): boolean;
+}
+let wasmModule: WasmStatelessApi | undefined;
+let loadError: unknown;
+
+const isNode =
+	typeof globalThis.process !== "undefined" &&
+	typeof globalThis.process.versions?.node === "string";
+
+if (isNode) {
+	try {
+		const { createRequire } = await import("node:module");
+		const { dirname, join } = await import("node:path");
+		const { fileURLToPath } = await import("node:url");
+		const { arch, platform } = await import("node:process");
+
+		const nodeRequire = createRequire(import.meta.url);
+		const currentDir = dirname(fileURLToPath(import.meta.url));
+
+		const platformMap: Record<string, string> = {
+			"linux-x64": "linux-x64-gnu",
+			"linux-arm64": "linux-arm64-gnu",
+			"darwin-x64": "darwin-x64",
+			"darwin-arm64": "darwin-arm64",
+			"win32-x64": "win32-x64-msvc",
+		};
+
+		const suffix = platformMap[`${platform}-${arch}`];
+		if (suffix) {
+			native = nodeRequire(join(currentDir, `../index.${suffix}.node`));
+		}
+	} catch (e) {
+		loadError = e;
+	}
+} else {
+	try {
+		// The WASM glue generated by wasm-pack exports `translate` and `has` as
+		// top-level functions with the exact same signatures as `WasmStatelessApi`.
+		// We declare the import shape explicitly so no cast is needed.
+		const wasm: { default: () => Promise<unknown> } & WasmStatelessApi =
+			await import("../wasm/rosetta_engine_wasm.js");
+		await wasm.default();
+		wasmModule = wasm;
+	} catch (e) {
+		loadError = e;
+	}
+}
+
+export function isNativeAvailable(): boolean {
+	return native !== undefined || wasmModule !== undefined;
+}
+
+/** Create a stateful engine (Node NAPI only). Returns null in browser (WASM is stateless). */
+export function createNativeEngine(): NativeRosettaEngine | null {
+	if (!native) {
+		if (!wasmModule) return null;
+		const wasm = wasmModule;
+		let catalogsJson = "{}";
+		return {
+			loadCatalogs(json: string) {
+				catalogsJson = json;
+			},
+			translate(key, paramsJson, chainJson, defaultValue) {
+				return wasm.translate(
+					catalogsJson,
+					key,
+					paramsJson ?? undefined,
+					chainJson,
+					defaultValue ?? undefined,
+				) as string;
+			},
+			has(key, chainJson) {
+				return wasm.has(catalogsJson, key, chainJson) as boolean;
+			},
+		};
+	}
+	return new native.RosettaEngine();
+}
+
+// Legacy stateless exports (used by tests)
+export function nativeTranslate(
+	catalogsJson: string,
+	key: string,
+	paramsJson: string | undefined,
+	chainJson: string,
+	defaultValue: string | undefined,
+): string {
+	if (native)
+		return native.translate(
+			catalogsJson,
+			key,
+			paramsJson,
+			chainJson,
+			defaultValue,
+		);
+	if (wasmModule)
+		return wasmModule.translate(
+			catalogsJson,
+			key,
+			paramsJson,
+			chainJson,
+			defaultValue,
+		) as string;
+	throw new Error(
+		`[ROSETTA_ENGINE_NOT_FOUND] ${loadError ?? "binary not found"}`,
+		{ cause: loadError },
+	);
+}
+
+export function nativeHas(
+	catalogsJson: string,
+	key: string,
+	chainJson: string,
+): boolean {
+	if (native) return native.has(catalogsJson, key, chainJson);
+	if (wasmModule)
+		return wasmModule.has(catalogsJson, key, chainJson) as boolean;
+	throw new Error(
+		`[ROSETTA_ENGINE_NOT_FOUND] ${loadError ?? "binary not found"}`,
+		{ cause: loadError },
+	);
+}

package/src/services/main.ts

@@ -0,0 +1,42 @@
+/**
+ * Default `Rosetta` singleton — mirror of Adonis's
+ * `import i18n from '@adonisjs/i18n/services/main'` shape.
+ *
+ *   import i18n from '@c9up/rosetta/services/main'
+ *
+ *   const locale = i18n.locale(i18n.resolveLocale({ header: req.headers['accept-language'] }))
+ *   locale.t('greeting', { name: user.name })
+ *
+ * Populated by `RosettaProvider.boot()` or by the app directly through
+ * `setI18n(myRosetta)` when the i18n config has to be built outside
+ * the provider flow.
+ */
+
+import type { Rosetta } from "../Rosetta.js";
+
+let instance: Rosetta | undefined;
+
+/** @internal Bind the singleton (called by RosettaProvider or the app). */
+export function setI18n(value: Rosetta): void {
+	instance = value;
+}
+
+/** @internal Read the singleton (or `undefined` pre-boot). */
+export function getI18n(): Rosetta | undefined {
+	return instance;
+}
+
+const i18n: Rosetta = new Proxy({} as Rosetta, {
+	get(_target, prop) {
+		if (!instance) {
+			throw new Error(
+				"[rosetta] Rosetta singleton accessed before RosettaProvider.boot() ran " +
+					"or `setI18n(myRosetta)` was called. Wire one of them first.",
+			);
+		}
+		const value = Reflect.get(instance, prop, instance);
+		return typeof value === "function" ? value.bind(instance) : value;
+	},
+});
+
+export default i18n;

package/wasm/rosetta_engine_wasm.d.ts

@@ -0,0 +1,27 @@
+// Hand-written stub for the wasm-pack-generated glue file. Lets `tsc --noEmit`
+// pass on a fresh checkout before `pnpm build:wasm` has been run. wasm-pack
+// will overwrite this file with its real generated declarations on the next
+// `build:wasm`; the runtime shape stays compatible.
+//
+// Story 52.1 review patch (2026-05-09): a) WASM artefact was previously
+// emitted to `../../dist/wasm/` (sibling of the package, outside its
+// tarball surface) while src/native.ts imported `../dist/wasm/...`. The
+// artefact never landed in the published tarball — a browser consumer
+// would hit `Cannot find module` at runtime. Same pattern as Epic 51 F3+F4
+// (atom + chronos). Fixed: build:wasm out-dir is now `../../wasm` (lands
+// inside the package), import path is `../wasm/...`, package.json files
+// array now includes `wasm`. b) typecheck was also broken on a fresh
+// checkout because tsc couldn't find this module before `build:wasm` had
+// been run. This stub provides the minimum types needed.
+
+export default function init(): Promise<unknown>;
+
+export function translate(
+  catalogsJson: string,
+  key: string,
+  paramsJson: string | undefined,
+  chainJson: string,
+  defaultValue: string | undefined,
+): string;
+
+export function has(catalogsJson: string, key: string, chainJson: string): boolean;