@pithy-sh/i18n 0.1.0

package/src/catalogs/es/errors.ts

@@ -0,0 +1,197 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+//
+// LOCALE es — an unreviewed first pass. Not American English by design.
+
+import type { MessageCatalog } from "@pithy-sh/core/src/i18n/catalog";
+
+/**
+ * Every kit error code, in Spanish. **Keyed by the code itself** — for an error the catalog key *is*
+ * the code, so there is no second identifier to keep in sync and `KitErrorCode` is the exhaustive
+ * checklist this file has to cover.
+ *
+ * There is no English twin. A payload already carries its English `message` on the wire, and a
+ * translating client renders `t.maybe(payload.code, payload.params) ?? payload.message` — so English is the
+ * fallback by construction and a duplicate of it here would be a second place for one sentence to
+ * drift.
+ *
+ * **These are the caller's words, not the operator's.** `message` is the only field on the wire;
+ * `action` names `pithy` commands and repository files and never leaves the terminal, so nothing here
+ * translates one. Placeholders match the `params` the throw sites pass.
+ *
+ * **Not one sentence below carries a placeholder, and that is a finding rather than a shortcut.** No
+ * throw site in this repository passes `params` today — `git grep "params: {"` over every package's
+ * `src` tree returns Workflow dispatch parameters and nothing else — so a `{name}` written here would
+ * have no value to receive and `interpolate` leaves an unsupplied placeholder as written. `Sala {code}
+ * llena.` on a caller's screen is worse than `Esa sala ya no admite más jugadores.`, which is why the
+ * generic clause wins until the English side has a value to send. `./errors.test.ts` pins the absence,
+ * and says there what would replace the pin the day a throw site starts naming one.
+ *
+ * Peninsular-neutral: one `es` serves es-ES, es-MX and es-AR, so a regionalism that reads as home to
+ * one of them and as foreign to the other two is the wrong word even when it is the better word. Where
+ * the English distinguishes an internal cause the Spanish states only the part a caller can act on —
+ * a caller who cannot read our logs is not helped by learning that a binding was missing.
+ */
+export const esErrors: MessageCatalog = {
+  // Core: the codes every capability throws, and the ones a caller meets most.
+  "validation/invalid_input": "Los datos enviados no son válidos.",
+  "auth/invalid_token": "Tu sesión no es válida o ha caducado. Vuelve a iniciar sesión.",
+  "auth/forbidden": "No tienes permiso para hacer esto.",
+  "auth/provider_unavailable": "Este método de acceso no está disponible ahora. Prueba con otro.",
+  "core/not_found": "No existe el recurso solicitado.",
+  "core/conflict": "La solicitud entra en conflicto con el estado actual.",
+  "rate_limit/exceeded": "Demasiadas solicitudes. Inténtalo más tarde.",
+  "core/internal": "Se ha producido un error inesperado.",
+  "core/upstream_failed": "Un servicio externo ha fallado. Inténtalo de nuevo.",
+  "core/upstream_timeout": "Un servicio externo no ha respondido a tiempo.",
+  "core/invalid_workflow_params": "Los parámetros de la operación no son válidos.",
+  // The three workflow-dispatch 500s say the same thing to a caller on purpose: the difference between
+  // them is which part of the deployment is wrong, and that belongs to `action`, not here.
+  "core/missing_workflow_binding": "Esta operación no está disponible ahora.",
+  "core/unknown_workflow": "La operación solicitada no existe.",
+  "core/workflow_failed": "La operación no se ha completado.",
+  "core/webhook_unverified": "La firma de la notificación no es válida.",
+
+  // Cloudflare REST. Naming the provider is safe — it is the adopter's own account, not our infrastructure.
+  "cloudflare/not_configured": "Este servicio no está disponible ahora.",
+  "cloudflare/request_failed": "No se ha podido completar la llamada a Cloudflare.",
+  "cloudflare/invalid_response": "La respuesta de Cloudflare no tiene el formato esperado.",
+
+  // Secrets.
+  "secrets/not_found": "El secreto solicitado no existe.",
+  "secrets/already_exists": "Ya existe un secreto con ese nombre.",
+  "secrets/invalid_value": "El valor del secreto no es válido.",
+  "secrets/crypto_failed": "No se ha podido procesar el secreto.",
+  "secrets/rotation_unrecorded": "No se ha registrado la rotación del secreto.",
+  "secrets/rotation_unsupported": "Este secreto no se puede rotar por esta vía.",
+
+  // Email.
+  "email/template_not_found": "Esa plantilla de correo no existe.",
+  "email/invalid_payload": "Los datos de la plantilla no son válidos.",
+  "email/invalid_token": "El enlace del correo no es válido o ha caducado.",
+  "email/suppressed": "Ese destinatario ha dejado de recibir correos.",
+  "email/rate_limited": "Se ha alcanzado el límite de envío. Inténtalo más tarde.",
+  "email/send_failed": "No se ha podido enviar el correo.",
+
+  // Turnstile. A caller never learns whether the check failed or the deployment misconfigured it.
+  "turnstile/missing_token": "Falta la verificación de seguridad.",
+  "turnstile/failed": "No se ha superado la verificación de seguridad. Inténtalo de nuevo.",
+  "turnstile/config": "La verificación de seguridad no está disponible ahora.",
+
+  // Audit.
+  "audit/invalid_event": "El evento de auditoría no es válido.",
+  "audit/write_failed": "No se ha podido registrar el evento de auditoría.",
+
+  // Media.
+  "media/not_found": "Ese archivo no existe.",
+  "media/unsupported": "Ese tipo de archivo no es compatible con esta operación.",
+  "media/storage_failed": "No se ha podido guardar el archivo.",
+  "media/enrichment_failed": "No se ha podido analizar el archivo.",
+
+  // Leaderboards.
+  "leaderboard/board_not_found": "Esa clasificación no existe.",
+  "leaderboard/entry_not_found": "No hay ninguna puntuación en esta clasificación.",
+  "leaderboard/score_rejected": "La puntuación está fuera del rango permitido.",
+  "leaderboard/submit_forbidden": "No puedes enviar puntuaciones a esta clasificación.",
+  "leaderboard/board_immutable": "Esta clasificación ya no se puede modificar.",
+  "leaderboard/invalid_schedule": "Esta clasificación no está disponible ahora.",
+
+  // Multiplayer.
+  "multiplayer/game_not_found": "Ese juego no existe.",
+  "multiplayer/session_not_found": "Esa partida no existe.",
+  "multiplayer/not_a_member": "No participas en esta partida.",
+  "multiplayer/session_full": "La partida está completa.",
+  "multiplayer/invalid_transition": "Esta acción no es posible en la fase actual de la partida.",
+  "multiplayer/invalid_move": "Ese movimiento no es válido.",
+
+  // Ledger.
+  "ledger/currency_not_found": "Esa moneda no existe.",
+  "ledger/account_not_found": "No tienes cuenta en esa moneda.",
+  "ledger/hold_not_found": "Esa reserva de saldo no existe.",
+  "ledger/insufficient_funds": "El saldo no es suficiente.",
+  "ledger/hold_not_open": "Esa reserva de saldo ya está resuelta.",
+  "ledger/invalid_amount": "El importe debe ser un número entero positivo.",
+
+  // Rating.
+  "rating/unknown_algorithm": "Ese algoritmo de valoración no existe.",
+  "rating/unsupported_player_count": "Ese número de jugadores no es compatible con esta valoración.",
+  "rating/invalid_params": "Los parámetros de valoración no son válidos.",
+  "rating/game_not_found": "Ese juego no tiene valoración.",
+  "rating/pool_not_found": "Ese grupo de valoración no existe.",
+  "rating/record_forbidden": "No puedes registrar resultados valorados.",
+
+  // Matchmaking.
+  "matchmaking/room_not_found": "Ese código no corresponde a ninguna sala abierta.",
+  "matchmaking/room_full": "Esa sala ya no admite más jugadores.",
+  "matchmaking/invalid_code": "Ese código de sala no es válido.",
+  "matchmaking/invite_not_found": "Esa invitación no existe.",
+  "matchmaking/invite_forbidden": "No puedes actuar sobre esta invitación.",
+  "matchmaking/user_not_found": "No se ha encontrado a esa persona.",
+  "matchmaking/already_friends": "Ya hay una amistad o una solicitud con esa persona.",
+  "matchmaking/friend_request_not_found": "No hay ninguna solicitud de amistad pendiente.",
+  "matchmaking/not_queued": "No estás en la cola.",
+
+  // Storage. The 404 keeps the English hedge, because telling a stranger that a file exists is the leak
+  // the code was written to avoid, and a Spanish sentence that resolves the ambiguity undoes it.
+  "storage/not_found": "Ese archivo no existe o no tienes acceso a él.",
+  "storage/forbidden": "No tienes acceso a este archivo.",
+  "storage/quota_exceeded": "La subida supera tu espacio disponible.",
+  "storage/upload_incomplete": "La subida de este archivo no ha terminado.",
+  "storage/multipart_failed": "No se ha podido completar la subida.",
+  "storage/share_expired": "Este enlace compartido ha caducado.",
+  "storage/share_revoked": "Este enlace compartido se ha revocado.",
+
+  // Vector search.
+  "vector/metadata_index_drift": "Esta búsqueda no está disponible ahora.",
+  "vector/dimension_mismatch": "El vector no tiene las dimensiones del índice.",
+  "vector/topk_exceeded": "Has pedido más resultados de los permitidos en esta consulta.",
+  "vector/filter_too_large": "El filtro es demasiado grande.",
+  "vector/metadata_too_large": "Los metadatos del vector superan el tamaño permitido.",
+  "vector/index_not_found": "Ese índice no existe.",
+  "vector/unfilterable_field": "Por ese campo no se puede filtrar.",
+
+  // Payments.
+  "payments/invalid_receipt": "Ese recibo no tiene un formato válido.",
+  "payments/verification_failed": "La tienda ha rechazado el recibo.",
+  "payments/webhook_unverified": "La firma de la notificación de pago no es válida.",
+  "payments/rail_not_configured": "Ese método de pago no está disponible.",
+  "payments/product_not_found": "Ese producto no está en el catálogo.",
+  "payments/environment_mismatch": "Esa compra pertenece a otro entorno de la tienda.",
+  "payments/subscription_change_refused": "El estado de esa suscripción no permite el cambio solicitado.",
+  "payments/receipt_already_owned": "Esa compra ya pertenece a otra cuenta.",
+  "payments/provider_unavailable": "No se ha podido contactar con la tienda. Inténtalo más tarde.",
+  "payments/entitlement_required": "Necesitas una compra activa para esto.",
+  "payments/clawback_failed": "No se ha podido recuperar el importe del reembolso.",
+  "payments/discount_invalid": "Ese código de descuento no es válido.",
+  "payments/entitlement_not_in_catalog": "Ese derecho de acceso no está en el catálogo.",
+  "payments/subject_unresolved": "No se ha podido determinar en nombre de quién actúas.",
+  "payments/reconcile_not_provisioned": "La conciliación no está configurada en este despliegue.",
+
+  // Control plane. The caller here is a management client, never an end user — the words stay caller-facing
+  // all the same, because `clientError` strips `action` on this path exactly as it does on every other.
+  "controlplane/not_connected": "No hay conexión de administración para este entorno.",
+  "controlplane/invalid_credential": "La credencial de administración no es válida.",
+  "controlplane/insufficient_scope": "La credencial de administración no tiene permiso para esta operación.",
+  "controlplane/key_not_found": "Esa clave no existe.",
+  "controlplane/key_conflict": "Esa operación entra en conflicto con el estado de la conexión.",
+
+  // Support.
+  "support/not_found": "Esa conversación de soporte no existe.",
+  "support/invalid_category": "Esa categoría de soporte no es válida.",
+  "support/unparseable_message": "No se ha podido leer el mensaje.",
+  "support/rejected": "Has enviado demasiados mensajes. Inténtalo más tarde.",
+  "support/classification_failed": "No se ha podido clasificar el mensaje.",
+  "support/reply_failed": "No se ha podido enviar la respuesta.",
+
+  // Testers.
+  "testers/cohort_not_found": "Ese grupo de pruebas no existe.",
+  "testers/member_not_found": "No hay ningún participante con esos datos.",
+  "testers/invalid_token": "Ese enlace de invitación no es válido o ha caducado.",
+  "testers/roster_full": "El grupo de pruebas está completo.",
+  "testers/already_on_roster": "Esa dirección ya está en el grupo de pruebas.",
+  "testers/cohort_closed": "Ese grupo de pruebas está cerrado.",
+  "testers/withdrawn": "Esa dirección se ha dado de baja de este grupo de pruebas.",
+  "testers/nudge_cooldown": "Se ha avisado a estas personas hace poco. Espera para volver a hacerlo.",
+  "testers/copy_not_allowed": "No se admite un mensaje propio en los avisos.",
+  "testers/not_configured": "Las pruebas no están disponibles ahora.",
+};

