@pithy-sh/i18n 0.1.1 → 0.1.3

package/dist/adapters/adapters.d.ts

@@ -0,0 +1,47 @@
+import type { Translator } from "@pithy-sh/core/src/i18n/translator";
+/** 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 declare function fromI18next(instance: I18nextLike, formattingLocale?: string): Translator;
+/** 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 declare function fromIntl(intl: IntlShapeLike, formattingLocale?: string): Translator;
+/** 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 declare function fromLingui(i18n: LinguiLike, formattingLocale?: string): Translator;
+//# sourceMappingURL=adapters.d.ts.map

package/dist/adapters/adapters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapters.d.ts","sourceRoot":"","sources":["../../src/adapters/adapters.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oCAAoC,CAAC;AAkErE,0DAA0D;AAC1D,MAAM,WAAW,WAAW;IAC1B,+BAA+B;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,+FAA+F;IAC/F,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC;CAC3D;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,WAAW,EAAE,gBAAgB,CAAC,EAAE,MAAM,GAAG,UAAU,CAOxF;AAED,0EAA0E;AAC1E,MAAM,WAAW,aAAa;IAC5B,6BAA6B;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,8CAA8C;IAC9C,aAAa,CAAC,UAAU,EAAE;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC;CACrF;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,aAAa,EAAE,gBAAgB,CAAC,EAAE,MAAM,GAAG,UAAU,CAMnF;AAED,+DAA+D;AAC/D,MAAM,WAAW,UAAU;IACzB,6BAA6B;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,4CAA4C;IAC5C,CAAC,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC;CACzD;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,UAAU,EAAE,gBAAgB,CAAC,EAAE,MAAM,GAAG,UAAU,CAMlF"}

package/dist/adapters/adapters.js

@@ -0,0 +1,87 @@
+import { createTranslator } from "@pithy-sh/core/src/i18n/translator";
+import { localeDirection } from "@pithy-sh/core/src/i18n/locale";
+//#region src/adapters/adapters.ts
+/**
+* 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) {
+	const base = createTranslator({
+		catalogLocale: source.catalogLocale,
+		formattingLocale: source.formattingLocale,
+		layers: []
+	});
+	const translate = (key, params) => 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
+		})
+	};
+}
+/**
+* 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.
+*/
+function fromI18next(instance, formattingLocale) {
+	return wrap({
+		catalogLocale: instance.language,
+		formattingLocale,
+		translate: (key, params) => instance.t(key, params),
+		plural: (key, count, params) => instance.t(key, {
+			count,
+			...params
+		})
+	});
+}
+/**
+* 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.
+*/
+function fromIntl(intl, formattingLocale) {
+	return wrap({
+		catalogLocale: intl.locale,
+		formattingLocale,
+		translate: (key, params) => intl.formatMessage({ id: key }, params)
+	});
+}
+/**
+* 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.
+*/
+function fromLingui(i18n, formattingLocale) {
+	return wrap({
+		catalogLocale: i18n.locale,
+		formattingLocale,
+		translate: (key, params) => i18n._(key, params)
+	});
+}
+//#endregion
+export { fromI18next, fromIntl, fromLingui };

package/dist/browser/document.d.ts

