@ultimat3/i18n 24.0.0 → 25.0.0

package/CLAUDE.md

@@ -14,6 +14,7 @@ Imported by every package that renders a string.
 | `locales.ts` | supported set, normalize, negotiate, RTL. No catalogs. |
 | `context.ts` | request locale via ALS, the registry + the base layer under it, the ambient `t` and `useI18n`. |
 | `framework.ts` | the framework's own strings, installed as the base layer at module scope. |
+| `app-catalogs.ts` | an app's declared locales, read by importing its catalog module — `loadAppCatalogs` (`undefined` when undeclared) and `appLocaleSet` (`UNDECLARED_LOCALES` then). The ONE reader: a CLI step never reads `localeConfig()`/`routedLocales()` after `loadApp`; it reads `LoadedApp.locales`. Tooling only: the `./app-catalogs` entry, never `index.ts` (it is in every island). |
 | `registration.ts` | are the catalogs an app SHIPS in the registry it READS? No file access. |
 | `extract.ts` | static scan + audit for `x verify`. |
 | `catalogs/en.json` | data, not code. |
@@ -35,7 +36,7 @@ Imported by every package that renders a string.
   puts it back. It was `registerFrameworkCatalog()`, whose ONE caller was `defineCatalogs`, so an
   app whose catalog module nothing imported served `⟦errors.notFound.title⟧` on its 404 page and
   `⟦ui.*⟧` in every design-system control, with `x verify` green (issue #249). Under
-  `FRAMEWORK_CATALOG_LOCALE` (`en`) **only**: it ran per locale until 2026-08, so an `es`-only app
+  core's `DEFAULT_LOCALE` (`en`) **only**: it ran per locale until 2026-08, so an `es`-only app
   served `Page not found` with `isMiss` reading FALSE — the fallback chain the line above refuses,
   wearing registration as a disguise. A non-`en` app translates the framework keys it renders into
   its own catalog.
@@ -105,7 +106,7 @@ Imported by every package that renders a string.
   `@ultimat3/mail` take a bare `Translator`. `has()` and `raw()` stay `string` — they are probes.
 - Nothing here formats a number, date or money. That is `@ultimat3/money` / `@ultimat3/time`.
 - **The ambient locale IS `Ctx.locale`**, core's own declared field — this package writes no context
-  field of its own and publishes no writer. `createContext({ locale })` and
+  field of its own and publishes no writer. `ctxOf({ locale })` and
   `withChildContext({ locale })` are the only ways in, `currentLocale()` the only way out.
   `attachLocale`/`localeOf` existed until 1.3.0 with zero callers; `@ultimat3/time` had the same
   pair over a field name (`ctx['timeZone']`) that disagreed with core's `tz`, which is what made

package/README.md

@@ -99,6 +99,22 @@ 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.
 
+## Reading an app's declared locales (tooling)
+
+`@ultimat3/i18n/app-catalogs` — server-only, its own entry so no island bundle carries it:
+
+| Export | What |
+|---|---|
+| `APP_CATALOGS_PATH` | `'packages/i18n/src/index.ts'`, where `x new` writes the app's `defineCatalogs()` |
+| `loadAppCatalogs(root)` | imports that module and answers `{ locales, defaultLocale }` (default first), or `undefined` when no `defineCatalogs()` was declared — never the ambient `localeConfig()` read blind. An exported set answers for itself, whatever the locale config says by then. A module that throws rejects with its own error |
+| `appLocaleSet(root)` | the same answer, with `UNDECLARED_LOCALES` for an app that declared nothing — what every consumer that needs *a* locale asks |
+| `UNDECLARED_LOCALES` | `{ locales: ['en'], defaultLocale: 'en' }`, frozen: the one answer for an app with no catalogs, so the PWA manifest, the service worker, the prerender and every `x` command agree |
+| `AppLocaleSet` | the type of both answers |
+
+The one reader the CLI (`loadApp`'s `locales`, the pwa manifest and service worker, the static export, `x shot`, `x g`, `x i18n`) and `@ultimat3/testing`'s e2e preload share. `@ultimat3/testing` asks `loadAppCatalogs` deliberately: an app that declared nothing pins no browser language rather than a guessed one.
+
+`DEFAULT_LOCALE`, `directionOf` and `isRtl` are `@ultimat3/core`'s since 25.0.0 — import them from there. The barrel still re-exports the three until `@ultimat3/mail` and `@ultimat3/ui` move (marked `PENDING` in `src/index.ts`); `Direction` stays a type re-export, because `LocaleResolution.direction` names it.
+
 ## Enforcement
 
 `extractKeys()` scans source for `t('...')` calls; `auditCatalogs()` reports keys used,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/i18n",
-  "version": "24.0.0",
+  "version": "25.0.0",
   "description": "Dependency-free translator, catalog flattening, locale negotiation and loud missing-key rendering",
   "license": "MIT",
   "type": "module",
@@ -18,7 +18,8 @@
     "provenance": true
   },
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./app-catalogs": "./src/app-catalogs.ts"
   },
   "files": [
     "src",
@@ -29,13 +30,13 @@
     "LICENSE"
   ],
   "engines": {
-    "bun": ">=1.4.0"
+    "bun": ">=1.4.2"
   },
   "scripts": {
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "24.0.0"
+    "@ultimat3/core": "25.0.0"
   }
 }