package/src/catalogs/es/index.ts

@@ -0,0 +1,30 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+//
+// LOCALE es — an unreviewed first pass. Not American English by design.
+
+import type { MessageCatalog } from "@pithy-sh/core/src/i18n/catalog";
+import { esErrors } from "./errors";
+import { esScreens } from "./screens";
+
+/**
+ * The kit's Spanish, in one catalog.
+ *
+ * Two files rather than one because they answer to different gates: the error keys are pinned to
+ * `KitErrorCode` and the screen keys to what the templates render. Split, a failure names which of
+ * the two drifted.
+ *
+ * **The email copy is not here, and that is deliberate (#442).** `@pithy-sh/email` carries its own
+ * `email/` translations beside its English, because the send Worker has to be *built* with them —
+ * anything it does not bundle is stamped into it as configuration, every provision run, against a
+ * 5 KB per-variable ceiling. A capability owning its own domain in every language is also what the
+ * domain rule already says; this package holds what no capability can, which is the error taxonomy
+ * and the copied screens.
+ *
+ * **This copy is a marked first pass and no native-speaker review blocks it.** Every file in this
+ * directory says so in its head, in the marker `docs/I18N.md` publishes. The brand voice is
+ * load-bearing in English and a literal translation does not carry it; saying so in the file is
+ * honest, and holding the machinery hostage to a reviewer who does not yet exist is not. Corrections
+ * arrive by contribution.
+ */
+export const es: MessageCatalog = { ...esErrors, ...esScreens };

