@ultimat3/i18n 23.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.
@@ -53,6 +54,16 @@ Imported by every package that renders a string.
   and `x verify`'s `i18n` step is what asks it of an app. An app reads strings through its OWN
   module (`useT()` from `packages/i18n/src/index.ts`), never `t` from `@ultimat3/i18n`, so that
   registration is a consequence of rendering rather than something a boot has to remember.
+- **`t()` ALWAYS interpolates, `As of 2026-10`.** It skipped `interpolate` when `vars` was omitted,
+  so `t('a')` on `Hello {name}` put the raw placeholder on the page where `t('a', {})` put the loud
+  `⟦name⟧`, and `{{` stayed escaped. One message, one render. A caller that wants the TEMPLATE
+  (plural forms for a client island) calls `t.raw(key)`. **Breaking.**
+- **`defineCatalogs` runs `assertLocale` over every tag BEFORE the register loop.**
+  `configureLocales` validated them after it, so `X_LOCALE_INVALID` arrived with the bad tag
+  already in `registeredLocales()`. That code is `@ultimat3/core`'s, raised by its `assertLocale` —
+  never add it to `I18N_ERROR_CODES` (a second claim is `X_ERROR_CODE_DUPLICATE`).
+- **A `q` that is not a plain decimal is 0**, so the range is dropped. A digits-only capture meant
+  `en;q=abc` never matched and kept the default quality of 1.
 - Only an **own** property of `vars` is a variable — `interpolate` guards with `Object.hasOwn`.
   A plain object inherits `constructor`, `toString`, `valueOf` and `__proto__`, so a bare
   `vars[name]` rendered a function's source into the page for a template nobody wrote a variable
@@ -95,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

@@ -54,6 +54,8 @@ t('pagination.showing', { from: 1, to: 20, total: 137 });
 t('pagination.result', { count: 1 });   // "1 result"
 t('pagination.result', { count: 9 });   // "9 results"
 t('nav.settings');                      // "⟦nav.settings⟧" — fix it or ship it broken, visibly
