@pithy-sh/i18n 0.1.0

package/src/http/middleware.ts

@@ -0,0 +1,125 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { PithyMiddleware } from "@pithy-sh/core/src/capability/capability";
+import type { MessageCatalog } from "@pithy-sh/core/src/i18n/catalog";
+import { createTranslator, type Translator } from "@pithy-sh/core/src/i18n/translator";
+import { getCookie } from "hono/cookie";
+import type { I18nConfig } from "../config/config";
+import type { ResolvedLocale } from "../resolve/chain";
+import { resolveServerLocale } from "../resolve/server";
+
+/** How a request's locale is looked up, given the locale that won. Supplied by the capability. */
+export type LayersFor = (locale: string) => readonly (MessageCatalog | undefined)[];
+
+/**
+ * The one middleware this capability contributes: resolve the request's locale, and put a real
+ * translator on it.
+ *
+ * It **replaces** `c.var.t` rather than filling a null. Core seeds a translator over the baked English
+ * for every request whether or not this capability is composed, which is what lets every capability
+ * call `c.var.t(...)` with no null check, and what makes a project that never opts in behave byte for
+ * byte as it did before.
+ *
+ * A fresh translator per request, never a cached one. A Worker isolate is reused across requests from
+ * different readers, so anything holding a locale across that boundary applies request A's language to
+ * request B. It is the same hazard `z.config()` is banned repo-wide for, and it is why the `Intl`
+ * formatters are held on the translator — which lives and dies with one request — rather than in a
+ * module-level cache.
+ *
+ * ## Why the query string is read off the URL here, and not through `zValidator`
+ *
+ * §HTTP's rule is that a route declares its request contract on the route line and a handler reads
+ * `c.req.valid(target)`; `plugins/no-raw-request-input.grit` enforces it by making the raw accessors
+ * unreadable under every capability's `src/http/` tree. This is a **global middleware over every route**, so there
+ * is no route line to declare a validator on and no handler to hand a typed value to — the rule's
+ * replacement does not exist at this position.
+ *
+ * What the rule is *for* still holds, and it holds structurally rather than by care: the value is one
+ * language range among four sources, every one of them is matched against `config.supportedLocales`
+ * before anything is done with it, and a range that matches nothing falls through to the next link.
+ * Nothing downstream ever sees a string this middleware did not already find in the project's own
+ * configured set. A reader who sends `?lang=<script>` gets the default locale.
+ */
+export function i18nMiddleware(config: I18nConfig, layersFor: LayersFor): PithyMiddleware {
+  return (app) => {
+    app.use("*", async (c, next) => {
+      // **Resolved on first read, not here, and that is what makes the `user` link work at all.**
+      //
+      // `createBackend` applies each capability's middleware in composition order — the order an
+      // adopter happened to list them in `pithy.config.ts`. Resolving eagerly therefore reads
+      // `c.var.auth` before `@pithy-sh/auth` has filled it whenever i18n is listed first, and the
+      // reader's stored language is silently dropped for half of all projects. Nothing fails; the
+      // chain just quietly becomes `param → cookie → header → default`.
+      //
+      // Both are `app.use("*")`, so both have run by the time any handler reads `c.var.t`. Deferring
+      // the resolution to that first read makes the answer identical in either order, which is a
+      // property rather than a convention — there is no ordering left to get wrong.
+      let resolved: ResolvedLocale | undefined;
+      const locale = (): ResolvedLocale =>
+        (resolved ??= resolveServerLocale(
+          {
+            param: queryParam(c.req.url, config.queryParam),
+            // The reader's own stored choice, off the row the session lookup already loaded.
+            user: c.var.auth?.locale ?? null,
+            cookie: getCookie(c, config.cookie) ?? null,
+            header: c.req.header("accept-language") ?? null,
+          },
+          config,
+        ));
+
+      let translator: Translator | undefined;
+      const t = (): Translator =>
+        (translator ??= createTranslator({
+          catalogLocale: locale().catalogLocale,
+          formattingLocale: locale().formattingLocale,
+          layers: layersFor(locale().catalogLocale),
+        }));
+
+      c.set("locale", {
+        get catalogLocale() {
+          return locale().catalogLocale;
+        },
+        get formattingLocale() {
+          return locale().formattingLocale;
+        },
+        get direction() {
+          return locale().direction;
+        },
+      });
+
+      // Every member delegates, so nothing is negotiated for a request that renders no copy — a health
+      // check and a webhook pay nothing for a capability the rest of the Worker composes.
+      c.set("t", {
+        get catalogLocale() {
+          return t().catalogLocale;
+        },
+        get formattingLocale() {
+          return t().formattingLocale;
+        },
+        get direction() {
+          return t().direction;
+        },
+        t: (key, params) => t().t(key, params),
+        maybe: (key, params) => t().maybe(key, params),
+        plural: (key, count, params) => t().plural(key, count, params),
+        formatNumber: (value, options) => t().formatNumber(value, options),
+        formatCurrency: (value, currency, options) => t().formatCurrency(value, currency, options),
+        formatDate: (value, options) => t().formatDate(value, options),
+        formatList: (values, options) => t().formatList(values, options),
+        formatRelativeTime: (value, unit, options) => t().formatRelativeTime(value, unit, options),
+      } satisfies Translator);
+
+      await next();
+    });
+  };
+}
+
+/** One query parameter off a request URL, or `null` — total, so a URL Hono accepted cannot throw here. */
+function queryParam(url: string, name: string): string | null {
+  try {
+    return new URL(url).searchParams.get(name);
+  } catch {
+    return null;
+  }
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * The package entrypoint — the surface `pithy add i18n` wires into `pithy.config.ts`. Deliberately
+ * narrow: the capability factory plus the config types an app declares.
+ *
+ * The React bindings are a first-class public API of this package and are imported by deep path
+ * (`@pithy-sh/i18n/src/react/translator`) at the component that mounts them — the documented contract,
+ * not a barrel over the package, and what keeps `react` off the Worker program's import graph. The
+ * adapters (`@pithy-sh/i18n/src/adapters/*`) and the browser helpers
+ * (`@pithy-sh/i18n/src/browser/signals`) are reached the same way.
+ *
+ * `Translator` itself lives in `@pithy-sh/core/src/i18n/translator` and is importable **without
+ * composing this capability**, so an adopter's own module can type against the seam whether or not
+ * they ever opt in.
+ */
+
+export { type I18nCapability, i18n, isI18nCapability } from "./capability";
+export { BrowserResolver, type I18nConfig, type I18nConfigInput, ServerResolver } from "./config/config";

package/src/react/translator.tsx

@@ -0,0 +1,133 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { interpolate, type MessageCatalog } from "@pithy-sh/core/src/i18n/catalog";
+import type { Translator } from "@pithy-sh/core/src/i18n/translator";
+import { bakedTranslator, createTranslator } from "@pithy-sh/core/src/i18n/translator";
+import { createContext, type ReactNode, useContext, useMemo } from "react";
+
+/**
+ * The React bindings — **a first-class public API of this package**, not something the kit's own
+ * templates happen to import.
+ *
+ * An adopter rendering entirely their own screens has to be able to consume the seam without ever
+ * touching a kit template, and after the first day most of them are: the screens are *copied*, so
+ * `pithy ui add` reaches a project scaffolded after this landed and no command retrofits one that was
+ * not. The seam is what an already-scaffolded adopter consumes. So this is the deliverable, and the
+ * templates are one of its consumers.
+ */
+
+/**
+ * What the provider carries: the two locales, and the catalog layers to walk.
+ *
+ * **The pieces, not a finished `Translator`.** A screen supplies the English it was scaffolded with as
+ * a final fallback layer, and that layer can only be appended if the layers are still a list. Handing
+ * the context a built translator would make a screen's own English unreachable — which is the one
+ * thing that has to keep working, because it is the only catalog that survives being copied.
+ */
+export interface TranslatorSource {
+  /** The locale whose catalog answers `t()`. */
+  readonly catalogLocale: string;
+  /** The locale handed to `Intl`. May be more specific than the catalog locale — `es-AR` over `es`. */
+  readonly formattingLocale: string;
+  /** The catalogs to walk, most-specific first: the adopter's, then the kit's translation. */
+  readonly layers: readonly (MessageCatalog | undefined)[];
+}
+
+/**
+ * What a provider may be given: the pieces, or a translator somebody else already built.
+ *
+ * The second arm is what makes the adapters reachable. `fromI18next`, `fromIntl` and `fromLingui`
+ * return a `Translator` — an adopter's whole message layer, already resolved — and with only the
+ * pieces arm they had nowhere to go: an adapted translator could be passed screen by screen as a `t`
+ * prop, and `useTranslator()` in the adopter's *own* components would never see it. A stack you plug
+ * in that only half the tree can read is not plugged in.
+ */
+export type TranslatorValue = TranslatorSource | Translator;
+
+const TranslatorContext = createContext<TranslatorValue | null>(null);
+
+/** Whether a provider was handed the pieces rather than a finished translator. */
+function isSource(value: TranslatorValue): value is TranslatorSource {
+  return "layers" in value;
+}
+
+/**
+ * `primary` first, then `fallback` — the screen's own English behind somebody else's message layer.
+ *
+ * Built by delegation rather than by spreading `primary`, because a `Translator` may carry getters
+ * (the request-scoped one does) and spreading would evaluate them once, here, freezing the answer.
+ *
+ * `t` and `maybe` consult the fallback because `maybe` is exactly the miss signal they need. `plural`
+ * has a weaker one — it answers the key on a miss, which is the documented contract — so it falls back
+ * only when it sees that, and an adapter whose library selects plurals itself (i18next does) keeps
+ * answering for every key it knows.
+ */
+function overlay(primary: Translator, fallback: MessageCatalog): Translator {
+  const own = (key: string, params?: Parameters<Translator["t"]>[1]): string | null =>
+    Object.hasOwn(fallback, key) ? interpolate(fallback[key] as string, params) : null;
+  return {
+    catalogLocale: primary.catalogLocale,
+    formattingLocale: primary.formattingLocale,
+    direction: primary.direction,
+    t: (key, params) => primary.maybe(key, params) ?? own(key, params) ?? key,
+    maybe: (key, params) => primary.maybe(key, params) ?? own(key, params),
+    plural: (key, count, params) => {
+      const answered = primary.plural(key, count, params);
+      if (answered !== key) return answered;
+      const withCount = { count, ...params };
+      return own(`${key}.other`, withCount) ?? own(key, withCount) ?? key;
+    },
+    formatNumber: (value, options) => primary.formatNumber(value, options),
+    formatCurrency: (value, currency, options) => primary.formatCurrency(value, currency, options),
+    formatDate: (value, options) => primary.formatDate(value, options),
+    formatList: (values, options) => primary.formatList(values, options),
+    formatRelativeTime: (value, unit, options) => primary.formatRelativeTime(value, unit, options),
+  };
+}
+
+/** Mount a resolved locale over a subtree. Everything under it reads the same translator. */
+export function TranslatorProvider({ value, children }: { value: TranslatorValue; children: ReactNode }) {
+  return <TranslatorContext.Provider value={value}>{children}</TranslatorContext.Provider>;
+}
+
+/**
+ * The translator for this subtree, with `fallback` as its last layer.
+ *
+ * **Never throws when there is no provider**, and that is deliberate rather than lenient. A screen
+ * copied into an adopter's repository renders in a project that may not compose `i18n` at all, and in
+ * that project it must render the English it was scaffolded with, byte for byte. With no provider this
+ * is exactly a `bakedTranslator` over `fallback` — no negotiation, no merge, no config.
+ *
+ * With a provider, `fallback` goes **last**: the adopter's own catalog, then the kit's translation,
+ * then the screen's baked English. So a key nobody translated still renders a sentence.
+ *
+ * That holds for a provider given a finished `Translator` too — an adapted i18next, FormatJS or Lingui
+ * instance answers first and the screen's own English is behind it, so plugging your stack in never
+ * costs you the sentences the kit already wrote.
+ */
+export function useTranslator(fallback?: MessageCatalog): Translator {
+  const source = useContext(TranslatorContext);
+  return useMemo(() => {
+    if (!source) return bakedTranslator(fallback ?? {});
+    if (!isSource(source)) return fallback ? overlay(source, fallback) : source;
+    return createTranslator({
+      catalogLocale: source.catalogLocale,
+      formattingLocale: source.formattingLocale,
+      layers: fallback ? [...source.layers, fallback] : source.layers,
+    });
+  }, [source, fallback]);
+}
+
+/**
+ * The prop every screen that renders copy takes.
+ *
+ * Optional, and injected the same way `fetch` and `redirect` already are on the kit's screens: a
+ * rendered fact no assertion about source text can reach is what earns a prop there, and a
+ * locale-dependent render is exactly that. A screen with no `t` passed reads the context, and with no
+ * context reads its own English.
+ */
+export interface TranslatorProp {
+  /** The translator this screen renders through. Defaults to the context, then to the baked English. */
+  t?: Translator;
+}

package/src/react/useNegotiatedLocale.ts

@@ -0,0 +1,198 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { MessageCatalog } from "@pithy-sh/core/src/i18n/catalog";
+import { localeDirection } from "@pithy-sh/core/src/i18n/locale";
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { applyDocumentLocale, readBrowserSignals, rememberBrowserLocale } from "../browser/signals";
+import { loadKitCatalog } from "../catalogs/browser";
+import type { I18nClientProjection } from "../client/projection";
+import { resolveBrowserLocale } from "../resolve/browser";
+import type { TranslatorSource } from "./translator";
+
+/** What the hook hands back: what to mount, what was chosen, and how to choose again. */
+export interface NegotiatedLocale {
+  /**
+   * Pass this straight to `TranslatorProvider`. `null` until the locale's catalog has loaded — and
+   * permanently `null` for a project with no `i18n` composed, which is the same branch and needs no
+   * second one: render the children untouched and every screen keeps its baked English.
+   */
+  readonly source: TranslatorSource | null;
+  /** The catalog locale in force — the words the app has. */
+  readonly locale: string;
+  /** Choose a language. Remembers it on this device and puts `lang`/`dir` on the document. */
+  readonly choose: (locale: string) => void;
+}
+
+/** What the caller knows that the browser cannot work out for itself. */
+export interface NegotiatedLocaleOptions {
+  /** The signed-in reader's stored locale, when the app knows it. Outranks this device's memory. */
+  readonly account?: string | null;
+  /** The adopter's own catalogs, keyed by locale — the top layer, above the kit's translation. */
+  readonly messages?: Readonly<Record<string, MessageCatalog | undefined>>;
+  /**
+   * Write a signed-in reader's choice through to their account. Omit it and a choice is remembered on
+   * this device only.
+   *
+   * **A seam rather than something this package does for you, because it cannot.** `pithy_auth_users.locale`
+   * is written through `updateUser` (`@pithy-sh/auth/src/client/api`) — a call `@pithy-sh/auth` owns and
+   * this package never imports. What it can do is call you at the moment the choice is made.
+   *
+   * It matters more than a convenience: `account` outranks `storage` in the browser chain precisely so
+   * a reader who picks Spanish on their phone is not reading French on their laptop. Without the
+   * write-through, that ordering describes a value nothing updates, and the second device keeps
+   * answering from its own older memory forever. Pass this whenever a reader is signed in.
+   *
+   * **Failures are yours to handle, inside this function.** It is called and not awaited, and a
+   * rejection is caught rather than reported: the reader already has the language they asked for and
+   * the device already remembers it, so a failed preference write must not become an unhandled
+   * rejection in their console or an error in your Worker. If a dropped write is worth knowing about,
+   * catch it here where you know what your API meant.
+   */
+  readonly persist?: (locale: string) => void | Promise<void>;
+}
+
+/**
+ * What `locale` answers, and what nothing writes to the document, when the capability is not composed.
+ *
+ * The kit writes in English and a scaffolded `templates/index.html` ships `lang="en"` as static text —
+ * so this is both the language on screen and the tag already on the document. Nothing negotiated it,
+ * which is exactly why the document is left alone rather than restamped with it.
+ */
+const UNNEGOTIATED_LOCALE = "en";
+
+/**
+ * Negotiate the reader's locale in the browser, load that locale's catalog, and keep the document in
+ * step.
+ *
+ * **It takes what a browser holds.** `projection` is `virtual:pithy/i18n` — locale metadata and nothing
+ * else — so a screen reads the chain order **this project** configured rather than one the front end
+ * assumed, and no page is asked for the catalogs, the cookie name or the server chain that only a
+ * Worker has. Your own catalogs reach it through `options.messages`, above the kit's translation.
+ *
+ * The catalog arrives by dynamic import, one Vite chunk per locale, so a reader downloads only their
+ * own language. Until it lands, `source` is `null` and every screen renders the English it was
+ * scaffolded with — which is the right thing to show for the handful of milliseconds involved, and is
+ * also exactly what a reader in the default locale sees permanently.
+ *
+ * **`{ enabled: false }` is an answer, not an error, and it costs the caller no branch of its own.** A
+ * project that never composed `i18n` projects it, and the hook then negotiates nothing, downloads no
+ * chunk, writes nothing to `localStorage`, and leaves the `lang` `index.html` declared exactly where it
+ * is: `source` stays `null` permanently, `locale` is `en`, and `choose` does nothing. `source === null`
+ * is the same null a caller already renders through while a catalog is in flight — so the screen shows
+ * the English it was scaffolded with, byte for byte as it did before any of this landed, and removing
+ * the capability puts the app back where it started.
+ */
+export function useNegotiatedLocale(
+  projection: I18nClientProjection,
+  options: NegotiatedLocaleOptions = {},
+): NegotiatedLocale {
+  // Narrowed once, at the top. `null` is the whole of what "the capability is not composed" means here,
+  // and every hook below runs either way and answers for it rather than being skipped — a hook behind a
+  // condition is the one thing React does not allow.
+  const config = projection.enabled ? projection : null;
+  // The same fact as a boolean, and the two effects below depend on **this** rather than on `config`.
+  // Composed, `config` is `projection` under another name, so its identity is the caller's — and a
+  // caller is free to hand the hook a fresh object every render (`{ ...i18nConfig }`, or a parse in a
+  // component body). An effect keyed on that identity re-runs on every render; the catalog effect sets
+  // state, so it re-renders itself, forever, with no error anywhere to read. Both effects want nothing
+  // from `config` but whether it is there, and a boolean is stable by value however the caller spells
+  // its projection.
+  const enabled = projection.enabled;
+
+  const resolved = useMemo(
+    () =>
+      config === null
+        ? null
+        : resolveBrowserLocale({ ...readBrowserSignals(config), account: options.account }, config),
+    [config, options.account],
+  );
+  const [chosen, setChosen] = useState<string | null>(null);
+  const [kit, setKit] = useState<{ locale: string; catalog: MessageCatalog } | null>(null);
+
+  const locale = chosen ?? resolved?.catalogLocale ?? UNNEGOTIATED_LOCALE;
+  // A chosen locale is a catalog locale, so it carries no region; the negotiated one may be more
+  // specific than the catalog it reads, and that specificity is what `Intl` should keep.
+  const formattingLocale = chosen ?? resolved?.formattingLocale ?? UNNEGOTIATED_LOCALE;
+  // The project's default locale, whose layer catches a key the reader's own locale has not
+  // translated. `en` when nothing is composed — both the language on screen and the only layer a
+  // project without the capability could mean.
+  const defaultLocale = config?.defaultLocale ?? UNNEGOTIATED_LOCALE;
+
+  useEffect(() => {
+    // No chunk is asked for at all with the capability uncomposed, and that is the whole of what keeps
+    // `source` null there: `kit` never arrives, so the memo below has nothing to mount and the caller
+    // renders through the same null it already renders through while a catalog is in flight.
+    if (!enabled) return;
+    let live = true;
+    loadKitCatalog(locale)
+      .then((catalog) => {
+        if (live) setKit({ locale, catalog });
+      })
+      // A per-locale chunk that will not load — a 404 after a deploy, an offline tab — must not leave
+      // the provider unmounted forever with `lang` already changed on the document. That is the
+      // "declares a language it does not speak" failure by another road: a screen reader believes the
+      // attribute and mispronounces English. An empty catalog mounts the provider, so every screen
+      // falls through to the English it was scaffolded with, which is what is actually on screen.
+      .catch(() => {
+        if (live) setKit({ locale, catalog: {} });
+      });
+    return () => {
+      live = false;
+    };
+  }, [enabled, locale]);
+
+  // Derived from the locale in force, never taken off `resolved`. `resolveBrowserLocale` answers for
+  // what the *chain* negotiated, and `choose` moves past it: a reader who picks Arabic from a language
+  // menu on an English page would otherwise be served `lang="ar" dir="ltr"` — the words right and the
+  // layout backwards, which is the one failure a suite that only reads sentences cannot see. Same
+  // derivation the chain itself uses (`localeDirection(match.locale)`), so the negotiated path is
+  // byte-identical to what it answered before.
+  const direction = localeDirection(locale);
+
+  useEffect(() => {
+    // Nothing negotiated it, so nothing declares it. A project without the capability keeps the `lang`
+    // its `index.html` shipped — restamping the document with a locale no chain chose would be the
+    // "declares a language it does not speak" failure with the negotiation removed rather than added.
+    if (!enabled) return;
+    applyDocumentLocale(locale, direction);
+  }, [enabled, locale, direction]);
+
+  const persist = options.persist;
+  const choose = useCallback(
+    (next: string) => {
+      // No languages to choose between, and no `storageKey` to remember one under.
+      if (config === null) return;
+      if (!config.supportedLocales.includes(next)) return;
+      // The device first, always: it is synchronous, it cannot fail in a way worth waiting for, and it
+      // is what answers on the next visit if the account write does not land.
+      rememberBrowserLocale(next, config);
+      setChosen(next);
+      // Then the account, when the app knows who is reading. Not awaited — a language switch is a
+      // render, not a round trip, and nothing on screen should wait for a preference.
+      //
+      // **Caught, and that is not the same as swallowed by accident.** An unawaited promise that
+      // rejects is an unhandled rejection: noise in a browser console, and a reported error in a
+      // Worker. A failed preference write must not do either, because the reader already has the
+      // language they asked for and the device already remembers it. Whether that failure is worth
+      // reporting is a question about the adopter's own API, so it is answered inside `persist`.
+      Promise.resolve(persist?.(next)).catch(() => undefined);
+    },
+    [config, persist],
+  );
+
+  const source = useMemo<TranslatorSource | null>(() => {
+    // Only once the catalog for *this* locale has landed. Mounting the previous locale's catalog under
+    // the new locale's tag is a page that says it is Spanish and reads English. This is also the one
+    // test the uncomposed case has to pass: nothing ever loads a catalog there, so `kit` stays null
+    // and no provider is ever mounted over screens already rendering their baked English.
+    if (kit?.locale !== locale) return null;
+    return {
+      catalogLocale: locale,
+      formattingLocale,
+      layers: [options.messages?.[locale], options.messages?.[defaultLocale], kit.catalog],
+    };
+  }, [kit, locale, formattingLocale, options.messages, defaultLocale]);
+
+  return { source, locale, choose };
+}

package/src/resolve/browser.ts

@@ -0,0 +1,122 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { BrowserResolver } from "../config/config";
+import { type LocaleSet, type ResolvedLocale, type ResolverLink, resolveChain, tagLink } from "./chain";
+
+/**
+ * What the browser side of this package reads: the languages, the chain order, and the two names a page
+ * looks itself up by.
+ *
+ * **The shape `I18nClientProjection` and `I18nConfig` both already are.** The browser holds the
+ * projection — locale metadata and nothing else, no catalogs, no cookie name, no server chain — so
+ * asking a page for an `I18nConfig` asks it for three fields it has no business knowing, and every
+ * adopter widens one into the other the same five ways. Declaring what is actually read costs nothing
+ * on the server, where the resolved config satisfies it as it stands.
+ *
+ * `browserResolvers` is `readonly string[]` for the same reason the projection's is: the ambient
+ * declaration `pithy ui add react` copies into an adopter's Worker cannot name a type it does not
+ * import. The chain is walked by name — see {@link recognizedResolvers}.
+ */
+export interface BrowserChain extends LocaleSet {
+  /** The query parameter an explicit choice arrives on — `?lang=es`. */
+  readonly queryParam: string;
+  /** The `localStorage` key this device's remembered locale is written under. */
+  readonly storageKey: string;
+  /** The browser chain, in the order it is asked. Names this build does not know contribute nothing. */
+  readonly browserResolvers: readonly string[];
+}
+
+/**
+ * Every link this build knows, as a record rather than a list.
+ *
+ * **A record so a new `BrowserResolver` cannot be forgotten here.** Adding a member to the enum leaves
+ * this object missing a property, which is a red build — the same guarantee the exhaustive switch in
+ * {@link linkFor} gives, in the one place a `string[]` has to be turned back into enum members.
+ *
+ * Written out rather than read off `BrowserResolver.options`, and that is a bundle decision, not a
+ * preference. `config/config.ts` is a Zod module, and everything under `src/browser/**` and
+ * `src/react/**` imports the config type-only precisely so that no scaffolded SPA ships Zod to walk a
+ * chain of six names. A value import here would put it in every adopter's main chunk.
+ */
+const KNOWN_RESOLVERS: Readonly<Record<BrowserResolver, true>> = {
+  query: true,
+  account: true,
+  storage: true,
+  navigator: true,
+  server: true,
+  default: true,
+};
+
+/**
+ * The links of `names` this build recognizes, in the order given, dropping the rest.
+ *
+ * The browser walks its chain by name because that is how the projection carries it, so a link this
+ * build has never heard of — a project one release ahead of the SPA bundle it is serving — contributes
+ * nothing rather than throwing. The links around it are still asked, each in its own place.
+ */
+export function recognizedResolvers(names: readonly string[]): BrowserResolver[] {
+  return names.filter((name): name is BrowserResolver => Object.hasOwn(KNOWN_RESOLVERS, name));
+}
+
+/**
+ * What a browser knows about the reader's language.
+ *
+ * A separate chain from the server's, because half the server's links do not exist here and half of
+ * these do not exist there: `localStorage` is absent from a Worker, and `navigator.language` inside
+ * workerd is the constant `"en"`, carrying no request information at all.
+ */
+export interface BrowserLocaleSignals {
+  /** An explicit choice on the URL — `?lang=es`. */
+  readonly query?: string | null;
+  /** The signed-in reader's own preference, as the app already holds it. */
+  readonly account?: string | null;
+  /** What this device remembers, from `localStorage`. */
+  readonly storage?: string | null;
+  /**
+   * The reader's own browser languages, most-wanted first, from `navigator.languages`.
+   *
+   * The browser's equivalent of `Accept-Language`, and the only link that answers for a first-time
+   * visitor who has chosen nothing and is signed in to nothing. A list rather than one tag, because
+   * `navigator.languages` is one and the whole of it is a preference order worth honoring.
+   */
+  readonly navigator?: readonly string[] | null;
+  /** What the server negotiated for the document, off `<html lang>`. */
+  readonly server?: string | null;
+}
+
+/**
+ * The reader's locale, by the configured browser chain.
+ *
+ * Default order: `?lang=`, the account, local storage, the server's answer, the project default.
+ *
+ * **The account outranks the device.** `pithy_auth_users.locale` is where a person's locale lives, so a
+ * signed-in reader who picks a language on one device must not silently be reading another language on
+ * the next. A `?lang=` choice by a signed-in reader is written through to their account rather than
+ * only to `localStorage`, which is what keeps the fact in one home; `docs/I18N.md` states it once.
+ */
+export function resolveBrowserLocale(signals: BrowserLocaleSignals, config: BrowserChain): ResolvedLocale {
+  const chain = recognizedResolvers(config.browserResolvers);
+  const links: ResolverLink[] = chain.map((resolver) => linkFor(resolver, signals, config));
+  return resolveChain(links, config);
+}
+
+/** One link, by name. A standalone function so the switch stays exhaustive under `verbatimModuleSyntax`. */
+function linkFor(resolver: BrowserResolver, signals: BrowserLocaleSignals, config: LocaleSet): ResolverLink {
+  switch (resolver) {
+    case "query":
+      return tagLink(resolver, signals.query);
+    case "account":
+      return tagLink(resolver, signals.account);
+    case "storage":
+      return tagLink(resolver, signals.storage);
+    case "navigator":
+      // The whole weighted list, not its head — `navigator.languages` is already in preference order,
+      // and a reader whose first language the project does not ship still gets their second.
+      return { name: resolver, ranges: (signals.navigator ?? []).filter((tag) => tag.trim().length > 0) };
+    case "server":
+      return tagLink(resolver, signals.server);
+    case "default":
+      return tagLink(resolver, config.defaultLocale);
+  }
+}