package/src/catalogs/es/screens.ts

@@ -0,0 +1,149 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+//
+// LOCALE es — an unreviewed first pass. Not American English by design.
+
+import type { MessageCatalog } from "@pithy-sh/core/src/i18n/catalog";
+
+/**
+ * The kit's screens, in Spanish — every string `@pithy-sh/ui-react` renders.
+ *
+ * The English twin of this catalog is not here and is not in this package: it is baked into each
+ * template, because a template is **copied** into the adopter's repository and its own English is the
+ * only catalog that survives the copy. That is what makes a project which never composes `i18n` render
+ * byte for byte as it did before, with no dependency on this package at all.
+ *
+ * **The keys are the join, and they are the templates'.** A key here that no template renders is a
+ * sentence nobody will ever read; a template key missing here is a Spanish reader meeting English. Both
+ * are invisible to `tsc` — a `MessageCatalog` is `Record<string, string>` and every typo satisfies it —
+ * so the way to check a change is to read the template beside it.
+ *
+ * **Two invariants are per-locale and survive translation, so they are checked here rather than only in
+ * English.** `auth/sign_in.provider.label` is the provider buttons' accessible name and must **contain**
+ * the visible word, which is the brand name and is never translated — voice control matches what a
+ * reader can see (WCAG 2.5.3, Label in Name). And nothing a sign-in button says may name a code: the
+ * screen offers one way in, the link, and `código` on that screen is a second passwordless path being
+ * advertised by a translation. The word appears here only under `auth/otp.*`, which is a different
+ * screen and the one place it is right.
+ *
+ * **Neutral where English is neutral.** English `You're subscribed.` carries no gender and
+ * `Estás suscrito.` does, so the Spanish says what the subscription is doing rather than what the
+ * reader is. The same argument moves `Welcome.` off `Bienvenido.`.
+ */
+export const esScreens: MessageCatalog = {
+  // ── auth: the sign-in screen ───────────────────────────────────────────────
+  "auth/sign_in.title": "Te damos la bienvenida.",
+  "auth/sign_in.provider.label": "Continuar con {provider}",
+  "auth/sign_in.provider_unconfigured": "{provider} no está configurado aquí. Usa el enlace.",
+  "auth/sign_in.provider_silent": "{provider} no respondió. Usa el enlace.",
+  "auth/sign_in.divider": "o",
+  "auth/sign_in.email.label": "Correo electrónico",
+  "auth/sign_in.submit": "Envíame un enlace",
+  "auth/sign_in.signup.prompt": "¿Aún no tienes cuenta?",
+  "auth/sign_in.signup.answer": "Al entrar se crea una.",
+  "auth/sign_in.signup.closed": "Solo cuentas existentes.",
+  "auth/sign_in.sent.title": "Mira tu correo.",
+  "auth/sign_in.sent.body": "Si esa dirección puede entrar, el enlace ya va en camino. Caduca pronto.",
+
+  // ── auth: the one-time code screen ─────────────────────────────────────────
+  "auth/otp.title": "Introduce el código.",
+  "auth/otp.sent.one": "Hemos enviado {count} dígito a {email}.",
+  "auth/otp.sent.other": "Hemos enviado {count} dígitos a {email}.",
+  "auth/otp.inbox": "tu correo",
+  "auth/otp.failed": "Ese código no funcionó. Inténtalo otra vez o pide uno nuevo.",
+  "auth/otp.submit": "Entrar",
+  "auth/otp.resend": "Enviar un código nuevo",
+
+  // ── auth: the magic link's landing screen ──────────────────────────────────
+  "auth/callback.title": "Entrando.",
+  "auth/callback.body": "Un momento.",
+
+  // ── payments: the paywall ──────────────────────────────────────────────────
+  "payments/paywall.title": "Ve más lejos.",
+  "payments/paywall.body": "Elige lo que necesitas. Puedes cambiar de idea más tarde.",
+  "payments/paywall.buy": "Comprar {product}",
+  "payments/paywall.in_app": "Disponible en la app.",
+  "payments/paywall.holdings": "¿Qué tengo ya?",
+  "payments/paywall.empty.title": "Nada a la venta.",
+  // The sentence continues into a `<code>pithy.config.ts</code>` the screen renders after it. A file
+  // name is not copy, so it is not a placeholder here and no translation may move it.
+  "payments/paywall.empty.body": "Este proyecto aún no tiene catálogo. Añade productos en",
+  "payments/paywall.done.title": "Todo listo.",
+  "payments/paywall.done.body": "Gracias. Tu compra ya está en tu cuenta.",
+  "payments/paywall.done.home": "Ir al inicio",
+
+  // ── payments: the pricing screen ───────────────────────────────────────────
+  "payments/pricing.title": "Lo que cuesta.",
+  "payments/pricing.body": "Los precios son para donde estás. Los impuestos los calcula Paddle, no nosotros.",
+  "payments/pricing.anonymous": "Cualquiera puede ver un precio. Comprar necesita cuenta.",
+  "payments/pricing.loading": "Buscando tu precio.",
+  "payments/pricing.estimated": "Estimado.",
+  "payments/pricing.unavailable": "No pudimos obtener un precio. Lo verás al pagar.",
+  "payments/pricing.sign_in": "Entra para comprar {product}",
+  "payments/pricing.buy": "Comprar {product}",
+  "payments/pricing.holdings": "¿Qué tengo ya?",
+  // `{interval}` is Paddle's own word for the billing period and arrives from their API in English, so
+  // it is left where it lands rather than half-translated into a sentence that then disagrees with the
+  // figure beside it. An adopter who wants `al mes` says so in `i18n({ messages })`.
+  "payments/pricing.every.one": "al {interval}",
+  "payments/pricing.every.other": "cada {count} {interval}s",
+  "payments/pricing.empty.title": "Aquí no hay precios.",
+  // Two halves of one sentence, with `<code>paddle</code>` between them and `<code>pithy.config.ts</code>`
+  // after. Both code words are identifiers and neither is translated.
+  "payments/pricing.empty.body": "Esta pantalla pone precio a lo que vendes por Paddle. Añade un bloque",
+  "payments/pricing.empty.body_end": "a un producto en",
+
+  // ── payments: what the reader already holds ────────────────────────────────
+  "payments/subscription.subscribed": "Tu suscripción está activa.",
+  "payments/subscription.empty": "Aún nada.",
+  "payments/subscription.unreadable": "No pudimos comprobarlo.",
+  "payments/subscription.nothing_held": "No tienes nada en esta cuenta.",
+  "payments/subscription.loading": "Un momento.",
+  "payments/subscription.holding.ended": "Finalizado.",
+  "payments/subscription.holding.ended_not_renewing": "Finalizado, y no se renueva.",
+  "payments/subscription.holding.kept": "Tuyo para siempre.",
+  // The date itself is `Intl`'s, rendered from the reader's formatting locale. This is the sentence
+  // around it, which is the only part a catalog can own.
+  "payments/subscription.holding.renews": "Se renueva el {date}.",
+  "payments/subscription.manage": "Gestionar la facturación",
+  "payments/subscription.apple": "Comprado en la App Store",
+  "payments/subscription.google": "Comprado en Google Play",
+  "payments/subscription.more": "Ver qué más hay",
+
+  // ── app: the adopter's own shell and home screen ───────────────────────────
+  //
+  // Under `app/` rather than a capability name because that is what these are: the router and the home
+  // screen are the adopter's files, seeded once and never rewritten. Translating them here is what
+  // makes a freshly scaffolded project speak Spanish on its first screen rather than its second.
+  "app/loading": "Un momento.",
+  "app/not_found.title": "Aquí no hay nada.",
+  "app/not_found.body": "Nada responde en {path}.",
+  "app/not_found.home": "Ir al inicio",
+  "app/home.title": "Ya estás dentro.",
+  "app/home.signed_in_as": "Has entrado como {email}.",
+  "app/home.someone": "alguien",
+  "app/home.sign_out": "Salir",
+  "app/home.bare.title": "Funciona.",
+  "app/home.bare.body": "El worker dice: {status}.",
+  "app/home.bare.checking": "comprobando",
+  "app/home.bare.unknown": "desconocido",
+  "app/home.bare.unreachable": "inaccesible",
+
+  // ── client: the failures a browser mints for itself, never sent by a Worker ─
+  //
+  // `client/*` is the one domain with no capability behind it, and that is deliberate: these are the
+  // codes an SDK writes when the request never reached a Worker at all — offline, a proxy's HTML page,
+  // no browser to redirect. They are also the failures a reader meets most, which is why leaving them
+  // untranslated made the whole feature read as half-finished: a Spanish sign-in page answering an
+  // offline phone in English is the first thing anybody would notice.
+  //
+  // **`@pithy-sh/auth` and `@pithy-sh/payments` mint the same two codes with different English** — "the
+  // server" against "the store" — and one key holds one string. The Spanish is written to be true of
+  // both rather than picking a side; the noun each English sentence names is not information the
+  // reader needed, and inventing `auth/client_unreachable` to keep it would put the same failure under
+  // two codes for the sake of one word.
+  "client/unreachable": "No hemos podido conectar.",
+  "client/unreadable": "La respuesta no se ha podido leer.",
+  "client/cross_origin": "Esa petición habría salido de este sitio, así que no se ha enviado.",
+  "client/no_browser": "No hay ningún navegador al que enviarte para pagar.",
+};