package/src/app-catalogs.ts

@@ -0,0 +1,77 @@
+// The ONE reader of an app's declared locales: its catalog module's `defineCatalogs()`, imported
+// and read back. The CLI (manifest, worker, prerender, `x shot`, `x g`, `x i18n`) and the e2e
+// preload each kept a copy, and the copies disagreed. Server-only, so its own entry
+// (`@ultimat3/i18n/app-catalogs`): `index.ts` is in every island.
+
+// why: Bun exposes no path-join primitive; the catalog module is joined to the app root.
+import { join } from 'node:path';
+import { DEFAULT_LOCALE } from '@ultimat3/core';
+import { localeConfig, routedLocales } from './context';
+import type { CatalogSet, CatalogSources } from './define-catalogs';
+import { catalogDeclarationCount, isDeclaredCatalogSet } from './define-catalogs';
+
+/** Where an app declares its catalogs — `x new` writes it, and its `defineCatalogs()` runs there. */
+export const APP_CATALOGS_PATH = 'packages/i18n/src/index.ts';
+
+export interface AppLocaleSet {
+  /** Every locale the app routes, its default first. */
+  readonly locales: readonly string[];
+  readonly defaultLocale: string;
+}
+
+/**
+ * `root`'s declared locales, or `undefined` when no declaration ran: no catalog module, or one
+ * that calls no `defineCatalogs()`. Never `localeConfig()` read blind — it ALWAYS answers a
+ * fallback, so a module declaring nothing would inherit whatever an earlier import declared, and a
+ * caller would pin a language no visitor sees. Declared means this import ran the call, or the
+ * module exports the set one returned (a cached module evaluates once: the boot scan imported it).
+ *
+ * A module that will not import throws its own error: each caller decides whether that is a
+ * refusal or "nothing declared".
+ */
+export async function loadAppCatalogs(root: string): Promise<AppLocaleSet | undefined> {
+  const path = join(root, APP_CATALOGS_PATH);
+  if (!(await Bun.file(path).exists())) return undefined;
+  const before = catalogDeclarationCount();
+  const module = (await import(path)) as Readonly<Record<string, unknown>>;
+  const ran = catalogDeclarationCount() !== before;
+  // The exported set FIRST: it is the declaration itself, where the locale config is shared,
+  // process-wide state a later `configureLocales()` or a reset may have moved since the module ran
+  // — and a cached module never runs its `defineCatalogs()` again to put it back.
+  const exported = Object.values(module).find(isDeclaredCatalogSet) as DeclaredSet | undefined;
+  if (exported !== undefined) return setOf(exported.default, exported.locales);
+  if (!ran) return undefined;
+  // Declared by this very import and not exported: the config is what that call just wrote.
+  const defaultLocale = localeConfig().fallback;
+  if (defaultLocale === '') return undefined;
+  return { locales: [...routedLocales()], defaultLocale };
+}
+
+/** What `isDeclaredCatalogSet` vouches for: a `CatalogSet` some `defineCatalogs()` returned. */
+type DeclaredSet = Pick<CatalogSet<CatalogSources>, 'default' | 'locales'>;
+
+/** Default first, as `routedLocales()` orders them — every consumer enumerates in this order. */
+const setOf = (defaultLocale: string, locales: readonly string[]): AppLocaleSet => ({
+  locales: [defaultLocale, ...locales.filter((locale) => locale !== defaultLocale)],
+  defaultLocale,
+});
+
+/**
+ * The answer for an app that declares no catalogs: the framework default, alone. ONE value, so the
+ * PWA manifest, the service worker, the prerender and every `x` command name the same language for
+ * such an app — before it, the manifest said `en` off its own literal while the worker and the
+ * prerender read `localeConfig()` blind and could inherit an earlier import's declaration.
+ */
+export const UNDECLARED_LOCALES: AppLocaleSet = Object.freeze({
+  locales: Object.freeze([DEFAULT_LOCALE]),
+  defaultLocale: DEFAULT_LOCALE,
+});
+
+/**
+ * `root`'s locales whether it declared any or not: `loadAppCatalogs`, else `UNDECLARED_LOCALES`.
+ * The caller that must tell the two apart (`x g`, which writes no catalog for an app without one)
+ * asks `loadAppCatalogs`; every other caller asks this. A module that will not import still throws.
+ */
+export async function appLocaleSet(root: string): Promise<AppLocaleSet> {
+  return (await loadAppCatalogs(root)) ?? UNDECLARED_LOCALES;
+}

