@junejs/i18n 0.0.29-dev.1

package/dist/codegen.d.ts

@@ -0,0 +1,22 @@
+import { t as CompiledCatalog } from "./format-C_VeKYVf.js";
+import "./compile.js";
+//#region src/codegen.d.ts
+/** Read + compile messages → compiled catalogs keyed by locale. Two layouts,
+ *  mergeable: flat `messages/<locale>.json` (root keys) and namespaced
+ *  `messages/<locale>/<ns>.json` (keys prefixed `<ns>.`). The runtime half of the
+ *  codegen, exposed for tests. */
+declare function loadMessages(messagesDir: string): {
+  catalogs: Record<string, CompiledCatalog>;
+  raw: Record<string, Record<string, string>>;
+  locales: string[];
+};
+/** Generate the frozen `_messages.ts` module text from `messages/`. The default
+ *  locale is the type source of truth (its keys define `Messages`). */
+declare function generateMessagesModule(messagesDir: string, opts: {
+  defaultLocale: string;
+}): {
+  code: string;
+  locales: string[];
+};
+//#endregion
+export { generateMessagesModule, loadMessages };

package/dist/codegen.js

@@ -0,0 +1,80 @@
+import { compileCatalog, deriveParams } from "./compile.js";
+import { readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+//#region src/codegen.ts
+const TS_TYPE = {
+	string: "string",
+	number: "number",
+	Date: "Date",
+	tag: "(chunks: ReactNode) => ReactNode"
+};
+/** Read + compile messages → compiled catalogs keyed by locale. Two layouts,
+*  mergeable: flat `messages/<locale>.json` (root keys) and namespaced
+*  `messages/<locale>/<ns>.json` (keys prefixed `<ns>.`). The runtime half of the
+*  codegen, exposed for tests. */
+function loadMessages(messagesDir) {
+	const raw = {};
+	const readJson = (path) => JSON.parse(readFileSync(path, "utf8"));
+	const merge = (locale, entries) => Object.assign(raw[locale] ??= {}, entries);
+	for (const ent of readdirSync(messagesDir, { withFileTypes: true })) if (ent.isFile() && ent.name.endsWith(".json")) merge(ent.name.replace(/\.json$/, ""), readJson(join(messagesDir, ent.name)));
+	else if (ent.isDirectory()) {
+		const locale = ent.name;
+		const sub = join(messagesDir, locale);
+		for (const f of readdirSync(sub).filter((x) => x.endsWith(".json"))) {
+			const ns = f.replace(/\.json$/, "");
+			const prefixed = {};
+			for (const [k, v] of Object.entries(readJson(join(sub, f)))) prefixed[`${ns}.${k}`] = v;
+			merge(locale, prefixed);
+		}
+	}
+	const catalogs = {};
+	for (const [locale, entries] of Object.entries(raw)) catalogs[locale] = compileCatalog(entries);
+	return {
+		catalogs,
+		raw,
+		locales: Object.keys(catalogs)
+	};
+}
+function paramsType(catalog, key) {
+	const params = deriveParams(catalog[key]);
+	const names = Object.keys(params);
+	if (names.length === 0) return "Record<never, never>";
+	return `{ ${names.map((n) => `${JSON.stringify(n)}: ${TS_TYPE[params[n]]}`).join("; ")} }`;
+}
+/** Generate the frozen `_messages.ts` module text from `messages/`. The default
+*  locale is the type source of truth (its keys define `Messages`). */
+function generateMessagesModule(messagesDir, opts) {
+	const { catalogs, locales } = loadMessages(messagesDir);
+	const defaultCatalog = catalogs[opts.defaultLocale] ?? {};
+	const entries = Object.keys(defaultCatalog).sort().map((key) => `  ${JSON.stringify(key)}: ${paramsType(defaultCatalog, key)};`).join("\n");
+	return {
+		code: `// AUTO-GENERATED by \`june gen\` — edit messages/*.json, not this file.
+import { defineMessages, t as rawT, type CompiledCatalog } from "@junejs/i18n";
+import type { ReactNode } from "react";
+
+const CATALOGS: Record<string, CompiledCatalog> = ${JSON.stringify(catalogs)};\n\ndefineMessages(CATALOGS, { defaultLocale: ${JSON.stringify(opts.defaultLocale)} });\n\n// The message keys + their params, derived from the default locale's ICU ASTs.
+export type Messages = {\n${entries}\n};\n\n// A key with a <tag> param has a function param → it must go through t.rich.
+type HasTag<P> = true extends
+  { [K in keyof P]: P[K] extends (...a: never[]) => unknown ? true : never }[keyof P]
+  ? true : false;
+type PlainKey = { [K in keyof Messages]: HasTag<Messages[K]> extends true ? never : K }[keyof Messages];
+
+// Typed translate: key AND params are checked against messages/*.json. A no-
+// param message takes no second arg; a wrong/missing param or unknown key is a
+// compile error. t.rich renders <tag>s to ReactNode (tag keys require it).
+export const t = rawT as unknown as {
+  <K extends PlainKey>(
+    key: K,
+    ...args: keyof Messages[K] extends never ? [] : [params: Messages[K]]
+  ): string;
+  rich: <K extends keyof Messages>(
+    key: K,
+    ...args: keyof Messages[K] extends never ? [] : [params: Messages[K]]
+  ) => ReactNode;
+};
+`,
+		locales
+	};
+}
+//#endregion
+export { generateMessagesModule, loadMessages };

package/dist/compile.d.ts

@@ -0,0 +1,13 @@
+import { n as CompiledMessage, t as CompiledCatalog } from "./format-C_VeKYVf.js";
+//#region src/compile.d.ts
+/** Parse one ICU string to its AST. */
+declare function parseMessage(icu: string): CompiledMessage;
+/** Parse a whole `{ key: icuString }` catalog to ASTs. */
+declare function compileCatalog(raw: Record<string, string>): CompiledCatalog;
+type ParamType = "string" | "number" | "Date" | "tag";
+/** The params a message needs, derived from its AST. Plural/number args are
+ *  numbers, date/time are Dates, plain `{x}` and select keys are strings. This is
+ *  what the codegen turns into `t`'s typed signature. */
+declare function deriveParams(msg: CompiledMessage, into?: Record<string, ParamType>): Record<string, ParamType>;
+//#endregion
+export { type CompiledCatalog, type CompiledMessage, ParamType, compileCatalog, deriveParams, parseMessage };

package/dist/compile.js

@@ -0,0 +1,45 @@
+import { TYPE, parse } from "@formatjs/icu-messageformat-parser";
+//#region src/compile.ts
+/** Parse one ICU string to its AST. */
+function parseMessage(icu) {
+	return parse(icu);
+}
+/** Parse a whole `{ key: icuString }` catalog to ASTs. */
+function compileCatalog(raw) {
+	const out = {};
+	for (const [key, icu] of Object.entries(raw)) out[key] = parseMessage(icu);
+	return out;
+}
+/** The params a message needs, derived from its AST. Plural/number args are
+*  numbers, date/time are Dates, plain `{x}` and select keys are strings. This is
+*  what the codegen turns into `t`'s typed signature. */
+function deriveParams(msg, into = {}) {
+	for (const el of msg) switch (el.type) {
+		case TYPE.argument:
+			into[el.value] ??= "string";
+			break;
+		case TYPE.number:
+			into[el.value] = "number";
+			break;
+		case TYPE.date:
+		case TYPE.time:
+			into[el.value] = "Date";
+			break;
+		case TYPE.plural:
+			into[el.value] = "number";
+			for (const o of Object.values(el.options)) deriveParams(o.value, into);
+			break;
+		case TYPE.select:
+			into[el.value] ??= "string";
+			for (const o of Object.values(el.options)) deriveParams(o.value, into);
+			break;
+		case TYPE.tag:
+			into[el.value] = "tag";
+			deriveParams(el.children, into);
+			break;
+		default: break;
+	}
+	return into;
+}
+//#endregion
+export { compileCatalog, deriveParams, parseMessage };

package/dist/format-C_VeKYVf.d.ts

@@ -0,0 +1,9 @@
+import { MessageFormatElement } from "@formatjs/icu-messageformat-parser";
+//#region src/format.d.ts
+/** A compiled message: the parsed ICU AST (what defineMessages ships). */
+type CompiledMessage = MessageFormatElement[];
+type CompiledCatalog = Record<string, CompiledMessage>;
+/** Format a compiled message in `locale` with `params`. */
+declare function formatMessage(msg: CompiledMessage, locale: string, params?: Record<string, unknown>): string;
+//#endregion
+export { CompiledMessage as n, formatMessage as r, CompiledCatalog as t };

package/dist/format.d.ts

@@ -0,0 +1,2 @@
+import { n as CompiledMessage, r as formatMessage, t as CompiledCatalog } from "./format-C_VeKYVf.js";
+export { CompiledCatalog, CompiledMessage, formatMessage };

package/dist/format.js

@@ -0,0 +1,42 @@
+import { TYPE } from "@formatjs/icu-messageformat-parser";
+//#region src/format.ts
+const num = (locale, n) => new Intl.NumberFormat(locale).format(n);
+function evaluate(els, locale, params, pound) {
+	let out = "";
+	for (const el of els) switch (el.type) {
+		case TYPE.literal:
+			out += el.value;
+			break;
+		case TYPE.argument:
+			out += el.value in params ? String(params[el.value]) : `{${el.value}}`;
+			break;
+		case TYPE.number:
+			out += num(locale, Number(params[el.value]));
+			break;
+		case TYPE.pound:
+			out += num(locale, pound ?? 0);
+			break;
+		case TYPE.plural: {
+			const n = Number(params[el.value]);
+			const exact = `=${n}`;
+			const cat = el.options[exact] !== void 0 ? exact : new Intl.PluralRules(locale, { type: el.pluralType === "ordinal" ? "ordinal" : "cardinal" }).select(n - el.offset);
+			const opt = el.options[cat] ?? el.options.other;
+			if (opt) out += evaluate(opt.value, locale, params, n - el.offset);
+			break;
+		}
+		case TYPE.select: {
+			const v = String(params[el.value]);
+			const opt = el.options[v] ?? el.options.other;
+			if (opt) out += evaluate(opt.value, locale, params, pound);
+			break;
+		}
+		default: break;
+	}
+	return out;
+}
+/** Format a compiled message in `locale` with `params`. */
+function formatMessage(msg, locale, params) {
+	return evaluate(msg, locale, params ?? {});
+}
+//#endregion
+export { formatMessage };

package/dist/index.d.ts

@@ -0,0 +1,37 @@
+import { n as CompiledMessage, r as formatMessage, t as CompiledCatalog } from "./format-C_VeKYVf.js";
+import { formatRich } from "./rich.js";
+import { ReactNode } from "react";
+//#region src/index.d.ts
+/** A translator: callable for a plain string, `.rich` for embedded components. */
+type Translator = {
+  (key: string, params?: Record<string, unknown>): string;
+  rich(key: string, params?: Record<string, unknown>): ReactNode;
+};
+type MessagesConfig = {
+  catalogs: Record<string, CompiledCatalog>;
+  defaultLocale: string;
+};
+/** Register the compiled message catalogs (called once at app boot). A build step
+ *  generates this call — with compiled ASTs — from `messages/*.json`. */
+declare function defineMessages(catalogs: Record<string, CompiledCatalog>, opts: {
+  defaultLocale: string;
+}): void;
+/** A pure translator bound to a locale + compiled catalogs. The fallback chain is
+ *  variant → default locale → the key itself (dev-warns on a miss). Exposed for
+ *  tests and for non-ambient use (islands receive a translator built from props). */
+declare function createTranslator(locale: string, catalogs: Record<string, CompiledCatalog>, defaultLocale: string): Translator;
+/** Ambient translate: resolves the locale from the request scope (`ctx.locale`),
+ *  then formats `key` from the registered catalogs. Falls back to the default
+ *  locale, then the key. `t.rich` renders embedded `<tag>`s to ReactNode. Server-
+ *  side (loaders/views/actions); islands take a translator via props instead. */
+declare const t: Translator;
+/** SERVER: the compiled subset of `keys` for `locale` (defaults to the scope
+ *  locale), with per-key fallback to the default locale. Pass it as an island
+ *  prop alongside the locale. */
+declare function pickMessages(keys: string[], locale?: string): CompiledCatalog;
+/** CLIENT: a translator over a one-locale subset (from an island's props). No
+ *  scope, no registry — just the messages it was handed. */
+declare function clientTranslator(messages: CompiledCatalog, locale: string): Translator;
+declare function __resetMessages(): void;
+//#endregion
+export { type CompiledCatalog, type CompiledMessage, MessagesConfig, Translator, __resetMessages, clientTranslator, createTranslator, defineMessages, formatMessage, formatRich, pickMessages, t };

package/dist/index.js

@@ -0,0 +1,97 @@
+import { formatMessage } from "./format.js";
+import { formatRich } from "./rich.js";
+import { currentLocale } from "@junejs/db";
+//#region src/index.ts
+let registry = null;
+/** Register the compiled message catalogs (called once at app boot). A build step
+*  generates this call — with compiled ASTs — from `messages/*.json`. */
+function defineMessages(catalogs, opts) {
+	registry = {
+		catalogs,
+		defaultLocale: opts.defaultLocale
+	};
+}
+const warn = (msg) => {
+	if (process.env.NODE_ENV !== "production") console.warn(`[june i18n] ${msg}`);
+};
+const warnedMissing = /* @__PURE__ */ new Set();
+const warnMissing = (key, locale) => {
+	const id = `${locale}:${key}`;
+	if (warnedMissing.has(id)) return;
+	warnedMissing.add(id);
+	warn(`missing key "${key}" (locale "${locale}")`);
+};
+/** A pure translator bound to a locale + compiled catalogs. The fallback chain is
+*  variant → default locale → the key itself (dev-warns on a miss). Exposed for
+*  tests and for non-ambient use (islands receive a translator built from props). */
+function createTranslator(locale, catalogs, defaultLocale) {
+	const lookup = (key) => catalogs[locale]?.[key] ?? catalogs[defaultLocale]?.[key];
+	const tr = ((key, params) => {
+		const msg = lookup(key);
+		if (msg === void 0) {
+			warnMissing(key, locale);
+			return key;
+		}
+		return formatMessage(msg, locale, params);
+	});
+	tr.rich = (key, params) => {
+		const msg = lookup(key);
+		if (msg === void 0) {
+			warnMissing(key, locale);
+			return key;
+		}
+		return formatRich(msg, locale, params);
+	};
+	return tr;
+}
+function ambientTranslator() {
+	if (!registry) return null;
+	return createTranslator(currentLocale() ?? registry.defaultLocale, registry.catalogs, registry.defaultLocale);
+}
+/** Ambient translate: resolves the locale from the request scope (`ctx.locale`),
+*  then formats `key` from the registered catalogs. Falls back to the default
+*  locale, then the key. `t.rich` renders embedded `<tag>`s to ReactNode. Server-
+*  side (loaders/views/actions); islands take a translator via props instead. */
+const t = Object.assign((key, params) => {
+	const tr = ambientTranslator();
+	if (!tr) {
+		warn(`t("${key}") called before defineMessages()`);
+		return key;
+	}
+	return tr(key, params);
+}, { rich: (key, params) => {
+	const tr = ambientTranslator();
+	if (!tr) {
+		warn(`t.rich("${key}") called before defineMessages()`);
+		return key;
+	}
+	return tr.rich(key, params);
+} });
+/** SERVER: the compiled subset of `keys` for `locale` (defaults to the scope
+*  locale), with per-key fallback to the default locale. Pass it as an island
+*  prop alongside the locale. */
+function pickMessages(keys, locale) {
+	if (!registry) {
+		warn(`pickMessages(${JSON.stringify(keys)}) called before defineMessages()`);
+		return {};
+	}
+	const loc = locale ?? currentLocale() ?? registry.defaultLocale;
+	const out = {};
+	for (const key of keys) {
+		const msg = registry.catalogs[loc]?.[key] ?? registry.catalogs[registry.defaultLocale]?.[key];
+		if (msg) out[key] = msg;
+		else warn(`pickMessages: missing key "${key}"`);
+	}
+	return out;
+}
+/** CLIENT: a translator over a one-locale subset (from an island's props). No
+*  scope, no registry — just the messages it was handed. */
+function clientTranslator(messages, locale) {
+	return createTranslator(locale, { [locale]: messages }, locale);
+}
+function __resetMessages() {
+	registry = null;
+	warnedMissing.clear();
+}
+//#endregion
+export { __resetMessages, clientTranslator, createTranslator, defineMessages, formatMessage, formatRich, pickMessages, t };

package/dist/rich.d.ts

@@ -0,0 +1,9 @@
+import { n as CompiledMessage } from "./format-C_VeKYVf.js";
+import { ReactNode } from "react";
+//#region src/rich.d.ts
+type RichParams = Record<string, unknown>;
+/** Format a compiled message to ReactNode, rendering `<tag>` elements via the
+ *  matching `(chunks) => ReactNode` param. */
+declare function formatRich(msg: CompiledMessage, locale: string, params?: RichParams): ReactNode;
+//#endregion
+export { formatRich };

package/dist/rich.js

@@ -0,0 +1,51 @@
+import { TYPE } from "@formatjs/icu-messageformat-parser";
+import { Fragment, createElement } from "react";
+//#region src/rich.ts
+const num = (locale, n) => new Intl.NumberFormat(locale).format(n);
+const keyed = (nodes) => nodes.length === 1 ? nodes[0] : nodes.map((n, i) => createElement(Fragment, { key: i }, n));
+function evaluate(els, locale, params, pound) {
+	const out = [];
+	for (const el of els) switch (el.type) {
+		case TYPE.literal:
+			out.push(el.value);
+			break;
+		case TYPE.argument:
+			out.push(el.value in params ? params[el.value] : `{${el.value}}`);
+			break;
+		case TYPE.number:
+			out.push(num(locale, Number(params[el.value])));
+			break;
+		case TYPE.pound:
+			out.push(num(locale, pound ?? 0));
+			break;
+		case TYPE.tag: {
+			const fn = params[el.value];
+			const children = keyed(evaluate(el.children, locale, params, pound));
+			out.push(fn ? fn(children) : children);
+			break;
+		}
+		case TYPE.plural: {
+			const n = Number(params[el.value]);
+			const exact = `=${n}`;
+			const cat = el.options[exact] !== void 0 ? exact : new Intl.PluralRules(locale, { type: el.pluralType === "ordinal" ? "ordinal" : "cardinal" }).select(n - el.offset);
+			const opt = el.options[cat] ?? el.options.other;
+			if (opt) out.push(...evaluate(opt.value, locale, params, n - el.offset));
+			break;
+		}
+		case TYPE.select: {
+			const v = String(params[el.value]);
+			const opt = el.options[v] ?? el.options.other;
+			if (opt) out.push(...evaluate(opt.value, locale, params, pound));
+			break;
+		}
+		default: break;
+	}
+	return out;
+}
+/** Format a compiled message to ReactNode, rendering `<tag>` elements via the
+*  matching `(chunks) => ReactNode` param. */
+function formatRich(msg, locale, params) {
+	return keyed(evaluate(msg, locale, params ?? {}));
+}
+//#endregion
+export { formatRich };

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@junejs/i18n",
+  "version": "0.0.29-dev.1",
+  "description": "June — the agent-native React framework. ICU messages (typed t()).",
+  "type": "module",
+  "license": "MIT",
+  "homepage": "https://june.build",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./codegen": {
+      "source": "./src/codegen.ts",
+      "bun": "./src/codegen.ts",
+      "types": "./dist/codegen.d.ts",
+      "default": "./dist/codegen.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "build": "tsdown"
+  },
+  "dependencies": {
+    "@formatjs/icu-messageformat-parser": "^2.7.0",
+    "@junejs/db": ">=0.0.33-dev.1"
+  },
+  "peerDependencies": {
+    "react": "^19.2.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/junebuild/june"
+  }
+}