package/src/catalogs/kit.ts

@@ -0,0 +1,25 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { LocaleCatalogs } from "@pithy-sh/core/src/i18n/catalog";
+import { es } from "./es/index";
+
+/**
+ * The kit's own translations, keyed by locale — every locale but the one the kit is written in.
+ *
+ * **There is no `en` here, and that is not an omission.** English is the source: an error carries its
+ * English `message` on the wire already, a kit capability contributes its English through
+ * `Capability.messages`, and a copied screen carries the English it was scaffolded with. A second copy
+ * of it in this map would be a second place for the same sentence to drift.
+ *
+ * **These ship in the package and are never copied into an adopter's repository.** If the Spanish for
+ * `auth/sign_in.title` lived in their tree, a typo fix or a new locale could never reach them, and
+ * every adopter would become a fork on the day they scaffolded. An adopter overrides a sentence by
+ * passing one entry to `i18n({ messages })`; passing a whole locale object **is** the fork, which is
+ * why no eject command is needed for this and none is offered.
+ *
+ * Server-side this map is imported statically — it is text, it is small, and a Worker has no second
+ * round trip to spend. The browser reaches the same catalogs by dynamic import, one chunk per locale;
+ * see `./browser`.
+ */
+export const KIT_CATALOGS: LocaleCatalogs = { es };