+t('pagination.result');                 // "⟦count⟧ result" — vars or none, the template is always
+                                        // interpolated; t.raw(key) is the template itself
 ```
 
 | Call | Returns | Use for |
@@ -97,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,
@@ -114,6 +132,7 @@ X_CATALOG_MISSING_KEYS: catalog is incomplete
 | Code | When |
 |---|---|
 | `X_LOCALE_UNSUPPORTED` | a tag outside the supported set was asserted, or a `defineCatalogs` default that is not one of its locales |
+| `X_LOCALE_INVALID` | `defineCatalogs` or `configureLocales` was given a tag that is not well-formed BCP 47 (`en_US`). **`@ultimat3/core`'s code**, raised by its `assertLocale` — not an `I18nError` and not in `I18N_ERROR_CODES` |
 | `X_CATALOG_MISSING_KEYS` | a shipped locale lacks a key the source uses |
 | `X_CATALOG_INVALID` | non-string leaf, bad key segment, or a dotted/nested collision |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/i18n",
-  "version": "23.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": "23.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})."
@@ -205,7 +218,8 @@
       "secret-required": "A value is required: this column is sealed and has no default.",
       "action-not-applicable": "This action does not apply to the row as it is now.",
       "row-out-of-scope": "The row this write would leave is outside the rows this account may see.",
-      "batch-not-offered": "This action does not run over a selection of rows."
+      "batch-not-offered": "This action does not run over a selection of rows.",
+      "row-changed": "Someone changed this row after you opened it. Your values are kept over the row as it is now: review them and save again."
     },
     "filter": {
       "any": "Any",
@@ -326,7 +340,8 @@
       "skipped": {
         "forbidden": "this account may not search that entity",
         "no-text-fields": "that entity has no text field to search",
-        "no-repo": "that entity has no repo bound"
+        "no-repo": "that entity has no repo bound",
+        "failed": "that entity's repo failed while searching"
       }
     },
     "value": {
@@ -485,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",
@@ -493,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

@@ -3,18 +3,19 @@
  * No call site passes a locale by hand — `t()` here is the ambient translator.
  */
 
-import { assertLocale, cachedFormatter, canonicalLocale, tryUseContext } from '@ultimat3/core';
-import { type Catalog, mergeCatalogs } from './catalog';
 import {
+  assertLocale,
+  cachedFormatter,
+  canonicalLocale,
   DEFAULT_LOCALE,
   type Direction,
   directionOf,
-  type Locale,
-  negotiateLocale,
-  normalizeLocale,
-  SUPPORTED_LOCALES,
-} from './locales';
-import { createTranslator, type TranslateVars, type Translator } from './translator';
+  readCookie,
+  tryUseContext,
+} from '@ultimat3/core';
+import { type Catalog, mergeCatalogs } from './catalog';
+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';
@@ -145,30 +146,18 @@ export function resolveLocale(
   return { locale: fallback, direction: directionOf(fallback), source: 'default' };
 }
 
-/** Read `x_locale` out of a raw `Cookie` header. */
+/**
+ * Read `x_locale` out of a raw `Cookie` header — through core's `readCookie`, so a malformed
+ * escape (`x_locale=%`) is the raw value, which `resolveLocale` then fails to normalise and skips.
+ */
 export function localeCookieOf(cookieHeader?: string | null): string | undefined {
-  if (!cookieHeader) return undefined;
-  for (const pair of cookieHeader.split(';')) {
-    const index = pair.indexOf('=');
-    if (index === -1) continue;
-    if (pair.slice(0, index).trim() !== LOCALE_COOKIE) continue;
-    const raw = pair.slice(index + 1).trim();
-    try {
-      return decodeURIComponent(raw);
-    } catch {
-      // A cookie is client-authored: `x_locale=%` is a `URIError` out of a per-request path, and
-      // a 500 for a malformed locale is worse than the raw value, which `resolveLocale` then
-      // fails to normalise and skips. Same guard as `@ultimat3/auth`'s `decodeCookieValue`.
-      return raw;
-    }
-  }
-  return undefined;
+  return readCookie(cookieHeader, LOCALE_COOKIE) ?? 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.
  */
@@ -304,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

@@ -4,6 +4,7 @@
  * Boot-time only — nothing here runs per request.
  */
 
+import { assertLocale } from '@ultimat3/core';
 import { type Catalog, catalogKeys, loadCatalog, mergeCatalogs } from './catalog';
 import { configureLocales, registerCatalog } from './context';
 import { localeUnsupported } from './errors';
@@ -37,11 +38,27 @@ 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> {
   const locales = Object.keys(input.locales) as (keyof TLocales & string)[];
   if (!locales.includes(input.default)) throw localeUnsupported(input.default, locales);
+  // Every tag, before anything is registered. `configureLocales` below runs the same screen, but
+  // after the register loop — so its `X_LOCALE_INVALID` arrived with the malformed tag already in
+  // `registeredLocales()` and the well-formed locales' strings already live.
+  for (const locale of locales) assertLocale(locale);
 
   // Load everything before registering anything: a malformed catalog must fail the boot
   // whole, not leave half the locales live and the other half missing.
@@ -57,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
@@ -107,6 +107,9 @@ export interface LanguageRange {
   quality: number;
 }
 
+/** A plain non-negative decimal — `0.8`, `1`, `.5`. No sign, no exponent, one point. */
+const Q_VALUE = /^(?:\d+(?:\.\d*)?|\.\d+)$/;
+
 /**
  * Parse `Accept-Language: en-GB,en;q=0.9,fr-CH;q=0.8,*;q=0.5` into ranges sorted by
  * quality descending, ties resolved by header order (stable sort).
@@ -120,10 +123,13 @@ export function parseAcceptLanguage(header?: string | null): LanguageRange[] {
     if (!tag) continue;
     let quality = 1;
     for (const param of params) {
-      const match = /^\s*q\s*=\s*([0-9.]+)\s*$/i.exec(param);
+      // The value is captured WHATEVER it is and judged after. Capturing digits only meant
+      // `q=abc` did not match at all, so the default of 1 stood: a malformed range outranked
+      // every well-formed one. A `q` that is not a plain decimal is a range nobody can rank — 0.
+      const match = /^\s*q\s*=(.*)$/i.exec(param);
       if (match?.[1] !== undefined) {
-        const parsed = Number.parseFloat(match[1]);
-        quality = Number.isFinite(parsed) ? Math.min(Math.max(parsed, 0), 1) : 0;
+        const value = match[1].trim();
+        quality = Q_VALUE.test(value) ? Math.min(Number.parseFloat(value), 1) : 0;
       }
     }
     if (quality > 0) ranges.push({ tag: tag.toLowerCase(), quality });

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 => {
@@ -72,7 +73,11 @@ export function createTranslator(catalog: Catalog, locale: Locale = DEFAULT_LOCA
     const resolved = resolveKey(key, vars);
     const template = hasExact(resolved) ? catalog[resolved] : undefined;
     if (template === undefined) return `⟦${key}⟧`;
-    return vars === undefined ? template : interpolate(template, vars);
+    // Always, never only when `vars` was passed: skipping it made `t('a')` and `t('a', {})` two
+    // renders of one message — the first put the raw `Hello {name}` on the page where the second
+    // put the loud `⟦name⟧`, and left `{{` escaped. `interpolate` returns a brace-free template
+    // untouched, so the common case pays one `includes`.
+    return interpolate(template, vars);
   };
 
   return Object.assign(translate, {