@pithy-sh/i18n 0.1.0

package/src/resolve/chain.ts

@@ -0,0 +1,86 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { LocaleContext } from "@pithy-sh/core/src/i18n/locale";
+import { formattingLocaleOf, localeDirection } from "@pithy-sh/core/src/i18n/locale";
+import type { LocaleExceptions } from "@pithy-sh/core/src/i18n/match";
+import { matchLocale } from "@pithy-sh/core/src/i18n/match";
+
+/**
+ * The languages a chain may land on: what it matches against, what it falls back to, and the pairs no
+ * truncation of a tag would reach.
+ *
+ * **Three fields rather than `I18nConfig`, because a browser holds neither the catalogs nor the cookie
+ * name nor the server chain.** `virtual:pithy/i18n` projects locale metadata and nothing else, and this
+ * is the part of it a match is made from — so the projection satisfies this shape as it stands and the
+ * resolved config satisfies it too. Structural on purpose: one type both sides already are beats a
+ * conversion every caller has to work out for itself.
+ */
+export interface LocaleSet {
+  /** Every locale this project serves. A chain answers with one of these or with nothing. */
+  readonly supportedLocales: readonly string[];
+  /** The locale served when no link answers. Always one of `supportedLocales`. */
+  readonly defaultLocale: string;
+  /** Language ranges the matcher cannot derive, as range → supported locale. Usually empty. */
+  readonly exceptions: LocaleExceptions;
+}
+
+/** One link of a resolver chain: where the ranges came from, and what they were. */
+export interface ResolverLink {
+  /** The link's name, as it appears in `serverResolvers` / `browserResolvers`. */
+  readonly name: string;
+  /** The language ranges this link offers, most-wanted first. Empty when the link has nothing to say. */
+  readonly ranges: readonly string[];
+}
+
+/** A resolved locale, plus which link answered — so `pithy doctor` and a log can say why. */
+export interface ResolvedLocale extends LocaleContext {
+  /** The chain link that answered, or `"default"` when the chain fell through to the project default. */
+  readonly resolvedBy: string;
+}
+
+/**
+ * A single tag as a one-element range list, or nothing when there is no tag.
+ *
+ * The links that read a stored or supplied value all have this shape. A blank string is nothing, not a
+ * range: a cookie the browser cleared and a cookie that was never set mean the same thing here.
+ */
+export function tagLink(name: string, tag: string | null | undefined): ResolverLink {
+  const trimmed = tag?.trim();
+  return { name, ranges: trimmed ? [trimmed] : [] };
+}
+
+/**
+ * Walk `links` in order and take the first that matches a supported locale.
+ *
+ * **The two locales are decided here, and only one of them falls back.** The catalog locale is what
+ * matched — the words the kit actually has. The formatting locale is the *range the reader sent*, kept
+ * whole when it is a tag `Intl` accepts: an `es-AR` visitor reads the `es` catalog and formats as
+ * `es-AR`, which `Intl` supports natively whether or not anyone wrote a string for it.
+ *
+ * Total. Every construction on the way through is guarded, so a chain fed nothing but malformed input
+ * lands on the project default rather than throwing.
+ */
+export function resolveChain(links: readonly ResolverLink[], locales: LocaleSet): ResolvedLocale {
+  for (const link of links) {
+    if (link.ranges.length === 0) continue;
+    const match = matchLocale(link.ranges, locales.supportedLocales, locales.exceptions);
+    if (!match) continue;
+    // The reader's own tag, canonicalized and stripped of extension subtags — `es-ar` becomes `es-AR`,
+    // and `en-u-nu-hanidec` becomes `en`. A range that is not a constructible tag (a wildcard, an
+    // exception-map key) formats as the catalog locale.
+    const requested = formattingLocaleOf(match.range);
+    return {
+      catalogLocale: match.locale,
+      formattingLocale: requested ?? match.locale,
+      direction: localeDirection(match.locale),
+      resolvedBy: link.name,
+    };
+  }
+  return {
+    catalogLocale: locales.defaultLocale,
+    formattingLocale: locales.defaultLocale,
+    direction: localeDirection(locales.defaultLocale),
+    resolvedBy: "default",
+  };
+}

package/src/resolve/server.ts