package/src/client/projection.ts

@@ -0,0 +1,51 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * What a browser may know about this project's languages — the shape of `virtual:pithy/i18n`.
+ *
+ * **Locale metadata only. Never catalogs.** `renderVirtualModule` emits the projection as an inline
+ * `JSON.stringify` literal in the main chunk, so a catalog carried here would be downloaded by every
+ * reader in every language before the first paint, and would defeat the per-locale code splitting the
+ * design is built on. Catalogs reach the browser by dynamic import, one Vite chunk per locale.
+ *
+ * **This declaration is the contract, and the projection is checked against it.** It is written here
+ * rather than inferred from the closure that builds it: an inferred type follows whatever the producer
+ * last happened to say, so a projection that dropped a field would take the type with it and nothing
+ * would go red. Declared, the arrow is what has to change.
+ *
+ * **This is the only statement of the shape.** `@pithy-sh/ui-react`'s `templates/client-env.d.ts` — the
+ * ambient declaration `pithy ui add react` copies into an adopter's Worker — is generated from this
+ * type by `@pithy-sh/vite`'s `clientEnvDeclaration.ts`, doc comments and all. What is written here is
+ * what a screen author reads.
+ */
+export type I18nClientProjection =
+  | {
+      /**
+       * The i18n capability is not composed. Every screen renders the English it was scaffolded with,
+       * byte for byte as it did before any of this landed — which is what makes the capability optional.
+       */
+      enabled: false;
+    }
+  | {
+      /** The i18n capability is composed, and these are the languages this project serves. */
+      enabled: true;
+      /** Every locale this project serves, as BCP-47 tags. The browser negotiates within this set. */
+      supportedLocales: string[];
+      /** The locale served when nothing in the browser chain answers. Always in `supportedLocales`. */
+      defaultLocale: string;
+      /** The query parameter an explicit choice arrives on — `?lang=es`. */
+      queryParam: string;
+      /** The `localStorage` key this device's remembered locale is written under. */
+      storageKey: string;
+      /**
+       * The browser chain, in the order it is asked: `query`, `account`, `storage`, `server`, `default`.
+       * Projected so the front end resolves in the order the project configured, not one it assumed.
+       */
+      browserResolvers: string[];
+      /**
+       * Language ranges the matcher cannot derive, as range → supported locale. Usually empty; it
+       * carries the historical pairs (`nb` meaning `no`) that no truncation of a tag would reach.
+       */
+      exceptions: Record<string, string>;
+    };