package/src/catalogs/en.json

@@ -65,7 +65,9 @@
       "action": "Try again"
     },
     "page": {
-      "builtWith": "Built with Ultimate"
+      "builtWith": "Built with Ultimate",
+      "code": "code",
+      "request": "request"
     }
   },
   "validation": {
@@ -183,7 +185,18 @@
       "name": "Admin"
     },
     "dashboard": {
-      "title": "Dashboard"
+      "title": "Dashboard",
+      "records": {
+        "title": "Records",
+        "label": "Records per resource",
+        "resource": "Resource",
+        "total": "records in all"
+      },
+      "access": {
+        "title": "Access",
+        "allowed": "{allowed} of {total} allowed",
+        "open": "Open the list"
+      }
     },
     "denied": {
       "body": "This account is missing {permission} ({reason})."
@@ -487,7 +500,27 @@
       },
       "timeline": {
         "title": "Timeline",
-        "question": "where did the time go in this request?"
+        "question": "where did the time go in this request?",
+        "requests": "Recent requests",
+        "spans": "Spans, on the request's own clock",
+        "byKind": "Time by kind",
+        "ms": "{ms} ms",
+        "empty": "No request has been traced yet — open a page of the app, then reload this tab.",
+        "kind": {
+          "http": "http",
+          "render": "render",
+          "action": "action",
+          "policy": "policy",
+          "sql": "sql",
+          "cache": "cache",
+          "job": "job"
+        },
+        "nPlusOne": {
+          "title": "Repeated statements",
+          "fix": "fix:",
+          "clean": "no statement repeated past the detector's threshold in this request",
+          "unwired": "no N+1 detector is attached to this process — x dev wires one"
+        }
       },
       "live": {
         "title": "Live",
@@ -495,7 +528,19 @@
       },
       "jobs": {
         "title": "Jobs",
-        "question": "is the queue moving, and which step failed?"
+        "question": "is the queue moving, and which step failed?",
+        "chart": {
+          "label": "Recent runs by state",
+          "total": "recent runs",
+          "state": "State",
+          "runs": "Runs"
+        },
+        "state": {
+          "ok": "done",
+          "running": "running",
+          "failed": "failed",
+          "dead": "dead"
+        }
       },
       "db": {
         "title": "DB",

package/src/context.ts

@@ -7,20 +7,15 @@ import {
   assertLocale,
   cachedFormatter,
   canonicalLocale,
+  DEFAULT_LOCALE,
+  type Direction,
+  directionOf,
   readCookie,
   tryUseContext,
 } from '@ultimat3/core';
 import { type Catalog, mergeCatalogs } from './catalog';
-import {
-  DEFAULT_LOCALE,
-  type Direction,
-  directionOf,
-  type Locale,
-  negotiateLocale,
-  normalizeLocale,
-  SUPPORTED_LOCALES,
-} from './locales';
-import { createTranslator, type TranslateVars, type Translator } from './translator';
+import { type Locale, negotiateLocale, normalizeLocale, SUPPORTED_LOCALES } from './locales';
+import { catalogTranslator, type TranslateVars, type Translator } from './translator';
 
 /** The cookie an explicit language switcher writes. */
 export const LOCALE_COOKIE = 'x_locale';
@@ -162,7 +157,7 @@ export function localeCookieOf(cookieHeader?: string | null): string | undefined
 /**
  * Ambient locale for the in-flight request; the configured fallback outside one.
  *
- * The store is **`Ctx.locale`**, core's own declared field, so `createContext({ locale })` and
+ * The store is **`Ctx.locale`**, core's own declared field, so `ctxOf({ locale })` and
  * `withChildContext({ locale })` are the only writers and this package publishes no second one.
  * `@ultimat3/time`'s `currentTimeZone()` is the same shape over `Ctx.tz`, deliberately.
  */
@@ -298,10 +293,10 @@ export function catalogFor(locale: Locale): Catalog {
 export function translatorFor<TCatalog = Catalog>(locale: Locale): Translator<TCatalog> {
   const key = translatorKey(locale);
   // Resolved BEFORE the memo, so what lands under `key` is the catalog that key stands for and
-  // not whichever spelling asked first. The caller's own tag reaches `createTranslator` either
+  // not whichever spelling asked first. The caller's own tag reaches `catalogTranslator` either
   // way — the catalog is chosen by locale, the formatting by what the caller actually sent.
   const translator = cachedFormatter(translators, key, () =>
-    createTranslator(catalogFor(registeredUnder(locale, key) ?? locale), locale),
+    catalogTranslator(catalogFor(registeredUnder(locale, key) ?? locale), locale),
   );
   // One cast, one place. `TCatalog` narrows the key parameter and nothing else, so the memoized
   // object already is the right value — the registry cannot be keyed by an app's catalog type.

package/src/define-catalogs.ts

@@ -38,6 +38,18 @@ let declarations = 0;
  */
 export const catalogDeclarationCount = (): number => declarations;
 
+/**
+ * Every set `defineCatalogs()` returned in this process — held weakly, so a set nothing references
+ * is never kept alive by being asked about. `app-catalogs.ts` asks it of a module's exports: a
+ * module evaluates once, so on its second `import()` the count above has not moved, and the set it
+ * exports is the one fact left that it declared.
+ */
+const declaredSets = new WeakSet<object>();
+
+/** Whether `value` is a set some `defineCatalogs()` call returned — never a lookalike object. */
+export const isDeclaredCatalogSet = (value: unknown): boolean =>
+  typeof value === 'object' && value !== null && declaredSets.has(value);
+
 export function defineCatalogs<TLocales extends CatalogSources>(
   input: DefineCatalogsInput<TLocales>,
 ): CatalogSet<TLocales> {
@@ -62,10 +74,12 @@ export function defineCatalogs<TLocales extends CatalogSources>(
   declarations += 1;
 
   const catalogs = Object.fromEntries(loaded) as Readonly<Record<keyof TLocales & string, Catalog>>;
-  return {
+  const set: CatalogSet<TLocales> = {
     default: input.default,
     locales,
     catalogs,
     keys: () => catalogKeys(mergeCatalogs(...loaded.map(([, catalog]) => catalog))),
   };
+  declaredSets.add(set);
+  return set;
 }

package/src/framework.ts

@@ -3,10 +3,10 @@
  * Under every app catalog, so an app overrides any framework key and forgets none.
  */
 
+import { DEFAULT_LOCALE } from '@ultimat3/core';
 import { type Catalog, loadCatalog } from './catalog';
 import en from './catalogs/en.json';
 import { registerBaseCatalog } from './context';
-import { DEFAULT_LOCALE, type Locale } from './locales';
 
 /**
  * `errors.*`, `auth.*`, `pagination.*`, `admin.*`, `validation.*`, `common.*`, `time.*`, `ui.*`.
@@ -17,20 +17,10 @@ import { DEFAULT_LOCALE, type Locale } from './locales';
  */
 export const FRAMEWORK_CATALOG: Catalog = loadCatalog(en);
 
-/**
- * The ONE locale this catalog is written in.
- *
- * Registering it under every locale was a fallback chain with no name: an app shipping only `es`
- * served `Page not found` and English `ui.*` chrome with `isMiss` reading FALSE, so nothing
- * downstream could see the gap — the one thing `⟦key⟧` exists to make impossible. A non-`en` app
- * translates the framework keys it renders into its own catalog.
- */
-export const FRAMEWORK_CATALOG_LOCALE: Locale = DEFAULT_LOCALE;
-
 // At module scope, and that is the whole point: `index.ts` re-exports this file, so anything that
 // can call `t()` has already imported the module that installs these strings. It was a function
 // (`registerFrameworkCatalog`) that only `defineCatalogs` called until 5.1.0 — so an app whose
 // catalog module nothing imported rendered `⟦errors.notFound.title⟧` on its 404 page, `⟦ui.*⟧` in
 // every design-system control, and had no way to notice (issue #249). Registration that an app
 // can forget is not registration; the framework's half of it is now unforgettable by construction.
-registerBaseCatalog(FRAMEWORK_CATALOG_LOCALE, FRAMEWORK_CATALOG);
+registerBaseCatalog(DEFAULT_LOCALE, FRAMEWORK_CATALOG);

package/src/index.ts

@@ -1,7 +1,9 @@
 /** Public surface of @ultimat3/i18n. Explicit exports only. */
 
-// Anchored on purpose, and NOT by the `sideEffects` array: Bun reads any array as `false` and drops
-// the module regardless (oven-sh/bun#40650). `registerBaseCatalog` here fills the catalog `t()`
+// Anchored on purpose, and not by the `sideEffects` array alone: Bun before 1.4.1 read any array as
+// `false` and dropped the module regardless (oven-sh/bun#40650), and a bare import holds on every
+// bundler. The array still lists it, because a bundler that honours the array drops a bare import
+// of a module it does not list. `registerBaseCatalog` here fills the catalog `t()`
 // falls back to, and `t()` never imports this module — so without the bare import every framework
 // string renders as its ⟦key⟧ placeholder. `SIDE_EFFECTS_ANCHORS` carries the argument and
 // `bun run side-effects` enforces it.
@@ -73,7 +75,7 @@ export {
   type LocaleAudit,
   mergeExtractions,
 } from './extract';
-export { FRAMEWORK_CATALOG, FRAMEWORK_CATALOG_LOCALE } from './framework';
+export { FRAMEWORK_CATALOG } from './framework';
 export {
   type InterpolationValue,
   type InterpolationVars,
@@ -87,17 +89,13 @@ export {
 } from './interpolate';
 export {
   type LocalePrefix,
-  localeSegment,
   localizedPath,
   splitLocalePrefix,
   unlocalizedPath,
 } from './locale-path';
 export {
   assertSupportedLocale,
-  DEFAULT_LOCALE,
   type Direction,
-  directionOf,
-  isRtl,
   isSupportedLocale,
   type LanguageRange,
   type Locale,
@@ -112,7 +110,7 @@ export {
   catalogRegistrationGaps,
 } from './registration';
 export {
-  createTranslator,
+  catalogTranslator,
   isMiss,
   type TranslateVars,
   type TranslationKey,

package/src/locale-path.ts

@@ -6,11 +6,10 @@
  * `meta` and the prerender writes files from one answer.
  */
 
-import { type LocalePathSplit, localeSegment, localizePath, splitLocalePath } from '@ultimat3/core';
+import { type LocalePathSplit, localizePath, splitLocalePath } from '@ultimat3/core';
 import { localeConfig, routedLocales } from './context';
 import type { Locale } from './locales';
 
-export { localeSegment };
 export type LocalePrefix = LocalePathSplit;
 
 /** `/en/precios` → `{ locale: 'en', path: '/precios', isDefault: false }`, or `undefined`. */

package/src/locales.ts

@@ -3,13 +3,12 @@
  * HTTP `Accept-Language` negotiation. Knows nothing about catalogs or interpolation.
  */
 
+import { DEFAULT_LOCALE } from '@ultimat3/core';
 import { localeUnsupported } from './errors';
 
 /** A normalized BCP-47 tag — primary subtag, lowercase (`pt`), or `lang-script` (`zh-hant`). */
 export type Locale = string;
 
-export const DEFAULT_LOCALE: Locale = 'en';
-
 /** Locales the framework's own catalogs may ship for. Apps narrow or extend this set. */
 export const SUPPORTED_LOCALES: readonly Locale[] = [
   'en',
@@ -44,10 +43,11 @@ export const SUPPORTED_LOCALES: readonly Locale[] = [
   'zh',
 ];
 
-// Direction moved to `@ultimat3/core` (`locale-direction.ts`) so a browser chunk that needs only
-// `directionOf` does not reach this barrel and the framework catalog it installs (issue #490).
-// Re-exported under the same names: every caller of this package is unchanged.
-export { type Direction, directionOf, isRtl } from '@ultimat3/core';
+// Direction is `@ultimat3/core`'s (`locale-direction.ts`), so a browser chunk that needs only
+// `directionOf` does not reach this barrel and the framework catalog it installs (issue #490). The
+// TYPE is re-exported because `LocaleResolution.direction` names it; the functions are not — their
+// one import path is `@ultimat3/core`.
+export type { Direction } from '@ultimat3/core';
 
 /**
  * The registered spelling of `lower`, compared case-insensitively. A registered `pt-BR` used to

package/src/translator.ts

@@ -4,9 +4,10 @@
  * visible in dev and in review screenshots instead of invisible in production.
  */
 
+import { DEFAULT_LOCALE } from '@ultimat3/core';
 import type { Catalog } from './catalog';
 import { type InterpolationVars, interpolate, selectPluralKey } from './interpolate';
-import { DEFAULT_LOCALE, type Locale } from './locales';
+import type { Locale } from './locales';
 
 export interface TranslateVars extends InterpolationVars {
   /** Present ⇒ plural selection runs against the locale's CLDR categories. */
@@ -52,7 +53,7 @@ export interface Translator<TCatalog = Catalog> {
   readonly locale: Locale;
 }
 
-export function createTranslator(catalog: Catalog, locale: Locale = DEFAULT_LOCALE): Translator {
+export function catalogTranslator(catalog: Catalog, locale: Locale = DEFAULT_LOCALE): Translator {
   const hasExact = (key: string): boolean => Object.hasOwn(catalog, key);
 
   const resolveKey = (key: string, vars?: TranslateVars): string => {