@@ -0,0 +1,36 @@
+import { type LocaleContext } from "@pithy-sh/core/src/i18n/locale";
+import type { I18nClientProjection } from "../client/projection";
+/**
+ * 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 declare function applyProjectedLocale(projection: I18nClientProjection): LocaleContext | null;
+//# sourceMappingURL=document.d.ts.map

package/dist/browser/document.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document.d.ts","sourceRoot":"","sources":["../../src/browser/document.ts"],"names":[],"mappings":"AAGA,OAAO,EAAsB,KAAK,aAAa,EAAmB,MAAM,gCAAgC,CAAC;AAEzG,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAKjE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,oBAAoB,GAAG,aAAa,GAAG,IAAI,CAoB3F"}

package/dist/browser/document.js

@@ -0,0 +1,85 @@
+import { recognizedResolvers } from "../resolve/browser.js";
+import { applyDocumentLocale } from "./signals.js";
+import { formattingLocaleOf, localeDirection } from "@pithy-sh/core/src/i18n/locale";
+import { matchLocale } from "@pithy-sh/core/src/i18n/match";
+//#region src/browser/document.ts
+/**
+* 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.
+*/
+function applyProjectedLocale(projection) {
+	if (!projection.enabled) return null;
+	const wanted = [];
+	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;
+	const resolved = {
+		catalogLocale,
+		formattingLocale: (matched ? formattingLocaleOf(matched.range) : null) ?? 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, projection) {
+	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": 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) {
+	try {
+		return get();
+	} catch {
+		return null;
+	}
+}
+//#endregion
+export { applyProjectedLocale };

package/dist/browser/signals.d.ts

@@ -0,0 +1,36 @@
+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 declare function readBrowserSignals(config: Pick<BrowserChain, "queryParam" | "storageKey">): BrowserLocaleSignals;
+/** Remember `locale` on this device. Silent when storage is unavailable — a preference is not worth a throw. */
+export declare function rememberBrowserLocale(locale: string, config: Pick<BrowserChain, "storageKey">): void;
+/**
+ * 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 declare function applyDocumentLocale(locale: string, direction: "ltr" | "rtl"): void;
+//# sourceMappingURL=signals.d.ts.map

package/dist/browser/signals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signals.d.ts","sourceRoot":"","sources":["../../src/browser/signals.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAE7E;;;;;;;GAOG;AAEH;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,IAAI,CAAC,YAAY,EAAE,YAAY,GAAG,YAAY,CAAC,GAAG,oBAAoB,CAShH;AAED,gHAAgH;AAChH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,YAAY,EAAE,YAAY,CAAC,GAAG,IAAI,CAOpG;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,GAAG,KAAK,GAAG,IAAI,CAQlF"}

package/dist/browser/signals.js

@@ -0,0 +1,70 @@
+//#region src/browser/signals.ts
+/**
+* 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.
+*/
+function readBrowserSignals(config) {
+	return {
+		query: read(() => new URL(window.location.href).searchParams.get(config.queryParam)),
+		storage: read(() => window.localStorage.getItem(config.storageKey)),
+		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. */
+function rememberBrowserLocale(locale, config) {
+	try {
+		window.localStorage.setItem(config.storageKey, locale);
+	} catch {}
+}
+/**
+* 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.
+*/
+function applyDocumentLocale(locale, direction) {
+	try {
+		document.documentElement.lang = locale;
+		document.documentElement.dir = direction;
+	} catch {}
+}
+/** Read a list off a global, answering `null` rather than throwing when the global is absent. */
+function readList(get) {
+	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) {
+	try {
+		return get();
+	} catch {
+		return null;
+	}
+}
+//#endregion
+export { applyDocumentLocale, readBrowserSignals, rememberBrowserLocale };

package/dist/capability.d.ts

@@ -0,0 +1,53 @@
+import { type Capability } from "@pithy-sh/core/src/capability/capability";
+import type { LocaleCatalogs, MessageCatalog } from "@pithy-sh/core/src/i18n/catalog";
+import { I18nConfig, type I18nConfigInput } from "./config/config";
+/**
+ * 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 declare function i18n(config?: I18nConfigInput): I18nCapability;
+/** Whether a capability is the i18n capability — carries its resolved config and composed catalogs. */
+export declare function isI18nCapability(capability: Capability): capability is I18nCapability;
+//# sourceMappingURL=capability.d.ts.map

package/dist/capability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability.d.ts","sourceRoot":"","sources":["../src/capability.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,UAAU,EAAoB,MAAM,0CAA0C,CAAC;AAC7F,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAKtF,OAAO,EAAE,UAAU,EAAE,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAKnE;;;;;;GAMG;AACH,MAAM,WAAW,cAAe,SAAQ,UAAU;IAChD,sGAAsG;IACtG,UAAU,EAAE,UAAU,CAAC;IACvB,qGAAqG;IACrG,gBAAgB,EAAE,cAAc,CAAC;IACjC,wEAAwE;IACxE,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,cAAc,GAAG,SAAS,CAAC,EAAE,CAAC;CACpE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,IAAI,CAAC,MAAM,GAAE,eAAoB,GAAG,cAAc,CA0EjE;AAED,uGAAuG;AACvG,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,UAAU,GAAG,UAAU,IAAI,cAAc,CAErF"}

package/dist/capability.js

@@ -0,0 +1,110 @@
+import { KIT_CATALOGS } from "./catalogs/kit.js";
+import { I18nConfig } from "./config/config.js";
+import { i18nMiddleware } from "./http/middleware.js";
+import { i18nSettings } from "./settings/coverage.js";
+import { PACKAGE_VERSION } from "./version.generated.js";
+import { defineCapability } from "@pithy-sh/core/src/capability/capability";
+import { composeMessages } from "@pithy-sh/core/src/i18n/registry";
+import { DEFAULT_LOCALE } from "@pithy-sh/core/src/i18n/translator";
+//#region src/capability.ts
+/**
+* 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.
+*/
+function i18n(config = {}) {
+	const resolved = I18nConfig.parse(config);
+	let composedMessages = {};
+	const layersFor = (locale) => [
+		resolved.messages[locale],
+		resolved.messages[resolved.defaultLocale],
+		KIT_CATALOGS[locale],
+		composedMessages[locale],
+		composedMessages[resolved.defaultLocale],
+		composedMessages[DEFAULT_LOCALE]
+	];
+	const capability = defineCapability({
+		name: "i18n",
+		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: () => ({
+			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
+	});
+	Object.defineProperty(composed, "composedMessages", {
+		get: () => composedMessages,
+		enumerable: true
+	});
+	return composed;
+}
+/** Whether a capability is the i18n capability — carries its resolved config and composed catalogs. */
+function isI18nCapability(capability) {
+	return capability.name === "i18n" && "i18nConfig" in capability;
+}
+//#endregion
+export { i18n, isI18nCapability };

package/dist/catalogs/browser.d.ts

@@ -0,0 +1,13 @@
+import type { MessageCatalog } from "@pithy-sh/core/src/i18n/catalog";
+/**
+ * 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 declare function hasKitCatalog(locale: string): boolean;
+/** The kit's catalog for `locale`, or an empty one when the kit writes nothing in that language. */
+export declare function loadKitCatalog(locale: string): Promise<MessageCatalog>;
+//# sourceMappingURL=browser.d.ts.map

package/dist/catalogs/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../../src/catalogs/browser.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAkBtE;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAErD;AAED,oGAAoG;AACpG,wBAAsB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAI5E"}

package/dist/catalogs/browser.js

@@ -0,0 +1,33 @@
+//#region src/catalogs/browser.ts
+/**
+* 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 = { es: () => import("./es/index.js").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.
+*/
+function hasKitCatalog(locale) {
+	return Object.hasOwn(LOADERS, locale);
+}
+/** The kit's catalog for `locale`, or an empty one when the kit writes nothing in that language. */
+async function loadKitCatalog(locale) {
+	if (!hasKitCatalog(locale)) return {};
+	const load = LOADERS[locale];
+	return load ? await load() : {};
+}
+//#endregion
+export { hasKitCatalog, loadKitCatalog };

package/dist/catalogs/es/errors.d.ts

@@ -0,0 +1,30 @@
+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 declare const esErrors: MessageCatalog;
+//# sourceMappingURL=errors.d.ts.map

package/dist/catalogs/es/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/catalogs/es/errors.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAEtE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,QAAQ,EAAE,cAkKtB,CAAC"}