@pithy-sh/i18n 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pithy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,17 @@
+# @pithy-sh/i18n
+
+Language for a Pithy app — negotiated per request, rendered through one seam. One piece of middleware. No tables, no migrations, no bindings, and no error codes of its own.
+
+It answers one question — *what language is this reader in?* — and hands every capability, every screen and every email a translator that already knows the answer.
+
+```sh
+pithy add i18n
+```
+
+**Documentation: [pithy.sh/docs/capabilities/i18n](https://pithy.sh/docs/capabilities/i18n).** Overview, adding it, using it, and the reference: the translator interface, catalog keys, layer order.
+
+_Everything else is on the site. `pithy.sh/docs` is canonical — new prose goes there, not here._
+
+## License
+
+MIT — adopter-side app value. The root `LICENSE` covers it.

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@pithy-sh/i18n",
+  "version": "0.1.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pithy-sh/pithy.git",
+    "directory": "packages/i18n"
+  },
+  "files": [
+    "src",
+    "pithy.manifest.json",
+    "!src/**/*.test.*"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    "./src/react/translator": "./src/react/translator.tsx",
+    "./src/*": "./src/*.ts"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json --noEmit false --outDir dist",
+    "typecheck": "tsc -p tsconfig.json && tsc -p tsconfig.browser.json",
+    "test": "vitest run",
+    "test:node": "vitest run --project=node --project=dom",
+    "test:workers": "vitest run --project=workers",
+    "clean": "rm -rf dist .turbo",
+    "reset": "bun run clean && rm -rf node_modules"
+  },
+  "dependencies": {
+    "@pithy-sh/core": "workspace:*",
+    "hono": "^4.13.2",
+    "zod": "^4.0.0"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@cloudflare/vitest-plugin": "^1.0.0",
+    "@pithy-sh/auth": "workspace:*",
+    "@pithy-sh/payments": "workspace:*",
+    "@pithy-sh/tsconfig": "workspace:*",
+    "@types/node": "^22.15.0",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "@vitest/coverage-v8": "^4.1.0",
+    "happy-dom": "^20.11.1",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.0",
+    "wrangler": "^4.115.0"
+  }
+}

package/pithy.manifest.json

@@ -0,0 +1,18 @@
+{
+  "name": "i18n",
+  "package": "@pithy-sh/i18n",
+  "requiredBindings": [],
+  "whenToEnable": "Enable it when your app serves readers in more than one language. It adds a translator seam every screen, error and email renders through, negotiates each reader's locale from the URL, their account, a cookie and Accept-Language, and formats dates, numbers and currency with Intl. Ships Spanish; add your own catalogs a sentence at a time.",
+  "scaffold": [
+    "Set `supportedLocales` to the languages you serve, least specific first — `es`, not `es-ES`.",
+    "Run `pithy doctor` to see which messages have no translation yet in each locale.",
+    "Override any kit sentence with one entry in `messages`; everything you do not mention keeps arriving with each release."
+  ],
+  "configOptions": [
+    {
+      "key": "defaultLocale",
+      "default": "en",
+      "describe": "The locale served when nothing else answers. Must be one of supportedLocales."
+    }
+  ]
+}

package/src/adapters/adapters.ts

