@ultimat3/i18n 27.3.0 → 27.5.0

package/README.md

@@ -99,6 +99,15 @@ catalog is a fallback chain, it reads as `isMiss === false`, and `assertCatalogs
 see it because `CatalogSet.catalogs` carries app strings only. Translate the framework keys your
 app renders into your own catalog — that is the one path, and it is the same merge an override is.
 
+## A catalog slice for an island
+
+A translator is a function and cannot be an island's prop. `catalogSubset(t, keys)` resolves the
+templates `keys` name — every plural variant included — into `{ locale, catalog }`, plain JSON;
+the island builds `subsetTranslator(subset)` over it: the same lookup, interpolation, CLDR plural
+pick and loud `⟦key⟧` miss as the server's. Both are on `@ultimat3/i18n/subset`, an entry that
+installs no framework catalog (the barrel does), so an island chunk can import it.
+`@ultimat3/ui`'s `uiCatalog(t)` is the design system's own slice.
+
 ## Reading an app's declared locales (tooling)
 
 `@ultimat3/i18n/app-catalogs` — server-only, its own entry so no island bundle carries it:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/i18n",
-  "version": "27.3.0",
+  "version": "27.5.0",
   "description": "Dependency-free translator, catalog flattening, locale negotiation and loud missing-key rendering",
   "license": "MIT",
   "type": "module",
@@ -19,7 +19,8 @@
   },
   "exports": {
     ".": "./src/index.ts",
-    "./app-catalogs": "./src/app-catalogs.ts"
+    "./app-catalogs": "./src/app-catalogs.ts",
+    "./subset": "./src/subset.ts"
   },
   "files": [
     "src",
@@ -37,6 +38,6 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "27.3.0"
+    "@ultimat3/core": "27.5.0"
   }
 }

package/src/index.ts

@@ -109,6 +109,12 @@ export {
   type CatalogRegistrationGap,
   catalogRegistrationGaps,
 } from './registration';
+export {
+  type CatalogSubset,
+  catalogSubset,
+  type RawTranslator,
+  subsetTranslator,
+} from './subset';
 export {
   catalogTranslator,
   isMiss,

package/src/subset.ts

@@ -0,0 +1,48 @@
+// A slice of a catalog that can cross into an island. A translator is a function and cannot be an
+// island's prop, so the server resolves the raw templates the island will read — plural variants
+// included — and the island builds a full translator over them: the same lookup, interpolation
+// and loud `⟦key⟧` miss as the server's. Its own entry (`@ultimat3/i18n/subset`): the barrel
+// installs the framework catalog at import, and an island chunk must not carry it.
+
+import type { Catalog } from './catalog';
+import { pluralVariantsOf } from './interpolate';
+import type { Locale } from './locales';
+import { catalogTranslator, type Translator } from './translator';
+
+/**
+ * What an island receives: plain JSON — its locale and the templates it may render. A type alias,
+ * not an interface, so it is assignable to the JSON an island's props are checked against.
+ */
+export type CatalogSubset = {
+  readonly locale: Locale;
+  readonly catalog: Readonly<Record<string, string>>;
+};
+
+/** The two members of a translator a subset is read through — any app's typed `t` has them. */
+export interface RawTranslator {
+  raw(key: string): string | undefined;
+  readonly locale: Locale;
+}
+
+/**
+ * The templates `keys` name in `t`'s locale, each with every plural variant the catalog holds, so
+ * `t(key, { count })` in the island picks the form the server would. A key the catalog lacks is
+ * left out, and renders `⟦key⟧` in the island exactly as it would on the server.
+ */
+export function catalogSubset(t: RawTranslator, keys: readonly string[]): CatalogSubset {
+  const catalog: Record<string, string> = Object.create(null) as Record<string, string>;
+  for (const key of keys) {
+    for (const name of [key, ...pluralVariantsOf(key)]) {
+      const template = t.raw(name);
+      if (template !== undefined) catalog[name] = template;
+    }
+  }
+  return { locale: t.locale, catalog };
+}
+
+/** The island half: a translator over the subset the server sent. */
+export function subsetTranslator(subset: CatalogSubset): Translator {
+  // Null-prototyped again: the subset arrived as parsed JSON, where `__proto__` is an own key.
+  const catalog: Catalog = Object.assign(Object.create(null) as Catalog, subset.catalog);
+  return catalogTranslator(catalog, subset.locale);
+}