package/src/codegen.ts

@@ -0,0 +1,105 @@
+// BUILD-time codegen for messages (the @junejs/i18n/codegen entry — node:fs lives
+// here, never in the runtime index). Reads `messages/<locale>.json` (ICU strings),
+// compiles each to its AST, and emits a module that:
+//   - registers the COMPILED catalogs (defineMessages) — the request bundle ships
+//     ASTs + the evaluator, never the parser; and
+//   - exports a TYPED `t` whose key AND params are derived from the ICU AST of the
+//     default locale — the differentiator (`t("cart.items", { n: number })`).
+
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { compileCatalog, deriveParams, type CompiledCatalog, type ParamType } from "./compile";
+
+const TS_TYPE: Record<ParamType, string> = {
+  string: "string",
+  number: "number",
+  Date: "Date",
+  tag: "(chunks: ReactNode) => ReactNode",
+};
+
+/** Read + compile messages → compiled catalogs keyed by locale. Two layouts,
+ *  mergeable: flat `messages/<locale>.json` (root keys) and namespaced
+ *  `messages/<locale>/<ns>.json` (keys prefixed `<ns>.`). The runtime half of the
+ *  codegen, exposed for tests. */
+export function loadMessages(messagesDir: string): {
+  catalogs: Record<string, CompiledCatalog>;
+  raw: Record<string, Record<string, string>>;
+  locales: string[];
+} {
+  const raw: Record<string, Record<string, string>> = {};
+  const readJson = (path: string) => JSON.parse(readFileSync(path, "utf8")) as Record<string, string>;
+  const merge = (locale: string, entries: Record<string, string>) =>
+    Object.assign((raw[locale] ??= {}), entries);
+
+  for (const ent of readdirSync(messagesDir, { withFileTypes: true })) {
+    if (ent.isFile() && ent.name.endsWith(".json")) {
+      merge(ent.name.replace(/\.json$/, ""), readJson(join(messagesDir, ent.name)));
+    } else if (ent.isDirectory()) {
+      const locale = ent.name;
+      const sub = join(messagesDir, locale);
+      for (const f of readdirSync(sub).filter((x) => x.endsWith(".json"))) {
+        const ns = f.replace(/\.json$/, "");
+        const prefixed: Record<string, string> = {};
+        for (const [k, v] of Object.entries(readJson(join(sub, f)))) prefixed[`${ns}.${k}`] = v;
+        merge(locale, prefixed);
+      }
+    }
+  }
+
+  const catalogs: Record<string, CompiledCatalog> = {};
+  for (const [locale, entries] of Object.entries(raw)) catalogs[locale] = compileCatalog(entries);
+  return { catalogs, raw, locales: Object.keys(catalogs) };
+}
+
+// The TS shape of one message's params (from its AST), or Record<string, never>.
+function paramsType(catalog: CompiledCatalog, key: string): string {
+  const params = deriveParams(catalog[key]!);
+  const names = Object.keys(params);
+  // Record<never, never> (not Record<string, never>!) so `keyof` is `never` — the
+  // signal that lets the typed `t` take NO second arg for a param-less message.
+  if (names.length === 0) return "Record<never, never>";
+  return `{ ${names.map((n) => `${JSON.stringify(n)}: ${TS_TYPE[params[n]!]}`).join("; ")} }`;
+}
+
+/** Generate the frozen `_messages.ts` module text from `messages/`. The default
+ *  locale is the type source of truth (its keys define `Messages`). */
+export function generateMessagesModule(
+  messagesDir: string,
+  opts: { defaultLocale: string },
+): { code: string; locales: string[] } {
+  const { catalogs, locales } = loadMessages(messagesDir);
+  const defaultCatalog = catalogs[opts.defaultLocale] ?? {};
+  const entries = Object.keys(defaultCatalog)
+    .sort()
+    .map((key) => `  ${JSON.stringify(key)}: ${paramsType(defaultCatalog, key)};`)
+    .join("\n");
+
+  const code =
+    "// AUTO-GENERATED by `june gen` — edit messages/*.json, not this file.\n" +
+    'import { defineMessages, t as rawT, type CompiledCatalog } from "@junejs/i18n";\n' +
+    'import type { ReactNode } from "react";\n\n' +
+    `const CATALOGS: Record<string, CompiledCatalog> = ${JSON.stringify(catalogs)};\n\n` +
+    `defineMessages(CATALOGS, { defaultLocale: ${JSON.stringify(opts.defaultLocale)} });\n\n` +
+    "// The message keys + their params, derived from the default locale's ICU ASTs.\n" +
+    `export type Messages = {\n${entries}\n};\n\n` +
+    "// A key with a <tag> param has a function param → it must go through t.rich.\n" +
+    "type HasTag<P> = true extends\n" +
+    "  { [K in keyof P]: P[K] extends (...a: never[]) => unknown ? true : never }[keyof P]\n" +
+    "  ? true : false;\n" +
+    "type PlainKey = { [K in keyof Messages]: HasTag<Messages[K]> extends true ? never : K }[keyof Messages];\n\n" +
+    "// Typed translate: key AND params are checked against messages/*.json. A no-\n" +
+    "// param message takes no second arg; a wrong/missing param or unknown key is a\n" +
+    "// compile error. t.rich renders <tag>s to ReactNode (tag keys require it).\n" +
+    "export const t = rawT as unknown as {\n" +
+    "  <K extends PlainKey>(\n" +
+    "    key: K,\n" +
+    "    ...args: keyof Messages[K] extends never ? [] : [params: Messages[K]]\n" +
+    "  ): string;\n" +
+    "  rich: <K extends keyof Messages>(\n" +
+    "    key: K,\n" +
+    "    ...args: keyof Messages[K] extends never ? [] : [params: Messages[K]]\n" +
+    "  ) => ReactNode;\n" +
+    "};\n";
+  return { code, locales };
+}