@@ -0,0 +1,138 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { MessageParams } from "@pithy-sh/core/src/i18n/catalog";
+import { localeDirection } from "@pithy-sh/core/src/i18n/locale";
+import type { Translator } from "@pithy-sh/core/src/i18n/translator";
+import { createTranslator } from "@pithy-sh/core/src/i18n/translator";
+
+/**
+ * Adapters, so an adopter who already runs an i18n stack plugs it into the seam instead of migrating.
+ *
+ * **No runtime dependency on any of them, and none is possible here.** Each adapter takes the instance
+ * the adopter already constructed and duck-types the minimal shape it needs — three or four members,
+ * declared as a structural type in this file. Nothing is imported, nothing is installed, and a version
+ * of i18next that moved a method is a compile error in *their* repository rather than a broken
+ * dependency in ours.
+ *
+ * The shapes are minimal on purpose. An adapter that named every member of `i18next.TFunction` would
+ * break on a release that added one; naming only what is called means it keeps working across the
+ * versions that do not touch those three.
+ */
+
+/** Everything the wrapper needs, once the words are somebody else's problem. */
+interface Wrapping {
+  /** The locale whose catalog answers. */
+  readonly catalogLocale: string;
+  /** The locale handed to `Intl`. Defaults to the catalog locale. */
+  readonly formattingLocale?: string;
+  /** The other library's lookup, already bound to its own catalogs. */
+  readonly translate: (key: string, params?: MessageParams) => string;
+  /** The other library's plural lookup, when it has one worth using. */
+  readonly plural?: (key: string, count: number, params?: MessageParams) => string;
+}
+
+/**
+ * A `Translator` whose words come from `translate` and whose formatting comes from `Intl`.
+ *
+ * The formatting half is never delegated. Every one of these libraries formats through `Intl` anyway,
+ * workerd embeds full ICU, and a `Translator` that formatted through a wrapper would answer a
+ * different date for the same locale depending on which adapter was in use.
+ */
+function wrap(source: Wrapping): Translator {
+  const base = createTranslator({
+    catalogLocale: source.catalogLocale,
+    formattingLocale: source.formattingLocale,
+    layers: [],
+  });
+  const translate = (key: string, params?: MessageParams): string => source.translate(key, params);
+  return {
+    ...base,
+    direction: localeDirection(source.catalogLocale),
+    t: translate,
+    /**
+     * **A miss is the key coming back**, which is what every library this adapts already does:
+     * i18next returns the key, FormatJS returns the message id, Lingui returns the id.
+     *
+     * It has to be implemented here rather than inherited. `wrap` builds its base from
+     * `createTranslator` with **no layers**, so an inherited `maybe` answers `null` for everything —
+     * and `maybe` is the whole of the documented error contract, `t.maybe(code, params) ?? message`.
+     * Left inherited, every adapted translator silently rendered the English fallback for every code
+     * it could in fact translate, and nothing failed to say so.
+     */
+    maybe: (key, params) => {
+      const answered = translate(key, params);
+      return answered === key ? null : answered;
+    },
+    plural: (key, count, params) =>
+      source.plural ? source.plural(key, count, params) : translate(key, { count, ...params } satisfies MessageParams),
+  };
+}
+
+/** The part of an i18next instance this adapter calls. */
+export interface I18nextLike {
+  /** The active language tag. */
+  readonly language: string;
+  /** i18next's lookup. `count` in the options object is what drives its own plural selection. */
+  t(key: string, options?: Record<string, unknown>): string;
+}
+
+/**
+ * A `Translator` backed by an i18next instance.
+ *
+ * i18next selects plurals from a `count` option rather than from a key suffix, so `plural` hands it
+ * `count` and lets it choose — the kit's `<key>.<category>` convention is not imposed on a catalog
+ * i18next already owns.
+ */
+export function fromI18next(instance: I18nextLike, formattingLocale?: string): Translator {
+  return wrap({
+    catalogLocale: instance.language,
+    formattingLocale,
+    translate: (key, params) => instance.t(key, params),
+    plural: (key, count, params) => instance.t(key, { count, ...params }),
+  });
+}
+
+/** The part of a FormatJS / react-intl `IntlShape` this adapter calls. */
+export interface IntlShapeLike {
+  /** The active locale tag. */
+  readonly locale: string;
+  /** FormatJS's lookup, keyed by message id. */
+  formatMessage(descriptor: { id: string }, values?: Record<string, unknown>): string;
+}
+
+/**
+ * A `Translator` backed by a FormatJS / react-intl `IntlShape`.
+ *
+ * FormatJS resolves plurals inside the ICU message itself, so `plural` passes `count` as a value and
+ * lets the message's own `{count, plural, …}` arm decide.
+ */
+export function fromIntl(intl: IntlShapeLike, formattingLocale?: string): Translator {
+  return wrap({
+    catalogLocale: intl.locale,
+    formattingLocale,
+    translate: (key, params) => intl.formatMessage({ id: key }, params),
+  });
+}
+
+/** The part of a Lingui `I18n` instance this adapter calls. */
+export interface LinguiLike {
+  /** The active locale tag. */
+  readonly locale: string;
+  /** Lingui's lookup, keyed by message id. */
+  _(id: string, values?: Record<string, unknown>): string;
+}
+
+/**
+ * A `Translator` backed by a Lingui `I18n` instance.
+ *
+ * Lingui also resolves plurals inside the message, so this is the same shape as {@link fromIntl} — the
+ * two differ only in what the lookup is called.
+ */
+export function fromLingui(i18n: LinguiLike, formattingLocale?: string): Translator {
+  return wrap({
+    catalogLocale: i18n.locale,
+    formattingLocale,
+    translate: (key, params) => i18n._(key, params),
+  });
+}

