@tapestry-ui/i18n 0.0.0-stage → 0.2.0

package/LICENSE

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

package/README.md

@@ -1,3 +1,110 @@
-# Temporary Holding Version
+# @tapestry-ui/i18n
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A small i18n core for Preact apps. **The app sets keys, the DOM resolves.**
+
+A **utility**, not a component — it renders nothing. Part of
+[Tapestry UI](https://github.com/ryurage/brandonminton), lifted from
+Brandskviða, which has run this shape across eleven locales since 2026-09.
+
+```bash
+npm i @tapestry-ui/i18n
+```
+
+```ts
+// en.ts — the source of truth. Keys name WHERE a string lives, never what it says.
+export const en = {
+  'gaps.title': 'Intel gaps',
+  'gaps.toggle.open': '{n, plural, one {# open gap} other {# open gaps}}',
+  'greeting.partner': 'Evening, {who}.',
+} as const;
+export type MsgKey = keyof typeof en;
+```
+
+```ts
+// i18n.ts — the three app-specific facts, and nothing else
+export const { translate, textOf, message, locale, setLocale } = createI18n({
+  source: en,
+  catalogs: { es },
+  registry: [{ code: 'en', endonym: 'English' }, { code: 'es', endonym: 'Español' }],
+  storageKey: 'my-app-locale',
+  sourceCode: 'en',
+});
+```
+
+```tsx
+<h2>{translate('gaps.title')}</h2>
+<p>{translate('gaps.toggle.open', { n: 12 })}</p>
+```
+
+`locale` is a signal, so `setLocale('es')` re-renders every visible string. No
+reload, no provider threaded through the tree.
+
+## Three rules it exists to enforce
+
+**Per-key fallback.** A locale file is `Partial<Record<MsgKey, string>>` on
+purpose. Ship forty keys today and four hundred next month; anything absent
+falls through to the source **key by key**, never to a blank string. An empty
+stub is a valid locale.
+
+**Keys say WHERE, not what.** `tile.cash.title`, not `cashAndRunway`. A key that
+describes the text has to be renamed when the text changes, which nobody does.
+
+**Your data is not copy.** A person's name, a property, something a user typed —
+those are content. They must not be in the catalog, because a translator must
+not be able to reach them. They arrive as `{vars}`.
+
+## The pseudo-locale is the point
+
+`setLocale('pseudo')` generates a catalog from the source: accented look-alikes,
+~35% padding, `[brackets]`.
+
+> **Unbracketed text on screen is a hardcoded string your extraction missed.**
+> Overflowing text is a layout that assumed English lengths.
+
+A grep can only see literals it recognises. The pseudo-locale sees everything
+that reaches the screen, which is why it is the real meter.
+
+It mangles the words inside a plural's branches but leaves the syntax alone —
+`other {…}` has to survive, or the parser stops finding the branch. (That was a
+real bug, found by the pseudo-locale catching itself.)
+
+## Plurals
+
+`{n, plural, one {# thing} other {# things}}`, backed by `Intl.PluralRules`,
+with `#` as the count. **Any CLDR category** is accepted, so a language needing
+`few` and `many` writes them, and a language that never does never has to. A
+missing category falls back to `other`.
+
+Never build a plural by concatenation, and never write `N item(s)` — those are
+English rules wearing a disguise.
+
+## Tokens your catalog must not contain
+
+```ts
+createI18n({ ..., tokens: { name: (id, tag) => NAMES[locale][id][tag ?? 'nom'] } })
+```
+
+`{name.jon}` and `{name.jon:gen}` are handed to your resolver. This is how
+Brandskviða transliterates Norse names into Cyrillic and declines them, without
+the library ever learning what a Norse name is.
+
+## API
+
+| | |
+|---|---|
+| `createI18n(options)` | the factory; everything it returns is typed to **your** keys |
+| `translate(key, vars?)` | resolve now |
+| `textOf(msg)` | resolve a `Msg`; a raw string passes through verbatim |
+| `message(key, vars?)` | build a `Msg` for a call site that carries one |
+| `keyOf(msg)` | compare **keys**, never rendered text |
+| `locale` / `setLocale` | the signal, and the setter that persists + stamps `<html lang>` |
+| `pseudoize`, `resolveLocale`, `resolveMessage` | pure, exported, and where the logic lives |
+
+Locale resolution: `?lang=` → saved → `navigator.language` → source.
+
+Names read like English by house law: **translate · textOf · message.** Never a
+lazy `t()`.
+
+## License
+
+MIT © Brandon Minton

package/dist/format.d.ts

@@ -0,0 +1,18 @@
+export type Vars = Record<string, string | number>;
+/** Resolvers for `{group.id}` tokens, by group name. */
+export type Tokens = Record<string, (id: string, tag?: string) => string>;
+export interface FormatOptions {
+    /** Locale whose CLDR plural rules pick the branch. Defaults to English. */
+    plurals?: string;
+    tokens?: Tokens;
+}
+/**
+ * One message, with its plurals chosen, its tokens resolved and its vars filled.
+ *
+ * Order matters and is not arbitrary: plurals first, because a branch can itself
+ * contain `{vars}`; then tokens, whose `{group.id}` shape would otherwise be
+ * mistaken for a var; then the vars. A var with no value is LEFT AS ITS
+ * PLACEHOLDER rather than blanked — a visible `{who}` is a bug report, and an
+ * empty space is a mystery.
+ */
+export declare function formatMessage(template: string, vars?: Vars, options?: FormatOptions): string;

package/dist/format.js

@@ -0,0 +1,58 @@
+// Filling one message in. The pure half of the library, and deliberately its own
+// module: this file imports NOTHING.
+//
+// Why that matters. createI18n is built on a signal, so importing it drags in
+// @preact/signals and preact — correct in a browser, wrong in a server that only
+// needs to render the source catalog. A Cloudflare Worker that refuses a bad edit
+// has to say why in words, and the words belong in the same catalog the browser
+// reads. So the formatting lives here, both halves use it, and there is exactly
+// one implementation of "what does {n, plural, …} mean".
+//
+// Reachable as @tapestry-ui/i18n/format.
+/**
+ * `{count, plural, one {…} other {…}}` — the var name, then the branch list.
+ *
+ * A branch may itself hold `{vars}`, so its content is "anything but braces, or
+ * one braced run" rather than `[^}]*`. The simpler version stopped at the first
+ * `}` it met, which for "one {# story for {who}}" meant the whole plural failed
+ * to match and the reader got the template. No catalog had nested one yet;
+ * pseudoize() in i18n.ts already knew better, and now both halves agree.
+ */
+const BRANCH_BODY = "(?:[^{}]|\\{[^{}]*\\})*";
+const PLURAL = new RegExp(`\\{(\\w+), plural,((?: \\w+ \\{${BRANCH_BODY}\\})+)\\}`, "g");
+/** One ` name {text}` branch inside a plural. */
+const PLURAL_BRANCH = new RegExp(` (\\w+) \\{(${BRANCH_BODY})\\}`, "g");
+/** `{var}`. */
+const PLACEHOLDER = /\{(\w+)\}/g;
+/** `{group.id}` or `{group.id:tag}` — a token an app resolves for itself. */
+const TOKEN = /\{(\w+)\.(\w+)(?::(\w+))?\}/g;
+/**
+ * One message, with its plurals chosen, its tokens resolved and its vars filled.
+ *
+ * Order matters and is not arbitrary: plurals first, because a branch can itself
+ * contain `{vars}`; then tokens, whose `{group.id}` shape would otherwise be
+ * mistaken for a var; then the vars. A var with no value is LEFT AS ITS
+ * PLACEHOLDER rather than blanked — a visible `{who}` is a bug report, and an
+ * empty space is a mystery.
+ */
+export function formatMessage(template, vars, options = {}) {
+    const pluralRules = new Intl.PluralRules(options.plurals ?? "en");
+    let out = template.replace(PLURAL, (_whole, varName, branchSource) => {
+        const count = Number(vars?.[varName] ?? 0);
+        const branches = {};
+        for (const found of branchSource.matchAll(PLURAL_BRANCH))
+            branches[found[1]] = found[2];
+        // `#` is the count, which is what spares a catalog "1 story"/"2 stories" twice
+        return (branches[pluralRules.select(count)] ?? branches.other ?? "").replace(/#/g, String(count));
+    });
+    if (options.tokens) {
+        out = out.replace(TOKEN, (whole, group, id, tag) => {
+            const resolve = options.tokens?.[group];
+            return resolve ? resolve(id, tag) : whole;
+        });
+    }
+    if (vars) {
+        out = out.replace(PLACEHOLDER, (whole, varName) => (varName in vars ? String(vars[varName]) : whole));
+    }
+    return out;
+}

package/dist/i18n.d.ts

@@ -0,0 +1,74 @@
+import { type Signal } from "@preact/signals";
+import { type Tokens, type Vars } from "./format";
+export { formatMessage } from "./format";
+export type { FormatOptions, Tokens } from "./format";
+/** A catalog is a flat map of key to source text. Keys name WHERE a string
+ *  lives, never what it says — `tile.cash.title`, not `cashAndRunway`. */
+export type Catalog = Record<string, string>;
+/** What a call site carries. A raw string is LEGACY during an extraction:
+ *  rendered verbatim, which is exactly what lets the pseudo-locale's bracket
+ *  test find text nobody has migrated yet. */
+export type Msg<K extends string> = string | {
+    k: K;
+    vars?: Vars;
+};
+export type { Vars } from "./format";
+export interface LocaleInfo<Code extends string> {
+    readonly code: Code;
+    /** The language's own name for itself, deliberately UNTRANSLATED — a Spanish
+     *  speaker must find "Español" whatever locale happens to be active. */
+    readonly endonym: string;
+}
+export interface I18nOptions<Source extends Catalog, Code extends string> {
+    /** The source of truth. Its keys become the key type for everything else. */
+    source: Source;
+    /**
+     * Every other locale, keyed by code. DELIBERATELY PARTIAL: a translation can
+     * ship forty keys today and four hundred next month and never fail typecheck
+     * or blank a render — resolveMessage falls through to the source key by key.
+     */
+    catalogs?: Partial<Record<Code, Partial<Record<keyof Source & string, string>>>>;
+    /** The locales a language menu may offer, in presentation order. The source
+     *  locale belongs here; the pseudo-locale never does. */
+    registry: readonly LocaleInfo<Code>[];
+    /** Where the choice is remembered. One per app, or they fight. */
+    storageKey: string;
+    /** The code the source catalog is written in. */
+    sourceCode: Code;
+    /** The tester-only generated locale. Reachable by ?lang=, never listed. */
+    pseudoCode?: string;
+    /**
+     * Token resolvers for `{group.id}` and `{group.id:tag}` placeholders, so an
+     * app can interpolate things a catalog must never contain — a proper name
+     * that crosses alphabets, say. The library stays ignorant of what they are.
+     */
+    tokens?: Tokens;
+}
+export declare function pseudoize(source: string): string;
+/**
+ * Resolution order: an explicit `?lang=` wins, then what was saved, then the
+ * browser's own preference, then the source language. Pure over its inputs so a
+ * test can lock it without a DOM.
+ */
+export declare function resolveLocale<Code extends string>(urlLang: string | null, saved: string | null, navigatorLanguage: string, supported: readonly string[], fallback: Code): Code;
+/**
+ * THE PER-KEY FALLBACK, which is what makes a partial catalog safe: a locale
+ * that ships a key uses it; anything else — a key it never reached, or a wholly
+ * empty stub — falls through to the source, never to a blank string. Pure, so
+ * the contract is directly testable with a synthetic catalog.
+ */
+export declare function resolveMessage<Source extends Catalog>(catalog: Partial<Record<keyof Source & string, string>>, source: Source, key: keyof Source & string): string;
+export interface I18n<Source extends Catalog, Code extends string> {
+    /** The key union, for typing a consumer's own helpers. Value is never read. */
+    readonly keyType: keyof Source & string;
+    readonly locale: Signal<Code | string>;
+    readonly registry: readonly LocaleInfo<Code>[];
+    setLocale(next: Code | string): void;
+    message(k: keyof Source & string, vars?: Vars): Msg<keyof Source & string>;
+    translate(k: keyof Source & string, vars?: Vars): string;
+    textOf(value: Msg<keyof Source & string> | null | undefined): string;
+    keyOf(value: Msg<keyof Source & string> | null | undefined): string | null;
+    /** Codes with a registered catalog, for a test's registry-agreement check. */
+    readonly catalogCodes: readonly string[];
+}
+export declare function createI18n<Source extends Catalog, Code extends string>(options: I18nOptions<Source, Code>): I18n<Source, Code>;

package/dist/i18n.js

@@ -0,0 +1,142 @@
+// @tapestry-ui/i18n — the loom's tongues, as a library.
+//
+// A UTILITY, not a component (Brandon's naming, 2026-10-08). The scope now
+// holds two kinds of thing: components that render — accordion, modal, tabs,
+// ask, combobox, tour — and utilities that do not. sortable is the other one:
+// a hook with no markup of its own. This has no markup either; it is a factory
+// and five functions.
+//
+// Lifted from Brandskviða, which has been running this shape across eleven
+// locales since 2026-09. The game is the pattern of record; this is the part of
+// it that knows nothing about any one app.
+//
+// THE SHAPE: THE APP SETS KEYS, THE DOM RESOLVES. A call site produces a key
+// (plus vars); the render resolves it against the active locale; `locale` is a
+// signal, so switching it re-renders every visible string with no reload and no
+// provider to thread through the tree.
+//
+// NAMES READ LIKE ENGLISH, by house law: translate · textOf · message. Never a
+// lazy `t()`.
+//
+// WHAT THIS DELIBERATELY DOES NOT DO: own your catalog, know your locale codes,
+// or understand your domain. createI18n() is a factory you hand a source
+// catalog; everything it returns is typed to YOUR keys, so a typo is a compile
+// error and a translation file that drifts fails the build.
+import { signal } from "@preact/signals";
+import { formatMessage } from "./format";
+export { formatMessage } from "./format";
+const PSEUDO_MAP = {
+    a: "å", e: "é", i: "ï", o: "ö", u: "û", y: "ý", c: "ç", n: "ñ", s: "š", z: "ž",
+    A: "Å", E: "É", I: "Ï", O: "Ö", U: "Û", C: "Ç", N: "Ñ", S: "Š", Z: "Ž", T: "Ŧ", L: "Ŀ",
+};
+/**
+ * Accented look-alikes, ~35% padding, and [brackets], with `{…}` placeholders
+ * left intact. Its whole job: UNBRACKETED TEXT ON SCREEN IS A HARDCODED STRING,
+ * and overflow is a layout that assumed English lengths.
+ */
+// A placeholder, INCLUDING a one-level-nested one. The obvious `\{[^}]*\}`
+// stops at the first inner brace, so it chops a plural in half and the
+// mangling then eats the word `other` — the branch the parser needs. Found by
+// the pseudo-locale catching itself, 2026-10-08.
+const PLACEHOLDER = /(\{[^{}]*(?:\{[^{}]*\}[^{}]*)*\})/;
+/** The shape of a plural, so its BRANCHES can be mangled while its SYNTAX is
+ *  left alone. Protecting the whole expression would keep `other` readable but
+ *  leave the human words inside it in plain English — half a pseudo-locale. */
+const PLURAL_SHAPE = /^\{(\w+), plural,((?: \w+ \{[^{}]*\})+)\}$/;
+const PLURAL_BRANCH = / (\w+) \{([^{}]*)\}/g;
+const mangleWords = (text) => text.replace(/[a-zA-Z]/g, ch => PSEUDO_MAP[ch] ?? ch);
+export function pseudoize(source) {
+    const mangled = source
+        .split(PLACEHOLDER)
+        .map(part => {
+        if (!part.startsWith("{"))
+            return mangleWords(part);
+        const plural = part.match(PLURAL_SHAPE);
+        if (!plural)
+            return part; // a plain {var} or {name.x} passes through whole
+        const branches = plural[2].replace(PLURAL_BRANCH, (_whole, category, body) => ` ${category} {${mangleWords(body)}}`);
+        return `{${plural[1]}, plural,${branches}}`;
+    })
+        .join("");
+    return `[${mangled}${"·".repeat(Math.max(0, Math.ceil(source.length * 0.35)))}]`;
+}
+/**
+ * Resolution order: an explicit `?lang=` wins, then what was saved, then the
+ * browser's own preference, then the source language. Pure over its inputs so a
+ * test can lock it without a DOM.
+ */
+export function resolveLocale(urlLang, saved, navigatorLanguage, supported, fallback) {
+    for (const candidate of [urlLang, saved, navigatorLanguage.split("-")[0]]) {
+        if (candidate && supported.includes(candidate))
+            return candidate;
+    }
+    return fallback;
+}
+/**
+ * THE PER-KEY FALLBACK, which is what makes a partial catalog safe: a locale
+ * that ships a key uses it; anything else — a key it never reached, or a wholly
+ * empty stub — falls through to the source, never to a blank string. Pure, so
+ * the contract is directly testable with a synthetic catalog.
+ */
+export function resolveMessage(catalog, source, key) {
+    return catalog[key] ?? source[key] ?? key;
+}
+export function createI18n(options) {
+    const { source, registry, storageKey, sourceCode, pseudoCode = "pseudo" } = options;
+    const catalogs = (options.catalogs ?? {});
+    const supported = [sourceCode, pseudoCode, ...Object.keys(catalogs)];
+    let pseudoCache = null;
+    const pseudoCatalog = () => {
+        pseudoCache ?? (pseudoCache = Object.fromEntries(Object.entries(source).map(([k, v]) => [k, pseudoize(v)])));
+        return pseudoCache;
+    };
+    const startup = () => {
+        try {
+            const url = new URLSearchParams(window.location.search).get("lang");
+            const saved = window.localStorage.getItem(storageKey);
+            return resolveLocale(url, saved, navigator.language || sourceCode, supported, sourceCode);
+        }
+        catch {
+            return sourceCode;
+        }
+    };
+    const locale = signal(typeof window === "undefined" ? sourceCode : startup());
+    const stampHtmlLang = (code) => {
+        try {
+            document.documentElement.lang = code === pseudoCode ? `${sourceCode}-x-pseudo` : code;
+        }
+        catch { /* no DOM, as in a test */ }
+    };
+    stampHtmlLang(locale.value);
+    const setLocale = (next) => {
+        locale.value = next;
+        try {
+            window.localStorage.setItem(storageKey, next);
+        }
+        catch { /* private mode */ }
+        stampHtmlLang(next);
+    };
+    const catalogFor = (code) => {
+        if (code === sourceCode)
+            return source;
+        if (code === pseudoCode)
+            return pseudoCatalog();
+        return catalogs[code] ?? {};
+    };
+    const translate = (key, vars) => formatMessage(resolveMessage(catalogFor(locale.value), source, key), vars, {
+        // the pseudo-locale is English wearing a costume; its plural rules are English's
+        plurals: locale.value === pseudoCode ? sourceCode : locale.value,
+        tokens: options.tokens,
+    });
+    return {
+        keyType: undefined,
+        locale,
+        registry,
+        setLocale,
+        catalogCodes: Object.keys(catalogs),
+        message: (k, vars) => (vars ? { k, vars } : { k }),
+        translate,
+        textOf: value => (value == null ? "" : typeof value === "string" ? value : translate(value.k, value.vars)),
+        keyOf: value => (value != null && typeof value === "object" ? value.k : null),
+    };
+}

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "@tapestry-ui/i18n",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "A small i18n core for Preact apps — a typed catalog, per-key fallback, CLDR plurals, and a pseudo-locale that makes untranslated text visible. The app sets keys, the DOM resolves.",
+  "license": "MIT",
+  "author": "Brandon Minton",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/i18n.d.ts",
+      "default": "./dist/i18n.js"
+    },
+    "./format": {
+      "types": "./dist/format.d.ts",
+      "default": "./dist/format.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "prepublishOnly": "npm run test && npm run build"
+  },
+  "peerDependencies": {
+    "@preact/signals": ">=1.3.0",
+    "preact": ">=10.24.0"
+  },
+  "devDependencies": {
+    "@preact/signals": "^2.0.0",
+    "jsdom": "^25.0.1",
+    "preact": "^10.29.4",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ryurage/brandonminton.git",
+    "directory": "packages/tapestry-ui/i18n"
+  },
+  "keywords": ["preact", "i18n", "l10n", "translation", "locale", "pseudo-locale", "signals", "tapestry-ui"]
+}