package/src/compile.ts

@@ -0,0 +1,64 @@
+// BUILD-time ICU compilation. The @formatjs PARSER lives HERE only (ICU string →
+// AST) — never imported by the runtime (index.ts → format.ts). What ships is the
+// AST + the format.ts evaluator. The same AST also DERIVES the param types (the
+// edge: `t("cart.items", { n: number })` types key AND params).
+
+import { parse, TYPE } from "@formatjs/icu-messageformat-parser";
+
+import type { CompiledCatalog, CompiledMessage } from "./format";
+
+export type { CompiledCatalog, CompiledMessage } from "./format";
+
+/** Parse one ICU string to its AST. */
+export function parseMessage(icu: string): CompiledMessage {
+  return parse(icu);
+}
+
+/** Parse a whole `{ key: icuString }` catalog to ASTs. */
+export function compileCatalog(raw: Record<string, string>): CompiledCatalog {
+  const out: CompiledCatalog = {};
+  for (const [key, icu] of Object.entries(raw)) out[key] = parseMessage(icu);
+  return out;
+}
+
+// "tag" = a `<x>…</x>` rich element → a (chunks: ReactNode) => ReactNode param,
+// rendered by t.rich (not the plain string t).
+export type ParamType = "string" | "number" | "Date" | "tag";
+
+/** The params a message needs, derived from its AST. Plural/number args are
+ *  numbers, date/time are Dates, plain `{x}` and select keys are strings. This is
+ *  what the codegen turns into `t`'s typed signature. */
+export function deriveParams(
+  msg: CompiledMessage,
+  into: Record<string, ParamType> = {},
+): Record<string, ParamType> {
+  for (const el of msg) {
+    switch (el.type) {
+      case TYPE.argument:
+        into[el.value] ??= "string";
+        break;
+      case TYPE.number:
+        into[el.value] = "number";
+        break;
+      case TYPE.date:
+      case TYPE.time:
+        into[el.value] = "Date";
+        break;
+      case TYPE.plural:
+        into[el.value] = "number";
+        for (const o of Object.values(el.options)) deriveParams(o.value, into);
+        break;
+      case TYPE.select:
+        into[el.value] ??= "string";
+        for (const o of Object.values(el.options)) deriveParams(o.value, into);
+        break;
+      case TYPE.tag:
+        into[el.value] = "tag";
+        deriveParams(el.children, into);
+        break;
+      default:
+        break;
+    }
+  }
+  return into;
+}