package/src/browser/document.ts

@@ -0,0 +1,106 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { formattingLocaleOf, type LocaleContext, localeDirection } from "@pithy-sh/core/src/i18n/locale";
+import { matchLocale } from "@pithy-sh/core/src/i18n/match";
+import type { I18nClientProjection } from "../client/projection";
+import type { BrowserResolver } from "../config/config";
+import { recognizedResolvers } from "../resolve/browser";
+import { applyDocumentLocale } from "./signals";
+
+/**
+ * The document's opening language, negotiated from what `virtual:pithy/i18n` projects.
+ *
+ * **The entry point a scaffolded `client.tsx` calls, and the reason it is one line there.** A template
+ * is copied into an adopter's repository and never rewritten, so anything it does by hand is frozen on
+ * the day they scaffold. Two things in particular must not be: the guarded storage reads — `localStorage`
+ * throws in a private window, behind a site-data block, and inside some embedded views — and the chain
+ * order itself, which is the project's configuration rather than the front end's assumption.
+ *
+ * **It takes the projection, not an `I18nConfig`.** The projection is browser-safe by construction and
+ * is what a client actually holds: `browserResolvers` arrives as `string[]` because the generated
+ * ambient declaration in an adopter's Worker cannot name a type it does not import, so the chain is
+ * walked by name and an unrecognized link contributes nothing rather than throwing. `recognizedResolvers`
+ * is where that happens, once, for this pass and for `useNegotiatedLocale` both.
+ *
+ * **This is the first pass, not the decision.** It reaches only what a page can see before it renders:
+ * the URL, this device's memory, and whatever the server put on `<html lang>`. A signed-in reader's
+ * stored preference needs a session, which needs a render — `useNegotiatedLocale` picks that up and
+ * calls {@link applyDocumentLocale} again if it lands somewhere else. Doing it here as well is what
+ * keeps a right-to-left reader from watching the page reflow after the first paint.
+ *
+ * Answers **both** locales it resolved, or `null` when the capability is not composed and there was
+ * nothing to negotiate — a project without it keeps the `lang` its `index.html` shipped.
+ *
+ * **Both, and not the one tag `lang` carries.** This returned a single string at first, and the
+ * scaffolded provider then passed it as `catalogLocale` *and* `formattingLocale` — which is exactly the
+ * collapse the two-locale design exists to prevent, reintroduced in the one place a reader actually
+ * looks at a page. An `es-AR` visitor got Argentine dates from the Worker and Spanish-from-Spain dates
+ * from the SPA, on the same account, in the same session. The region survives here for the same reason
+ * `resolveChain` keeps it on the server: the range the reader asked for is a fact the match already
+ * knows, and throwing it away is a decision, not an omission.
+ */
+export function applyProjectedLocale(projection: I18nClientProjection): LocaleContext | null {
+  if (!projection.enabled) return null;
+  const wanted: string[] = [];
+  for (const resolver of recognizedResolvers(projection.browserResolvers)) {
+    const tag = signal(resolver, projection);
+    if (tag) wanted.push(tag);
+  }
+  const matched = matchLocale(wanted, projection.supportedLocales, projection.exceptions);
+  const catalogLocale = matched?.locale ?? projection.defaultLocale;
+  // The reader's own tag, canonicalized, when the range that matched is one `Intl` accepts — `es-ar`
+  // becomes `es-AR`. A range that is not a constructible tag (a wildcard, an exception-map key)
+  // formats as the catalog locale, which is the same rule the server chain applies.
+  const requested = matched ? formattingLocaleOf(matched.range) : null;
+  const resolved: LocaleContext = {
+    catalogLocale,
+    formattingLocale: requested ?? catalogLocale,
+    direction: localeDirection(catalogLocale),
+  };
+  applyDocumentLocale(resolved.catalogLocale, resolved.direction);
+  return resolved;
+}
+
+/**
+ * One link of the browser chain, by name.
+ *
+ * `account` answers nothing: there is no session before a render, and inventing one here would be a
+ * second source of truth for a fact `pithy_auth_users.locale` owns. It stays in the list so the
+ * configured order is walked whole, and so the link that follows it is still asked in its own place.
+ *
+ * Takes a `BrowserResolver` rather than a `string`, so the switch is exhaustive: `recognizedResolvers`
+ * has already dropped anything this build does not know, and a link added to the enum tomorrow is a red
+ * build here rather than a silently inert first paint.
+ */
+function signal(
+  resolver: BrowserResolver,
+  projection: Extract<I18nClientProjection, { enabled: true }>,
+): string | null {
+  switch (resolver) {
+    case "query":
+      return read(() => new URL(window.location.href).searchParams.get(projection.queryParam));
+    case "account":
+      return null;
+    case "storage":
+      return read(() => window.localStorage.getItem(projection.storageKey));
+    case "navigator":
+      // The pre-render pass takes only the reader's first choice: this runs before paint to keep an
+      // RTL page from reflowing, and each link here offers one range. The full weighted list is walked
+      // a moment later by `useNegotiatedLocale`, which can afford it.
+      return read(() => window.navigator.languages?.[0] ?? window.navigator.language ?? null);
+    case "server":
+      return read(() => document.documentElement.lang || null);
+    case "default":
+      return projection.defaultLocale;
+  }
+}
+
+/** Read a global, answering `null` rather than throwing when the global is absent or refuses. */
+function read(get: () => string | null): string | null {
+  try {
+    return get();
+  } catch {
+    return null;
+  }
+}