@@ -0,0 +1,55 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { parseAcceptLanguage } from "@pithy-sh/core/src/i18n/acceptLanguage";
+import type { I18nConfig, ServerResolver } from "../config/config";
+import { type ResolvedLocale, type ResolverLink, resolveChain, tagLink } from "./chain";
+
+/**
+ * What a Worker knows about a request's language, before any of it is trusted.
+ *
+ * Every field is caller-supplied and every one of them is guarded downstream: a `*`, an `en_US`, an
+ * empty token or a fragment still carrying `;q=0.9` falls out of the match instead of reaching
+ * `Intl.Locale` and raising a `RangeError`.
+ */
+export interface ServerLocaleSignals {
+  /** An explicit choice on the query string — `?lang=es`. */
+  readonly param?: string | null;
+  /** The signed-in reader's own preference, from `pithy_auth_users.locale`. */
+  readonly user?: string | null;
+  /** The locale cookie, for a reader who chose one and is not signed in. */
+  readonly cookie?: string | null;
+  /** The raw `Accept-Language` header, q-weights and all. */
+  readonly header?: string | null;
+}
+
+/**
+ * The request's locale, by the configured server chain.
+ *
+ * Default order: explicit param, the account, the cookie, `Accept-Language`, the project default. An
+ * adopter reorders or shortens it in config; `default` is the last resort whether or not it is listed.
+ *
+ * `Accept-Language` is honored as the **full q-weighted list**, not as its first entry —
+ * `pt-PT;q=1.0, es;q=0.8, en;q=0.5` from a reader with no Portuguese is a request for Spanish, and
+ * reading only the head answers English.
+ */
+export function resolveServerLocale(signals: ServerLocaleSignals, config: I18nConfig): ResolvedLocale {
+  const links: ResolverLink[] = config.serverResolvers.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: ServerResolver, signals: ServerLocaleSignals, config: I18nConfig): ResolverLink {
+  switch (resolver) {
+    case "param":
+      return tagLink(resolver, signals.param);
+    case "user":
+      return tagLink(resolver, signals.user);
+    case "cookie":
+      return tagLink(resolver, signals.cookie);
+    case "header":
+      return { name: resolver, ranges: parseAcceptLanguage(signals.header).map((entry) => entry.range) };
+    case "default":
+      return tagLink(resolver, config.defaultLocale);
+  }
+}

package/src/settings/coverage.ts

@@ -0,0 +1,58 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { CapabilitySettings, SettingsFinding } from "@pithy-sh/core/src/capability/settings";
+import type { LocaleCatalogs } from "@pithy-sh/core/src/i18n/catalog";
+import { KIT_CATALOGS } from "../catalogs/kit";
+import type { I18nConfig } from "../config/config";
+
+/** How many missing keys a finding names before it stops counting out loud. */
+const LISTED_KEYS = 5;
+
+/**
+ * Catalog coverage as `pithy doctor`'s **local** tier — offline, project-file-only, and already fatal
+ * to `doctor`'s exit code.
+ *
+ * This is the whole of what a `pithy i18n check` command would have been, and it costs no new command,
+ * no `docs/commands/` page, and no edit to the five exact-count or byte-pinned CLI gates a new command
+ * moves (`dispatch.test.ts`'s `DECLARED`/`GROUPS`, `binDocs.test.ts`'s byte comparison of `docs/CLI.md`
+ * §4.1 against real `pithy --help`, `doctorDocs.test.ts`'s mandated page sections and `--json` key
+ * register). The seam already exists and this is textbook for it.
+ *
+ * It answers one question: **would a reader in a supported locale meet a sentence nobody wrote?** For
+ * each locale the project serves, every key reachable in the default locale must be reachable in that
+ * one too, through the adopter's own catalog or the kit's translation.
+ *
+ * There is no `account` tier. Nothing about language is a question for the Cloudflare API.
+ */
+export function i18nSettings(config: I18nConfig, composed: () => LocaleCatalogs): CapabilitySettings {
+  return {
+    local: () => {
+      const findings: SettingsFinding[] = [];
+      const capabilityMessages = composed();
+      const baseline = new Set([
+        ...Object.keys(capabilityMessages[config.defaultLocale] ?? {}),
+        ...Object.keys(config.messages[config.defaultLocale] ?? {}),
+      ]);
+      for (const locale of config.supportedLocales) {
+        if (locale === config.defaultLocale) continue;
+        const covered = new Set([
+          ...Object.keys(KIT_CATALOGS[locale] ?? {}),
+          ...Object.keys(capabilityMessages[locale] ?? {}),
+          ...Object.keys(config.messages[locale] ?? {}),
+        ]);
+        const missing = [...baseline].filter((key) => !covered.has(key)).sort();
+        if (missing.length === 0) continue;
+        const named = missing.slice(0, LISTED_KEYS).join(", ");
+        const rest = missing.length > LISTED_KEYS ? `, and ${missing.length - LISTED_KEYS} more` : "";
+        findings.push({
+          setting: `i18n.supportedLocales.${locale}`,
+          environment: null,
+          problem: `${missing.length} ${missing.length === 1 ? "message has" : "messages have"} no \`${locale}\` translation, so a reader in that language meets ${config.defaultLocale} instead.`,
+          action: `Add them to \`i18n({ messages: { ${locale}: … } })\` in your \`pithy.config.ts\`: ${named}${rest}.`,
+        });
+      }
+      return findings;
+    },
+  };
+}

package/src/version.generated.ts

@@ -0,0 +1,16 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+// GENERATED by scripts/stampVersions.ts — do not edit by hand. Regenerate with `bun run stamp-versions`.
+//
+// A Worker cannot read its own package.json, so this is how @pithy-sh/i18n knows its own version at
+// runtime. The capability attaches it, and `GET /control-plane/manifest` reports it per capability —
+// which is what answers "should this project upgrade" and "is this customer exposed to what we just
+// fixed". Those questions are only answerable per module, because a project composes some capabilities
+// and not others.
+
+/** This package's npm name — the join key against a release feed. */
+export const PACKAGE_NAME = "@pithy-sh/i18n";
+
+/** This package's version, stamped from its own package.json at generation time. */
+export const PACKAGE_VERSION = "0.1.0";