package/src/format.ts

@@ -0,0 +1,70 @@
+// RUNTIME message formatting — the AST evaluator. It imports only the `TYPE` enum
+// from @formatjs (the parser `parse` is NOT reachable from here), so the runtime
+// bundle ships the evaluator + Intl, never the ICU string parser. The build path
+// (compile.ts) owns parsing; this owns evaluating what the build produced.
+
+import { TYPE, type MessageFormatElement } from "@formatjs/icu-messageformat-parser";
+
+/** A compiled message: the parsed ICU AST (what defineMessages ships). */
+export type CompiledMessage = MessageFormatElement[];
+export type CompiledCatalog = Record<string, CompiledMessage>;
+
+const num = (locale: string, n: number) => new Intl.NumberFormat(locale).format(n);
+
+// Walk the AST. `pound` is the active plural's number (the `#`).
+function evaluate(
+  els: CompiledMessage,
+  locale: string,
+  params: Record<string, unknown>,
+  pound?: number,
+): string {
+  let out = "";
+  for (const el of els) {
+    switch (el.type) {
+      case TYPE.literal:
+        out += el.value;
+        break;
+      case TYPE.argument:
+        out += el.value in params ? String(params[el.value]) : `{${el.value}}`;
+        break;
+      case TYPE.number:
+        out += num(locale, Number(params[el.value]));
+        break;
+      case TYPE.pound:
+        out += num(locale, pound ?? 0);
+        break;
+      case TYPE.plural: {
+        const n = Number(params[el.value]);
+        const exact = `=${n}`;
+        const cat =
+          el.options[exact] !== undefined
+            ? exact
+            : new Intl.PluralRules(locale, {
+                type: el.pluralType === "ordinal" ? "ordinal" : "cardinal",
+              }).select(n - el.offset);
+        const opt = el.options[cat] ?? el.options.other;
+        if (opt) out += evaluate(opt.value, locale, params, n - el.offset);
+        break;
+      }
+      case TYPE.select: {
+        const v = String(params[el.value]);
+        const opt = el.options[v] ?? el.options.other;
+        if (opt) out += evaluate(opt.value, locale, params, pound);
+        break;
+      }
+      default:
+        // date/time/tag: handled by t.rich / later; ignored in the plain path.
+        break;
+    }
+  }
+  return out;
+}
+
+/** Format a compiled message in `locale` with `params`. */
+export function formatMessage(
+  msg: CompiledMessage,
+  locale: string,
+  params?: Record<string, unknown>,
+): string {
+  return evaluate(msg, locale, params ?? {});
+}

