@pithy-sh/core 0.1.0

package/src/i18n/locale.ts

@@ -0,0 +1,153 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+
+/**
+ * The longest language tag this kit accepts. RFC 5646's own grammar allows far more, but a tag that
+ * long is not a locale anyone serves — it is a header a caller filled with something else. The bound
+ * exists so a hostile `Accept-Language` cannot make the matcher walk a megabyte per request.
+ */
+export const MAX_LOCALE_TAG_LENGTH = 64;
+
+/**
+ * The shape of a well-formed language tag, checked before `Intl.Locale` ever sees it.
+ *
+ * Deliberately looser than RFC 5646 and deliberately stricter than "any string". Looser, because the
+ * authority on whether `es-419` or `zh-Hans-CN` is meaningful is ICU, not a regular expression we would
+ * have to keep in step with it. Stricter, because {@link https://tc39.es/ecma402 `Intl.Locale`} throws a
+ * `RangeError` rather than returning a signal, and the four things it throws on — `*`, `en_US`, the empty
+ * string, and a token still carrying `;q=0.9` — all appear in real `Accept-Language` headers.
+ */
+const LANGUAGE_TAG = /^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*$/;
+
+/**
+ * A BCP-47 language tag — the identity of a locale everywhere in the kit.
+ *
+ * One string, two jobs, and only one of them falls back: the tag that picks a **catalog** is the words
+ * we have written, and the tag that drives **formatting** is whatever the reader asked for. See
+ * {@link LocaleContext} for why collapsing them is the bug where an Argentine reads Spanish and sees
+ * `1,234.56`.
+ */
+export const Locale = z
+  .string()
+  .min(2)
+  .max(MAX_LOCALE_TAG_LENGTH)
+  .regex(LANGUAGE_TAG, { message: "A locale is a BCP-47 tag like `en`, `es`, or `es-AR`." })
+  // **And then ICU has to accept it**, which is a strictly narrower thing than matching the shape.
+  // `en-x`, `en-t`, `en-u`, `en-1` and `en-a-bbb-a-ccc` are all well-formed by the grammar above and
+  // all raise `RangeError` in `new Intl.Locale()`: a singleton subtag with nothing after it, and a
+  // repeated extension, are shapes the pattern cannot see.
+  //
+  // The check is here rather than at each render site because of where the values end up. This schema
+  // guards `pithy_auth_users.locale` and `pithy_email_jobs.locale`, so a tag it admits is a tag stored
+  // in D1 — and the place it is read back is `renderEmail`, inside the send Workflow, with no request
+  // on it. An `Intl` construction that throws there is a raw `RangeError` rather than a `PithyError`,
+  // `classifySendError` sees no code it knows, and the job burns its retries and wedges. Refusing the
+  // value on the way in costs one `try` at a boundary that was already validating; catching it on the
+  // way out costs a guard at every site that ever formats, forever, and one of them will be forgotten.
+  .refine((tag) => parseLocale(tag) !== null, {
+    message: "That is not a language tag `Intl` accepts. `en-x` and `en-a-bbb-a-ccc` are the usual shapes that miss.",
+  })
+  .describe("A BCP-47 language tag (`en`, `es`, `es-AR`) — the identity of a locale across the kit.");
+export type Locale = z.infer<typeof Locale>;
+
+/** Which way a locale's script runs. Drives the `dir` attribute on the document and the email shell. */
+export const TextDirection = z
+  .enum(["ltr", "rtl"])
+  .describe("Which way a locale's script runs — the value of the `dir` attribute.");
+export type TextDirection = z.infer<typeof TextDirection>;
+
+/**
+ * The per-request locale seam, published on `c.var.locale` by `@pithy-sh/i18n` and `null` in a Worker
+ * that does not compose it. Core defines the shape; one capability populates it — the same split
+ * `AuthContext` uses, and for the same reason: `@pithy-sh/email` and the error module both need a
+ * locale and neither may import an i18n capability.
+ */
+export const LocaleContext = z
+  .object({
+    catalogLocale: Locale.describe("The locale whose catalog answers `t()` — the words the kit actually has."),
+    formattingLocale: Locale.describe("The locale handed to `Intl` — what the reader asked for, region and all."),
+    direction: TextDirection.describe("The catalog locale's text direction, for `lang`/`dir` on the document."),
+  })
+  .describe("Per-request resolved locale; the seam capabilities read instead of negotiating their own.");
+export type LocaleContext = z.infer<typeof LocaleContext>;
+
+/**
+ * `tag` as an `Intl.Locale`, or `null` when it is not one.
+ *
+ * **Every construction on header- or adopter-supplied input goes through this.** `new Intl.Locale()`
+ * throws `RangeError` on `*`, on `en_US`, on the empty string, and on any token still carrying
+ * `;q=0.9` — so a malformed `Accept-Language` is an uncaught 500 rather than a fallback, unless the
+ * throw is caught somewhere. It is caught here, once, and nowhere else.
+ */
+export function parseLocale(tag: string): Intl.Locale | null {
+  if (!LANGUAGE_TAG.test(tag) || tag.length > MAX_LOCALE_TAG_LENGTH) return null;
+  try {
+    return new Intl.Locale(tag);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The part of `tag` that may be handed to `Intl` as a **formatting** locale, or `null` when it is not a
+ * tag at all: language, script, region and variants, with every extension subtag stripped.
+ *
+ * **A `-u-` extension is not a locale, it is an instruction**, and the range a formatting locale is
+ * built from is caller-supplied. `?lang=en-u-nu-hanidec` truncates to `en`, matches a project that
+ * ships English, and — kept whole — reaches `Intl.NumberFormat` verbatim, where it renders `1,234` as
+ * `一,二三四`. `-u-ca-islamic` does the same to every date on the page. Nothing is disclosed and nothing
+ * persists, so it is spoofing rather than a breach; it is also a link somebody can send, and the whole
+ * point of resolving against `supportedLocales` is that a reader cannot pick a rendering the project
+ * did not offer.
+ *
+ * `baseName` is exactly the right cut, and is why this is a helper rather than a regex: `es-AR`,
+ * `zh-Hant-TW`, `es-419` and `de-DE-1996` all survive whole, because none of them is an extension.
+ */
+export function formattingLocaleOf(tag: string): string | null {
+  return parseLocale(tag)?.baseName ?? null;
+}
+
+/** Whether `tag` is a language tag `Intl` will accept — the predicate half of {@link parseLocale}. */
+export function isLocale(tag: string): tag is Locale {
+  return parseLocale(tag) !== null;
+}
+
+/**
+ * The languages written right-to-left, for the runtimes that expose neither text-info accessor.
+ *
+ * A last resort, not the answer: `getTextInfo()` knows about scripts this list cannot name, and it is
+ * asked first. The five here are the ones a fallback has to get right.
+ */
+const RTL_LANGUAGES: ReadonlySet<string> = new Set(["ar", "he", "fa", "ur", "ps"]);
+
+/**
+ * Text info as either of the two names the runtimes Pithy targets expose it under.
+ *
+ * Neither is on the standard's own `Intl.Locale` type in every TypeScript lib, and the split is real:
+ * **workerd and Bun expose `getTextInfo()` only; Node 22 — the declared floor, so the CLI — exposes
+ * `textInfo` only; Node 24 has both.** Firefox has the method from 153 and Safari the accessor from
+ * 15.4. A helper written against either name alone is wrong on roughly half the matrix.
+ */
+type LocaleWithTextInfo = Intl.Locale & {
+  getTextInfo?: () => { direction?: string };
+  textInfo?: { direction?: string };
+};
+
+/**
+ * Which way `tag`'s script runs, feature-detected across both spellings and falling back to a small
+ * right-to-left language set when a runtime exposes neither.
+ *
+ * Total: an unparseable tag is `ltr`, because a document still needs a `dir` and guessing the other way
+ * mirrors a page nobody asked to mirror.
+ */
+export function localeDirection(tag: string): TextDirection {
+  const locale = parseLocale(tag);
+  if (!locale) return "ltr";
+  const withTextInfo = locale as LocaleWithTextInfo;
+  const info = typeof withTextInfo.getTextInfo === "function" ? withTextInfo.getTextInfo() : withTextInfo.textInfo;
+  if (info?.direction === "rtl") return "rtl";
+  if (info?.direction === "ltr") return "ltr";
+  return RTL_LANGUAGES.has(locale.language) ? "rtl" : "ltr";
+}

package/src/i18n/localeMarker.ts

@@ -0,0 +1,116 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * Reading the locale a source file declares in its head — the reader for the marker `docs/I18N.md` publishes.
+ *
+ * A prose census reads every committed file as text and refuses the spellings a project does not write. This
+ * repository runs one (`packages/cli/src/ci/americanEnglish.test.ts`: the words this project writes are
+ * American), and any project that ships translated copy eventually needs the same thing, because a catalog
+ * written in Spanish is prose that is *supposed* not to be English. A path list would answer that and is
+ * exactly what a census must not grow — a list is right on the day it is written, wrong afterwards, and the
+ * way it goes wrong is that the gate keeps passing. So the file says what it is instead, in one marker, in
+ * its head, where a reader meets it: the **locale** it is written in, and that the copy is an **unreviewed
+ * first pass**. Both facts are load-bearing and neither is checkable from the outside.
+ *
+ * ## The half that is easy to get backwards
+ *
+ * **The marker exempts the file's quoted values, not the file.** A catalog is not written in Spanish — its
+ * *values* are. Everything around them is a docblock, an import and an identifier: the project's own English
+ * prose, and exactly as subject to the rule as any other file's. So a declaring file widens what counts as a
+ * value — every quoted run, whole sentences included, rather than only the whitespace-free tokens exempt
+ * everywhere else — and every character outside those quotes is censused as it would be anywhere.
+ *
+ * Reading the marker as *skip this file* is the port that goes wrong, and it goes wrong quietly. It made this
+ * repository's own `es/errors.ts` a place where a twenty-seven-line English argument went unread, which is a
+ * gate that cannot fail on most of what it is looking at, and it costs an adopter the docblocks of every
+ * translated catalog they ever add.
+ *
+ * **`en` and `en-*` are a declaration and never an exemption**, which is why {@link localeDeclared} hands back
+ * the tag rather than a yes or a no. The words a project writes *in English* are the ones a census is about,
+ * and a marker cannot become a way to opt English prose out of it. The caller decides what a tag means;
+ * treating `en` as translated is the same mistake as treating `es` as skippable.
+ *
+ * ## Why it lives in `core/src/i18n`
+ *
+ * The folder is the import path, so it is named for the caller. The marker is a locale declaration — the same
+ * thing `./locale` and `./catalog` are about, one artifact earlier — and an adopter reaching for it is asking
+ * a question about translated copy, not about linting. It is deliberately not in the CLI: the CLI is a
+ * development tool an adopter's own test suite has no reason to depend on, and this is the kit's precedent for
+ * a pure textual scanner that a repository's tests want back (`../entitlement/gateScan`, which exports
+ * `withoutComments` for the same reason). No `node:` import, no filesystem: the caller brings the text,
+ * whether from a walked directory or from `import.meta.glob(…, "?raw")` inside a Workers-typed program.
+ *
+ * The census that owns the rest of the rule stays where it is. What ships here is the pair a port gets wrong.
+ */
+
+/**
+ * What a file written in a language other than English declares in its head.
+ *
+ * The exact spelling is published in `docs/I18N.md` — `LOCALE <tag>`, an em dash, and the unreviewed-first-pass
+ * sentence — and `packages/cli/src/ci/americanEnglish.test.ts` reads the line out of that document and holds it
+ * to this pattern, so an adopter copying the published marker cannot copy one that matches nothing. The tag is
+ * captured, never merely detected, because the caller's decision turns on which language it names.
+ */
+const LOCALE_DECLARED = /\bLOCALE ([a-z]{2,8}(?:-[A-Za-z0-9]{1,8})*) — an unreviewed first pass\./;
+
+/**
+ * How far into a file the marker has to be, so a file mentioning it in prose is still read.
+ *
+ * A documented number rather than a tuning knob: `docs/I18N.md` publishes this window to adopters, and
+ * `packages/cli/src/ci/americanEnglish.test.ts` holds the count that document states to where this reader
+ * actually stops — so moving the number here fails the build until the document moves with it. This module's
+ * own test pins both sides of the boundary. It is an implementation detail of {@link localeDeclared} and is
+ * not exported — a caller hands over a whole source and gets an answer.
+ */
+const HEAD_LINES = 25;
+
+/**
+ * The locale tag this source declares in its head, or `null` if it declares none.
+ *
+ * `null` is the ordinary answer: almost every file in a tree declares nothing, and a file that does is saying
+ * something about its own values, not asking to be skipped. See this module's docblock for what a caller owes
+ * the answer — in particular that `en` comes back like any other tag and exempts nothing.
+ */
+export function localeDeclared(source: string): string | null {
+  for (const line of source.split("\n").slice(0, HEAD_LINES)) {
+    const found = LOCALE_DECLARED.exec(line);
+    if (found !== null) return found[1] as string;
+  }
+  return null;
+}
+
+/**
+ * Every span on one line whose quoted content is a value rather than prose — as `[open, close)` offsets.
+ *
+ * `open` is the first character inside the quote and `close` is the closing quote, so a match at or after
+ * `open` and ending at or before `close` sits inside a value. Left to right, in whichever of the three quote
+ * characters opened it.
+ *
+ * By default a run holding whitespace is a sentence, not a value, and **a span that turns out to hold one is
+ * passed over rather than skipped**: the scan keeps reading inside it, which is how a backticked token inside
+ * a prose string literal still counts — this repository names wire values that way in a `.describe()`.
+ *
+ * `everyQuoted` widens that to include the sentences, for one case and one only: a line in a file that has
+ * declared itself written in another language, where the quoted runs are the translation. It is the mechanism
+ * the marker drives, and it is why the marker exempts a file's values without exempting the file.
+ *
+ * A run is one line's worth. A quote that never closes on its line opens no value, so the inner lines of a
+ * multi-line template literal are read as prose — deliberately, since that is where a long English argument
+ * would otherwise hide.
+ */
+export function valueSpans(line: string, everyQuoted = false): [number, number][] {
+  const spans: [number, number][] = [];
+  for (let index = 0; index < line.length; index += 1) {
+    const quote = line[index];
+    if (quote !== '"' && quote !== "'" && quote !== "`") continue;
+    const close = line.indexOf(quote, index + 1);
+    if (close === -1) continue;
+    const inner = line.slice(index + 1, close);
+    if (inner.length === 0) continue;
+    if (!everyQuoted && /\s/.test(inner)) continue;
+    spans.push([index + 1, close]);
+    index = close;
+  }
+  return spans;
+}

package/src/i18n/match.ts

@@ -0,0 +1,111 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { parseLocale } from "./locale";
+
+/**
+ * A declared exception map: a language range the truncation walk would miss, and the supported locale
+ * it means. `{ nb: "no", tl: "fil" }` — the pairs no algorithm derives, because they are historical
+ * rather than structural.
+ */
+export type LocaleExceptions = Readonly<Record<string, string>>;
+
+/** How a match was reached, so a caller can tell an answer from a default. */
+export interface LocaleMatch {
+  /** The supported locale that answered, exactly as the caller spelled it in `supported`. */
+  readonly locale: string;
+  /** The range that matched it, lower-cased — `*` when a wildcard took the first supported locale. */
+  readonly range: string;
+}
+
+/** Lower-cased index of the supported list, so matching is case-insensitive without lower-casing answers. */
+function index(supported: readonly string[]): Map<string, string> {
+  const map = new Map<string, string>();
+  for (const locale of supported) {
+    const key = locale.toLowerCase();
+    if (!map.has(key)) map.set(key, locale);
+  }
+  return map;
+}
+
+/**
+ * RFC 4647 §3.4 lookup: `tag`, then `tag` with its right-most subtag removed, and so on.
+ *
+ * A trailing single-character subtag is removed with the one before it, as the RFC requires —
+ * `en-a-bbb` truncates to `en`, never to the meaningless `en-a`.
+ */
+function truncationWalk(tag: string, supported: Map<string, string>): string | null {
+  let candidate = tag.toLowerCase();
+  while (candidate.length > 0) {
+    const hit = supported.get(candidate);
+    if (hit) return hit;
+    const cut = candidate.lastIndexOf("-");
+    if (cut < 0) return null;
+    candidate = candidate.slice(0, cut);
+    const tail = candidate.lastIndexOf("-");
+    if (tail >= 0 && candidate.length - tail === 2) candidate = candidate.slice(0, tail);
+  }
+  return null;
+}
+
+/**
+ * The supported locale that best answers one range, or `null`.
+ *
+ * Three passes, in the order that makes each one earn its place: the declared exception map first,
+ * because it exists to override what follows; then the truncation walk on the range as written, which
+ * answers `es-AR` with `es`; then the walk again over the **maximized** form, which answers `zh-TW`
+ * with `zh-Hant` by way of `zh-Hant-TW`.
+ *
+ * **Maximizing is the third step, not the first.** `Intl.Locale` throws on input the first step handles
+ * fine, and maximizing a range before trying it as written turns `es` into `es-Latn-ES` and then walks
+ * back down to `es` — the same answer, three constructions later, and a `RangeError` away from a 500.
+ */
+function lookupRange(range: string, supported: Map<string, string>, exceptions: LocaleExceptions): string | null {
+  // `Object.hasOwn`, never a bare index — `exceptions` is a plain object built by Zod, so
+  // `exceptions["constructor"]` answers `Object` and `exceptions["__proto__"]` answers the prototype.
+  // Read bare, both are truthy and neither is a string, so `declared.toLowerCase()` threw a
+  // `TypeError` — inside a global middleware, which makes `?lang=constructor` a 500 on every request,
+  // and a stale `pithy_locale=__proto__` cookie a 500 on every request that client makes until it is
+  // cleared. `catalogs/browser.ts` already guards its own thunk map for exactly this reason.
+  const key = range.toLowerCase();
+  const declared = Object.hasOwn(exceptions, key) ? exceptions[key] : undefined;
+  if (declared) {
+    const hit = supported.get(declared.toLowerCase());
+    if (hit) return hit;
+  }
+  const direct = truncationWalk(range, supported);
+  if (direct) return direct;
+  const maximized = parseLocale(range)?.maximize().toString();
+  return maximized ? truncationWalk(maximized, supported) : null;
+}
+
+/**
+ * The first supported locale any of `desired` asks for, most-wanted first, or `null` when none does.
+ *
+ * `desired` is already in preference order — {@link parseAcceptLanguage} sorts by q-weight, and a
+ * browser resolver chain builds it from the reader's explicit choice downward. A `*` range takes the
+ * first supported locale, which is what "anything you have" means; it is checked in place rather than
+ * up front, so a reader who wrote `de, *` is answered in German when German ships.
+ *
+ * Total, and never throws: every `Intl` construction on the way through is guarded, so a header full
+ * of `en_US` and `;q=0.9` fragments falls through to `null` and the caller's default.
+ */
+export function matchLocale(
+  desired: readonly string[],
+  supported: readonly string[],
+  exceptions: LocaleExceptions = {},
+): LocaleMatch | null {
+  if (supported.length === 0) return null;
+  const lookup = index(supported);
+  for (const range of desired) {
+    const normalized = range.trim().toLowerCase();
+    if (normalized.length === 0) continue;
+    if (normalized === "*") {
+      const first = supported[0];
+      return first ? { locale: first, range: normalized } : null;
+    }
+    const hit = lookupRange(normalized, lookup, exceptions);
+    if (hit) return { locale: hit, range: normalized };
+  }
+  return null;
+}

package/src/i18n/registry.ts

@@ -0,0 +1,78 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { Capability } from "../capability/capability";
+import { ValidationError } from "../error/pithyError";
+import { type LocaleCatalogs, type MessageCatalog, messageDomain } from "./catalog";
+import { DEFAULT_LOCALE } from "./translator";
+
+/** One capability's contribution, kept beside the capability that made it so a refusal can name it. */
+interface Contribution {
+  /** The contributing capability's `name` — the only domain it may write keys under. */
+  readonly capability: string;
+  /** That capability's catalogs, keyed by locale. */
+  readonly catalogs: LocaleCatalogs;
+}
+
+/**
+ * Every composed capability's `messages`, merged into one set of catalogs keyed by locale.
+ *
+ * **A capability may only declare keys under its own domain**, and the merge refuses anything else.
+ * That is the same rule as `pithy_<capability>_<table>` and `auth/invalid_token`, enforced for the same
+ * reason: the domain segment is what makes two capabilities' contributions incapable of colliding, so
+ * merge order stops being a thing anyone has to reason about. It applies to the adopter's own `app`
+ * capability exactly as it applies to a kit package — `board/nav.settings` is theirs to declare, and
+ * `auth/sign_in.title` is not.
+ *
+ * Library-before-app, like the migration registry: capabilities are merged in composition order, so a
+ * later contribution wins a key an earlier one wrote. With the domain rule in force that can only
+ * happen between two capabilities sharing a name, which `createBackend` already refuses.
+ */
+export function composeMessages(capabilities: readonly Capability[]): LocaleCatalogs {
+  const contributions: Contribution[] = [];
+  for (const capability of capabilities) {
+    if (capability.messages) contributions.push({ capability: capability.name, catalogs: capability.messages });
+  }
+  // **Accumulated in a `Map`, not in an object literal, and that is not a style preference.**
+  //
+  // `Object.entries` really does hand back an own `__proto__` key — `JSON.parse('{"__proto__":{}}')`
+  // creates one, and a capability's `messages` can arrive from parsed JSON. Assigning `merged[locale]`
+  // for that key goes *through* the inherited setter rather than into the map: the locale is silently
+  // lost, and the object's prototype is replaced. Guarding the read with `Object.hasOwn` does not help,
+  // because the hazard is the write. A `Map` has no prototype chain to walk and no setter to trip, and
+  // `Object.fromEntries` defines rather than assigns, so the object handed back is an ordinary one
+  // with an ordinary prototype.
+  //
+  // Only an adopter's own capability could reach this, in their own runtime, so it is a consistency
+  // fix rather than a vulnerability — but the rest of this merge path is hardened and a lone exception
+  // is the one somebody copies.
+  const merged = new Map<string, Map<string, string>>();
+  for (const { capability, catalogs } of contributions) {
+    for (const [locale, catalog] of Object.entries(catalogs)) {
+      const target = merged.get(locale) ?? new Map<string, string>();
+      for (const [key, message] of Object.entries(catalog)) {
+        const domain = messageDomain(key);
+        if (domain !== capability) {
+          throw new ValidationError({
+            message: "A capability may only contribute messages under its own domain.",
+            action: `Rename \`${key}\` to start with \`${capability}/\`, or move it to the capability that owns that domain.`,
+            detail: `\`${capability}\` contributed \`${key}\` in locale \`${locale}\`, whose domain is \`${domain}\`.`,
+          });
+        }
+        target.set(key, message);
+      }
+      merged.set(locale, target);
+    }
+  }
+  return Object.fromEntries([...merged].map(([locale, catalog]) => [locale, Object.fromEntries(catalog)]));
+}
+
+/**
+ * The catalog for `locale`, or the default locale's, or an empty one.
+ *
+ * The fallback that makes the seam optional: a Worker composing no i18n capability reads the baked
+ * English and behaves byte for byte as it did before any of this landed.
+ */
+export function catalogFor(catalogs: LocaleCatalogs, locale: string): MessageCatalog {
+  return catalogs[locale] ?? catalogs[DEFAULT_LOCALE] ?? {};
+}

package/src/i18n/translator.ts

@@ -0,0 +1,168 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { interpolate, lookupMessage, type MessageCatalog, type MessageParams } from "./catalog";
+import { localeDirection, type TextDirection } from "./locale";
+
+/**
+ * The i18n seam. `@pithy-sh/core` defines this shape; `@pithy-sh/i18n` populates it from the resolved
+ * request locale. Every other capability, and every screen, depends only on this object — the same
+ * split `AuthContext` uses, and for the same reason: `@pithy-sh/email` and the error module both need
+ * a locale and neither may import an i18n capability.
+ *
+ * **The two locales are both here, as plain strings.** An adopter who already owns their date and
+ * number rendering needs the locale as a *value* to hand to `Intl`; forcing it through
+ * {@link Translator.formatDate} turns a one-line repair into an every-call-site one, against gates that
+ * exist to keep those calls in one place.
+ */
+export interface Translator {
+  /**
+   * The locale whose catalog answers {@link Translator.t} — the words the kit actually has.
+   *
+   * An `es-AR` reader gets `es` here, because `es` is what is written. See
+   * {@link Translator.formattingLocale} for the half that does not fall back.
+   */
+  readonly catalogLocale: string;
+  /**
+   * The locale handed to `Intl` — what the reader asked for, region and all.
+   *
+   * An `es-AR` reader gets `es-AR` here, which `Intl` supports natively whether or not anyone wrote a
+   * string for it. Collapsing this into {@link Translator.catalogLocale} is the bug where an Argentine
+   * reads Spanish and sees `1,234.56`.
+   */
+  readonly formattingLocale: string;
+  /** The catalog locale's text direction — what `lang`/`dir` on the document and the email shell get. */
+  readonly direction: TextDirection;
+  /**
+   * The message `key` names, with `{placeholder}` substitution.
+   *
+   * Returns the key itself when nothing has it. That is the honest answer — a blank reads like finished
+   * copy — and it is unreachable for a kit key, because catalog coverage is a CI gate.
+   */
+  t(key: string, params?: MessageParams): string;
+  /**
+   * The message `key` names, or `null` when no layer has it.
+   *
+   * **The half {@link Translator.t} cannot express, and the error path needs.** `t` is total because a
+   * screen always has to render something, so a miss comes back as the key — which is the honest thing
+   * to show and is unusable as a signal. An error is the other case: the payload already carries an
+   * English `message`, and a client that could not translate the code must render *that*, not the code.
+   *
+   * So the documented client contract is `t.maybe(payload.code, payload.params) ?? payload.message`.
+   * Written against `t` it silently never falls back — `t` returns the key, `??` sees a string, and a
+   * caller in an uncovered locale reads `auth/invalid_token` on their screen instead of the sentence
+   * the server took care to send them.
+   */
+  maybe(key: string, params?: MessageParams): string | null;
+  /**
+   * The message `key` names, in the plural form `count` calls for.
+   *
+   * Looks up `<key>.<category>` for the `Intl.PluralRules` category of `count` in the catalog locale,
+   * falling back to `<key>.other`. `count` is available to the message as `{count}` without being
+   * passed twice.
+   *
+   * Explicit rather than folded into {@link Translator.t}, because plural selection is the thing a
+   * second locale exposes: English has two forms, Spanish has two, Russian has three, and a call site
+   * that concatenated a number onto a noun has no form at all.
+   */
+  plural(key: string, count: number, params?: MessageParams): string;
+  /** `value` as a number in the formatting locale. */
+  formatNumber(value: number, options?: Intl.NumberFormatOptions): string;
+  /** `value` as an amount of `currency` in the formatting locale. */
+  formatCurrency(value: number, currency: string, options?: Intl.NumberFormatOptions): string;
+  /** `value` as a date in the formatting locale. Accepts a `Date` or an epoch-milliseconds number. */
+  formatDate(value: Date | number, options?: Intl.DateTimeFormatOptions): string;
+  /** `values` as a list in the formatting locale — `a, b y c` in Spanish, `a, b, and c` in English. */
+  formatList(values: readonly string[], options?: Intl.ListFormatOptions): string;
+  /** `value` `unit`s from now, in the formatting locale — `ayer`, `in 3 days`. */
+  formatRelativeTime(
+    value: number,
+    unit: Intl.RelativeTimeFormatUnit,
+    options?: Intl.RelativeTimeFormatOptions,
+  ): string;
+}
+
+/** What a translator is built from: the locales it answers in, and the layers it looks messages up through. */
+export interface TranslatorInput {
+  /** The locale whose catalog answers `t()`. */
+  readonly catalogLocale: string;
+  /** The locale handed to `Intl`; defaults to {@link TranslatorInput.catalogLocale}. */
+  readonly formattingLocale?: string;
+  /**
+   * The catalogs to walk, most-specific first. `@pithy-sh/i18n` passes adopter-locale, adopter-default,
+   * kit-locale, kit-default; a copied screen passes its own baked English and nothing else.
+   */
+  readonly layers: readonly (MessageCatalog | undefined)[];
+}
+
+/**
+ * A translator over `layers`.
+ *
+ * The `Intl` formatters are constructed lazily and held for the life of the translator. A translator is
+ * per request (or per mounted screen), so nothing here outlives a locale — which is the whole reason
+ * `z.config()` is banned repo-wide and a per-request global is not an option.
+ */
+export function createTranslator(input: TranslatorInput): Translator {
+  const catalogLocale = input.catalogLocale;
+  const formattingLocale = input.formattingLocale ?? catalogLocale;
+  const layers = input.layers;
+
+  let plurals: Intl.PluralRules | undefined;
+  const pluralRules = (): Intl.PluralRules => {
+    plurals ??= new Intl.PluralRules(catalogLocale);
+    return plurals;
+  };
+
+  const maybe = (key: string, params?: MessageParams): string | null => {
+    const message = lookupMessage(layers, key);
+    return message === null ? null : interpolate(message, params);
+  };
+
+  const translate = (key: string, params?: MessageParams): string => maybe(key, params) ?? key;
+
+  return {
+    catalogLocale,
+    formattingLocale,
+    direction: localeDirection(catalogLocale),
+    t: translate,
+    maybe,
+    plural(key, count, params) {
+      const category = pluralRules().select(count);
+      const withCount: MessageParams = { count, ...params };
+      const exact = lookupMessage(layers, `${key}.${category}`);
+      if (exact !== null) return interpolate(exact, withCount);
+      const other = lookupMessage(layers, `${key}.other`);
+      return other === null ? key : interpolate(other, withCount);
+    },
+    formatNumber(value, options) {
+      return new Intl.NumberFormat(formattingLocale, options).format(value);
+    },
+    formatCurrency(value, currency, options) {
+      return new Intl.NumberFormat(formattingLocale, { ...options, style: "currency", currency }).format(value);
+    },
+    formatDate(value, options) {
+      return new Intl.DateTimeFormat(formattingLocale, options).format(value);
+    },
+    formatList(values, options) {
+      return new Intl.ListFormat(formattingLocale, options).format(values);
+    },
+    formatRelativeTime(value, unit, options) {
+      return new Intl.RelativeTimeFormat(formattingLocale, options).format(value, unit);
+    },
+  };
+}
+
+/** The locale a project falls back to when nothing else answers, and the locale the kit writes in. */
+export const DEFAULT_LOCALE = "en";
+
+/**
+ * A translator over one baked catalog — **the seam's behavior when `@pithy-sh/i18n` is not composed.**
+ *
+ * This is what makes the capability optional. A project that never composes `i18n` renders the baked
+ * English fallback, byte for byte as it does today, with no negotiation, no merge and no config. A
+ * copied screen builds one from the English it was scaffolded with, which is the only catalog that
+ * survives being copied into an adopter's repository.
+ */
+export function bakedTranslator(catalog: MessageCatalog, locale: string = DEFAULT_LOCALE): Translator {
+  return createTranslator({ catalogLocale: locale, layers: [catalog] });
+}