package/src/browser/signals.ts

@@ -0,0 +1,85 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { BrowserChain, BrowserLocaleSignals } from "../resolve/browser";
+
+/**
+ * The browser-side edge of locale resolution: the three signals a page can read for itself.
+ *
+ * **Separate from `resolve/browser.ts` on purpose.** That module is a pure function — signals in,
+ * locale out — so it typechecks and tests in the Worker program with no DOM library in scope. This one
+ * touches globals, so it lives in the browser program (`tsconfig.browser.json`) and nothing a Worker
+ * bundles can reach it. Effects at the edge; the decision in the middle.
+ */
+
+/**
+ * What the page can see: the query string, this device's memory, and what the server put on `<html lang>`.
+ *
+ * `account` is deliberately absent — the app knows whether someone is signed in and this function does
+ * not. Merge it in at the call site.
+ *
+ * **Every read is wrapped**, because two of the three throw in real browsers. `localStorage` raises in
+ * a private window, behind a site-data block, and in some embedded views; and during a server render
+ * there is no `window` or `document` at all. A reader whose browser refuses storage still gets a
+ * language — just not a remembered one.
+ *
+ * Takes the two names a page looks itself up by and nothing else, so the projection a browser holds and
+ * the config a Worker resolves both answer it without either being widened into the other.
+ */
+export function readBrowserSignals(config: Pick<BrowserChain, "queryParam" | "storageKey">): BrowserLocaleSignals {
+  return {
+    query: read(() => new URL(window.location.href).searchParams.get(config.queryParam)),
+    storage: read(() => window.localStorage.getItem(config.storageKey)),
+    // The reader's own preference order. Guarded like the rest: `navigator` is absent during a server
+    // render, and `languages` is absent in a few older browsers where `language` is the whole of it.
+    navigator: readList(() => [...(window.navigator.languages ?? [window.navigator.language])]),
+    server: read(() => document.documentElement.lang || null),
+  };
+}
+
+/** Remember `locale` on this device. Silent when storage is unavailable — a preference is not worth a throw. */
+export function rememberBrowserLocale(locale: string, config: Pick<BrowserChain, "storageKey">): void {
+  try {
+    window.localStorage.setItem(config.storageKey, locale);
+  } catch {
+    // A private window, a cleared site-data setting, a browser told to block storage. The reader still
+    // gets the language they asked for this visit; only the memory of it is lost.
+  }
+}
+
+/**
+ * Put `lang` and `dir` on the document.
+ *
+ * The one thing no catalog can do and every screen needs: assistive technology, hyphenation, and the
+ * browser's own text handling all read `lang`, and `dir` is what makes a right-to-left locale lay out
+ * at all. `templates/index.html` ships `lang="en"` as static text with no substitution token, so the
+ * script side is the only hook there is.
+ */
+export function applyDocumentLocale(locale: string, direction: "ltr" | "rtl"): void {
+  try {
+    document.documentElement.lang = locale;
+    document.documentElement.dir = direction;
+  } catch {
+    // No document — a server render, or a test environment without one. Nothing to set and nothing
+    // to report: the markup a server render produces carries the same two attributes already.
+  }
+}
+
+/** Read a list off a global, answering `null` rather than throwing when the global is absent. */
+function readList(get: () => string[]): string[] | null {
+  try {
+    const list = get().filter((tag) => typeof tag === "string" && tag.trim().length > 0);
+    return list.length > 0 ? list : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Read a global, answering `null` rather than throwing when the global is absent or refuses. */
+function read(get: () => string | null): string | null {
+  try {
+    return get();
+  } catch {
+    return null;
+  }
+}

package/src/capability.ts

@@ -0,0 +1,141 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { type Capability, defineCapability } from "@pithy-sh/core/src/capability/capability";
+import type { LocaleCatalogs, MessageCatalog } from "@pithy-sh/core/src/i18n/catalog";
+import { composeMessages } from "@pithy-sh/core/src/i18n/registry";
+import { DEFAULT_LOCALE } from "@pithy-sh/core/src/i18n/translator";
+import { KIT_CATALOGS } from "./catalogs/kit";
+import type { I18nClientProjection } from "./client/projection";
+import { I18nConfig, type I18nConfigInput } from "./config/config";
+import { i18nMiddleware } from "./http/middleware";
+import { i18nSettings } from "./settings/coverage";
+import { PACKAGE_VERSION } from "./version.generated";
+
+/**
+ * The i18n capability, with its resolved config and the catalogs it composed attached for inspection.
+ *
+ * The composed catalogs are populated by the `compose` hook rather than at construction, because a
+ * capability sees only itself when it is constructed and the kit's English lives on the capabilities
+ * that own it.
+ */
+export interface I18nCapability extends Capability {
+  /** The validated config, for `@pithy-sh/ui-react` and anything else that needs the negotiated set. */
+  i18nConfig: I18nConfig;
+  /** Every composed capability's English, merged under the domain rule. Empty until `compose` runs. */
+  composedMessages: LocaleCatalogs;
+  /** The catalog layers `t()` walks for `locale`, most-specific first. */
+  layersFor(locale: string): readonly (MessageCatalog | undefined)[];
+}
+
+/**
+ * The i18n capability.
+ *
+ * **Stateless, like `@pithy-sh/turnstile`** — no tables, no migrations, no `<NAME>_MIGRATION_ORDER`, no
+ * error codes, no bindings of its own. It contributes one middleware, which resolves the request's
+ * locale and replaces `c.var.t` with a translator over the merged catalogs.
+ *
+ * It declares no error codes deliberately. The moment an `i18n/*` code entered `KitErrorPayload` the
+ * whole `i18n` domain would be reserved against adopters, and `i18n` is a generic enough word that
+ * somebody has already defined `i18n/missing_catalog` through `defineErrorPayload`. Nothing here needs
+ * a code that `core/*` and `validation/*` do not already carry.
+ *
+ * ## What the layers are, and why the order is this
+ *
+ * `t(key)` walks, per key, in this order:
+ *
+ * 1. the adopter's catalog for the resolved locale,
+ * 2. the adopter's catalog for the project default,
+ * 3. **the kit's translation** for the resolved locale — the `es` this package ships,
+ * 4. every composed capability's English, for the resolved locale,
+ * 5. every composed capability's copy for the project default,
+ * 6. and their English, which is the language the kit is written in.
+ *
+ * Per key, never per catalog: overriding one sentence is one entry, and every key an adopter did not
+ * mention keeps flowing from the package. That is what makes an override a merge rather than a fork,
+ * and it is why kit catalogs are never copied into an adopter's repository.
+ *
+ * Errors are not in any of those layers and do not need to be: the payload already carries its English
+ * `message`, and a translating client renders `t.maybe(payload.code, payload.params) ?? payload.message`. So
+ * the kit ships translations for the 120 codes and no English duplicate of what is already on the wire.
+ */
+export function i18n(config: I18nConfigInput = {}): I18nCapability {
+  const resolved = I18nConfig.parse(config);
+  let composedMessages: LocaleCatalogs = {};
+
+  const layersFor = (locale: string): readonly (MessageCatalog | undefined)[] => [
+    resolved.messages[locale],
+    resolved.messages[resolved.defaultLocale],
+    KIT_CATALOGS[locale],
+    composedMessages[locale],
+    composedMessages[resolved.defaultLocale],
+    // **The source language, explicitly, and last.** This was `catalogFor(composedMessages, default)`,
+    // which answers `catalogs[default] ?? catalogs.en` — so it only ever reached English because no
+    // capability had contributed a non-`en` locale. `@pithy-sh/email` does now (#442), which made the
+    // fallback silently stop existing for any project whose `defaultLocale` is not `en`: layers 5 and
+    // 6 collapsed into the same Spanish map, and an adopter's own English-only key rendered as its raw
+    // key on a Spanish page. English is the language the kit is written in, so it is a layer of its
+    // own rather than something another layer resolves to by coincidence.
+    composedMessages[DEFAULT_LOCALE],
+  ];
+
+  const capability = defineCapability({
+    name: "i18n",
+    // The package version this capability ships at, stamped by `scripts/stampVersions.ts` — a Worker
+    // cannot read its own package.json. Reported per capability by the control-plane manifest.
+    version: PACKAGE_VERSION,
+    config: I18nConfig,
+    /**
+     * Merge every composed capability's English once, at assembly.
+     *
+     * Here rather than at construction because a capability sees only itself when it is built, and the
+     * kit's English is contributed by the capabilities that own it — `@pithy-sh/email`'s template copy
+     * under `email/`, an adopter's own `app` capability under theirs. `composeMessages` enforces that
+     * each may only write keys under its own domain.
+     */
+    compose: ({ capabilities }) => {
+      composedMessages = composeMessages(capabilities);
+    },
+    middleware: [i18nMiddleware(resolved, layersFor)],
+    /**
+     * Locale **metadata**, never catalogs. `renderVirtualModule` inlines this as a `JSON.stringify`
+     * literal in the main chunk, so a catalog here would be downloaded by every reader in every
+     * language before first paint and would defeat the per-locale splitting the design rests on.
+     *
+     * The return type is {@link I18nClientProjection} — declared, not inferred, so a dropped field is a
+     * compile error here rather than a browser's problem.
+     */
+    client: (): I18nClientProjection => ({
+      enabled: true,
+      supportedLocales: [...resolved.supportedLocales],
+      defaultLocale: resolved.defaultLocale,
+      queryParam: resolved.queryParam,
+      storageKey: resolved.storageKey,
+      browserResolvers: [...resolved.browserResolvers],
+      exceptions: { ...resolved.exceptions },
+    }),
+    /**
+     * Catalog coverage, as `pithy doctor`'s local tier rather than as a `pithy i18n check` command.
+     *
+     * It is offline, project-file-only, and a local finding already fails `doctor`'s exit code — which
+     * is exactly what the command would have been, at the cost of a new page in `docs/commands/`, a
+     * row in five exact-count CLI gates, and a byte-pinned re-paste of `pithy --help`.
+     */
+    settings: i18nSettings(resolved, () => composedMessages),
+    requiredBindings: [],
+  });
+
+  const composed = Object.assign(capability, { i18nConfig: resolved, layersFor });
+  // `composedMessages` is defined on the target rather than declared in the literal above, and that is
+  // not a style choice. `Object.assign` **reads** an accessor on its source and copies the value it
+  // returned, so a `get composedMessages()` in that literal would be evaluated once — before `compose`
+  // has run — and every reader would see the empty object it held at construction, permanently.
+  // Defined here it stays an accessor over the live binding, which is what the interface promises.
+  Object.defineProperty(composed, "composedMessages", { get: () => composedMessages, enumerable: true });
+  return composed as I18nCapability;
+}
+
+/** Whether a capability is the i18n capability — carries its resolved config and composed catalogs. */
+export function isI18nCapability(capability: Capability): capability is I18nCapability {
+  return capability.name === "i18n" && "i18nConfig" in capability;
+}

package/src/catalogs/browser.ts

@@ -0,0 +1,39 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { MessageCatalog } from "@pithy-sh/core/src/i18n/catalog";
+
+/**
+ * The kit's catalogs, as one dynamic import per locale.
+ *
+ * **A static map of thunks, not a computed specifier.** `import(\`./es/${locale}\`)` is a specifier no
+ * bundler can resolve, so it either fails the build or pulls every match into one chunk; written out,
+ * Rollup emits exactly one chunk per locale and a reader downloads only their own. That is the whole
+ * reason catalogs are not on the `virtual:pithy/i18n` projection, which `renderVirtualModule` inlines
+ * as a `JSON.stringify` literal into the main chunk.
+ *
+ * English is absent for the same reason it is absent from {@link KIT_CATALOGS}: a copied screen already
+ * carries the English it was scaffolded with, and that is the only catalog that survives being copied.
+ */
+const LOADERS: Record<string, () => Promise<MessageCatalog>> = {
+  es: () => import("./es/index").then((module) => module.es),
+};
+
+/**
+ * Whether the kit ships a catalog for `locale`. English answers `false` — it is the baked fallback.
+ *
+ * **`Object.hasOwn`, never `in`.** The argument is a language tag, and a language tag is whatever a
+ * reader put after `?lang=`. `"__proto__" in LOADERS` is `true` — the accessor is on `Object.prototype`
+ * — so `in` answered yes for a locale the kit has never written, and {@link loadKitCatalog} then read
+ * `Object.prototype` back as a loader and called it.
+ */
+export function hasKitCatalog(locale: string): boolean {
+  return Object.hasOwn(LOADERS, locale);
+}
+
+/** The kit's catalog for `locale`, or an empty one when the kit writes nothing in that language. */
+export async function loadKitCatalog(locale: string): Promise<MessageCatalog> {
+  if (!hasKitCatalog(locale)) return {};
+  const load = LOADERS[locale];
+  return load ? await load() : {};
+}