package/src/index.ts

@@ -0,0 +1,168 @@
+// @junejs/i18n — ICU messages, the OPT-IN Layer 2 of June's i18n (routing is the
+// in-box Layer 1; see docs/i18n.md §Packaging). Ambient `t`: read the current
+// request locale off the scope (no ctx threading) and format the catalog message.
+//
+//   import { defineMessages, compileCatalog, t } from "@junejs/i18n";
+//   defineMessages(
+//     { en: compileCatalog({ hi: "Hello, {name}!" }),
+//       de: compileCatalog({ hi: "Hallo, {name}!" }) },
+//     { defaultLocale: "en" },
+//   );
+//   t("hi", { name: "Ada" });   // server: reads ctx.locale via the request scope
+//
+// The catalogs ship COMPILED (parsed ASTs) — the @formatjs parser runs at build,
+// never in the request path (see compile.ts). A build step will generate the
+// defineMessages call + the typed `t` signature from `messages/*.json` (3.2b).
+
+// currentLocale is the generic request-scope read (the host sets it after locale
+// resolution); the core pipeline never imports this package — the locale crosses
+// via the scope, not a direct dependency.
+import type { ReactNode } from "react";
+
+import { currentLocale } from "@junejs/db";
+
+// Runtime only — format.ts/rich.ts do NOT reach the @formatjs parser (that's
+// build-only in compile.ts / codegen.ts), so the request bundle never ships one.
+import { formatMessage, type CompiledCatalog, type CompiledMessage } from "./format";
+import { formatRich } from "./rich";
+
+export { formatMessage, type CompiledCatalog, type CompiledMessage } from "./format";
+export { formatRich } from "./rich";
+
+/** A translator: callable for a plain string, `.rich` for embedded components. */
+export type Translator = {
+  (key: string, params?: Record<string, unknown>): string;
+  rich(key: string, params?: Record<string, unknown>): ReactNode;
+};
+
+export type MessagesConfig = {
+  catalogs: Record<string, CompiledCatalog>;
+  defaultLocale: string;
+};
+
+let registry: MessagesConfig | null = null;
+
+/** Register the compiled message catalogs (called once at app boot). A build step
+ *  generates this call — with compiled ASTs — from `messages/*.json`. */
+export function defineMessages(
+  catalogs: Record<string, CompiledCatalog>,
+  opts: { defaultLocale: string },
+): void {
+  registry = { catalogs, defaultLocale: opts.defaultLocale };
+}
+
+const warn = (msg: string) => {
+  // Tree-shaken out of production bundles (NODE_ENV baked at build).
+  if (process.env.NODE_ENV !== "production") console.warn(`[june i18n] ${msg}`);
+};
+
+// Missing-key warnings dedupe: a key missing on every render would otherwise spam
+// the dev console once per request — warn each (locale, key) once.
+const warnedMissing = new Set<string>();
+const warnMissing = (key: string, locale: string) => {
+  const id = `${locale}:${key}`;
+  if (warnedMissing.has(id)) return;
+  warnedMissing.add(id);
+  warn(`missing key "${key}" (locale "${locale}")`);
+};
+
+/** A pure translator bound to a locale + compiled catalogs. The fallback chain is
+ *  variant → default locale → the key itself (dev-warns on a miss). Exposed for
+ *  tests and for non-ambient use (islands receive a translator built from props). */
+export function createTranslator(
+  locale: string,
+  catalogs: Record<string, CompiledCatalog>,
+  defaultLocale: string,
+): Translator {
+  const lookup = (key: string): CompiledMessage | undefined =>
+    catalogs[locale]?.[key] ?? catalogs[defaultLocale]?.[key];
+  const tr = ((key, params) => {
+    const msg = lookup(key);
+    if (msg === undefined) {
+      warnMissing(key, locale);
+      return key;
+    }
+    return formatMessage(msg, locale, params);
+  }) as Translator;
+  tr.rich = (key, params) => {
+    const msg = lookup(key);
+    if (msg === undefined) {
+      warnMissing(key, locale);
+      return key; // a string ReactNode
+    }
+    return formatRich(msg, locale, params);
+  };
+  return tr;
+}
+
+function ambientTranslator(): Translator | null {
+  if (!registry) return null;
+  return createTranslator(
+    currentLocale() ?? registry.defaultLocale,
+    registry.catalogs,
+    registry.defaultLocale,
+  );
+}
+
+/** Ambient translate: resolves the locale from the request scope (`ctx.locale`),
+ *  then formats `key` from the registered catalogs. Falls back to the default
+ *  locale, then the key. `t.rich` renders embedded `<tag>`s to ReactNode. Server-
+ *  side (loaders/views/actions); islands take a translator via props instead. */
+export const t: Translator = Object.assign(
+  (key: string, params?: Record<string, unknown>): string => {
+    const tr = ambientTranslator();
+    if (!tr) {
+      warn(`t("${key}") called before defineMessages()`);
+      return key;
+    }
+    return tr(key, params);
+  },
+  {
+    rich: (key: string, params?: Record<string, unknown>): ReactNode => {
+      const tr = ambientTranslator();
+      if (!tr) {
+        warn(`t.rich("${key}") called before defineMessages()`);
+        return key;
+      }
+      return tr.rich(key, params);
+    },
+  },
+);
+
+// --- islands (client code-split) ------------------------------------------
+// A page renders with ambient `t` server-side and ships ZERO message catalog to
+// the browser (the HTML carries the formatted strings). An ISLAND can't read the
+// scope on the client, so it ships ONLY the keys it uses — `pickMessages` (server,
+// builds the subset for this request's locale) into the island's props, and
+// `clientTranslator` (client, formats that subset). The parser never ships; only
+// the tiny evaluator (format.ts/rich.ts) + the island's own messages do.
+
+/** SERVER: the compiled subset of `keys` for `locale` (defaults to the scope
+ *  locale), with per-key fallback to the default locale. Pass it as an island
+ *  prop alongside the locale. */
+export function pickMessages(keys: string[], locale?: string): CompiledCatalog {
+  if (!registry) {
+    warn(`pickMessages(${JSON.stringify(keys)}) called before defineMessages()`);
+    return {};
+  }
+  const loc = locale ?? currentLocale() ?? registry.defaultLocale;
+  const out: CompiledCatalog = {};
+  for (const key of keys) {
+    const msg = registry.catalogs[loc]?.[key] ?? registry.catalogs[registry.defaultLocale]?.[key];
+    if (msg) out[key] = msg;
+    else warn(`pickMessages: missing key "${key}"`);
+  }
+  return out;
+}
+
+/** CLIENT: a translator over a one-locale subset (from an island's props). No
+ *  scope, no registry — just the messages it was handed. */
+export function clientTranslator(messages: CompiledCatalog, locale: string): Translator {
+  return createTranslator(locale, { [locale]: messages }, locale);
+}
+
+// Test-only: reset the module registry + dedup state between cases.
+export function __resetMessages(): void {
+  registry = null;
+  warnedMissing.clear();
+}