package/src/config/config.ts

@@ -0,0 +1,152 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { LocaleCatalogs } from "@pithy-sh/core/src/i18n/catalog";
+import { Locale } from "@pithy-sh/core/src/i18n/locale";
+import { z } from "zod";
+
+/**
+ * One link of the **server** resolver chain — the order a Worker asks "what language is this request in?".
+ *
+ * Split from the browser chain because `localStorage` does not exist in a Worker and
+ * `navigator.language` inside workerd is the constant `"en"`, carrying no request information at all.
+ * Two chains over one contract is honest; one chain with half its links inert is not.
+ */
+export const ServerResolver = z
+  .enum(["param", "user", "cookie", "header", "default"])
+  .describe("A link of the server resolver chain: an explicit param, the account, a cookie, the header, the default.");
+export type ServerResolver = z.infer<typeof ServerResolver>;
+
+/**
+ * One link of the **browser** resolver chain.
+ *
+ * `account` sits above `storage` deliberately: `pithy_auth_users.locale` is where a person's locale
+ * lives, so a signed-in reader's choice must not silently diverge per device. See `docs/I18N.md`.
+ */
+export const BrowserResolver = z
+  .enum(["query", "account", "storage", "navigator", "server", "default"])
+  .describe(
+    "A link of the browser resolver chain: `?lang=`, the account, local storage, the browser's own languages, the server, the default.",
+  );
+export type BrowserResolver = z.infer<typeof BrowserResolver>;
+
+/** The server chain's default order — explicit param, account, cookie, `Accept-Language`, project default. */
+const DEFAULT_SERVER_RESOLVERS: readonly ServerResolver[] = ["param", "user", "cookie", "header", "default"];
+
+/** The browser chain's default order — `?lang=`, account, local storage, the server's answer, default. */
+/**
+ * The browser chain's default order — `?lang=`, account, this device's memory, the reader's own
+ * browser languages, what the server declared, the project default.
+ *
+ * **`navigator` sits above `server`, and that ordering is the whole reason the link exists.** The
+ * `server` link reads `document.documentElement.lang`, and a scaffolded SPA is served from a static
+ * `index.html` that says `lang="en"` with no substitution token — so without a browser link, a
+ * first-time Spanish visitor to a project shipping `es` resolved to the default and read English on
+ * every screen. Automatic negotiation worked on the server and nowhere else.
+ *
+ * Placing it above `server` costs a genuinely server-rendered app nothing: if that server negotiated,
+ * it negotiated from `Accept-Language`, which is the same preference `navigator.languages` reports —
+ * and anything it knew that the browser does not, the reader's account, is already ranked higher.
+ */
+const DEFAULT_BROWSER_RESOLVERS: readonly BrowserResolver[] = [
+  "query",
+  "account",
+  "storage",
+  "navigator",
+  "server",
+  "default",
+];
+
+/** The locale the kit writes in, and what every unconfigured project falls back to. */
+const DEFAULT_LOCALE = "en";
+
+/**
+ * The i18n capability's configuration.
+ *
+ * Everything an adopter decides about language lives here, including their own catalogs — **a config
+ * object passed to the capability, never files discovered on disk.** Two reasons, and both are hard
+ * constraints rather than preferences. `configEntrypoints.test.ts` imports every capability's config
+ * entry point in a plain Node process, so a catalog loader doing `readFileSync` at module scope breaks
+ * `pithy upgrade`, `migrate` and `deploy` for every project composing it. And a catalog file copied
+ * into an adopter's repository is a fork on the day they scaffold: a typo fix or a new locale could
+ * never reach them again.
+ */
+export const I18nConfig = z
+  .object({
+    supportedLocales: z
+      .array(Locale)
+      .min(1)
+      .default([DEFAULT_LOCALE])
+      .describe("Every locale this project serves. Ship the least specific tag that is true — `es`, not `es-ES`."),
+    defaultLocale: Locale.default(DEFAULT_LOCALE).describe(
+      "The locale served when nothing else answers. Must be one of `supportedLocales`.",
+    ),
+    messages: LocaleCatalogs.default({}).describe(
+      "This project's own catalogs. Overriding one kit key is one entry; everything unmentioned keeps flowing from the package.",
+    ),
+    exceptions: z
+      .record(
+        z.string().describe("The language range a reader sends that no truncation of it would match."),
+        Locale.describe("The supported locale it means."),
+      )
+      .default({})
+      // **Keys lower-cased on the way in, because the lookup lower-cases the range.** `matchLocale`
+      // compares against a lower-cased range, so an exception written the way BCP-47 spells it —
+      // `nb-NO`, which is exactly how somebody writes the pair this field documents — never matched and
+      // failed silently, the reader falling through to the project default. Normalizing here rather
+      // than indexing case-insensitively at the lookup keeps one spelling in the resolved config, so
+      // what `pithy doctor` prints is what the matcher will use.
+      .transform((exceptions) =>
+        Object.fromEntries(Object.entries(exceptions).map(([range, locale]) => [range.toLowerCase(), locale])),
+      )
+      .describe("Language ranges the matcher cannot derive — historical pairs like `nb` meaning `no`."),
+    cookie: z
+      .string()
+      .min(1)
+      .default("pithy_locale")
+      .describe("The cookie the server chain's `cookie` link reads a chosen locale from."),
+    queryParam: z
+      .string()
+      .min(1)
+      .default("lang")
+      .describe("The query parameter an explicit choice arrives on, on both the server and the browser."),
+    storageKey: z
+      .string()
+      .min(1)
+      .default("pithy.locale")
+      .describe("The `localStorage` key the browser chain's `storage` link reads and writes."),
+    serverResolvers: z
+      .array(ServerResolver)
+      .min(1)
+      .default([...DEFAULT_SERVER_RESOLVERS])
+      .describe("The server chain, in the order it is asked. Reorder or shorten it; `default` is the last resort."),
+    browserResolvers: z
+      .array(BrowserResolver)
+      .min(1)
+      .default([...DEFAULT_BROWSER_RESOLVERS])
+      .describe("The browser chain, in the order it is asked."),
+  })
+  .check((ctx) => {
+    const { supportedLocales, defaultLocale } = ctx.value;
+    if (!supportedLocales.includes(defaultLocale)) {
+      ctx.issues.push({
+        code: "custom",
+        input: ctx.value,
+        path: ["defaultLocale"],
+        message: `\`${defaultLocale}\` is the default locale and is not in \`supportedLocales\`, so nothing would answer when negotiation fails.`,
+      });
+    }
+    for (const locale of Object.keys(ctx.value.messages)) {
+      if (!supportedLocales.includes(locale)) {
+        ctx.issues.push({
+          code: "custom",
+          input: ctx.value,
+          path: ["messages", locale],
+          message: `\`${locale}\` carries messages and is not in \`supportedLocales\`, so nothing would ever read them.`,
+        });
+      }
+    }
+  })
+  .describe("How this project negotiates and renders language, and the catalogs it adds of its own.");
+export type I18nConfig = z.output<typeof I18nConfig>;
+export type I18nConfigInput = z.input<typeof I18nConfig>;