package/src/rich.ts

@@ -0,0 +1,82 @@
+// Rich formatting (t.rich): the AST evaluator that returns ReactNode, so a
+// message can embed components — `"Read the <link>docs</link>"` with
+// `{ link: (chunks) => <a href="/docs">{chunks}</a> }`. Like format.ts it imports
+// only TYPE (no parser); it additionally pulls React (a peer dep) for the tags.
+
+import { createElement, Fragment, type ReactNode } from "react";
+
+import { TYPE } from "@formatjs/icu-messageformat-parser";
+
+import type { CompiledMessage } from "./format";
+
+type RichParams = Record<string, unknown>;
+
+const num = (locale: string, n: number) => new Intl.NumberFormat(locale).format(n);
+
+// Key each node so an array of mixed strings/elements renders without React's
+// "missing key" warning.
+const keyed = (nodes: ReactNode[]): ReactNode =>
+  nodes.length === 1 ? nodes[0] : nodes.map((n, i) => createElement(Fragment, { key: i }, n));
+
+function evaluate(
+  els: CompiledMessage,
+  locale: string,
+  params: RichParams,
+  pound?: number,
+): ReactNode[] {
+  const out: ReactNode[] = [];
+  for (const el of els) {
+    switch (el.type) {
+      case TYPE.literal:
+        out.push(el.value);
+        break;
+      case TYPE.argument:
+        out.push(el.value in params ? (params[el.value] as ReactNode) : `{${el.value}}`);
+        break;
+      case TYPE.number:
+        out.push(num(locale, Number(params[el.value])));
+        break;
+      case TYPE.pound:
+        out.push(num(locale, pound ?? 0));
+        break;
+      case TYPE.tag: {
+        const fn = params[el.value] as ((chunks: ReactNode) => ReactNode) | undefined;
+        const children = keyed(evaluate(el.children, locale, params, pound));
+        out.push(fn ? fn(children) : children);
+        break;
+      }
+      case TYPE.plural: {
+        const n = Number(params[el.value]);
+        const exact = `=${n}`;
+        const cat =
+          el.options[exact] !== undefined
+            ? exact
+            : new Intl.PluralRules(locale, {
+                type: el.pluralType === "ordinal" ? "ordinal" : "cardinal",
+              }).select(n - el.offset);
+        const opt = el.options[cat] ?? el.options.other;
+        if (opt) out.push(...evaluate(opt.value, locale, params, n - el.offset));
+        break;
+      }
+      case TYPE.select: {
+        const v = String(params[el.value]);
+        const opt = el.options[v] ?? el.options.other;
+        if (opt) out.push(...evaluate(opt.value, locale, params, pound));
+        break;
+      }
+      default:
+        break;
+    }
+  }
+  return out;
+}
+
+/** Format a compiled message to ReactNode, rendering `<tag>` elements via the
+ *  matching `(chunks) => ReactNode` param. */
+export function formatRich(
+  msg: CompiledMessage,
+  locale: string,
+  params?: RichParams,
+): ReactNode {
+  return keyed(evaluate(msg, locale, params ?? {}));
+}