@mccaskie-labs/workbench-strings 0.0.0-stage → 0.1.0

package/dist/detect.js

@@ -0,0 +1,108 @@
+// Choosing the language for a request (internationalization standard §7).
+//
+//   URL prefix -> cookie -> account -> country -> Accept-Language -> default
+//
+// Country outranks Accept-Language on purpose: in the Philippines and most
+// markets like it, a phone reports English whatever its owner reads, so the
+// header is evidence about the phone and the country is evidence about the
+// person (§7.2). The header stays, below country, for someone abroad who set
+// their home language deliberately.
+//
+// The review gate (§10.4): the prefix, the cookie and the account are choices
+// the person made, and are always honoured. Everything below them is inferred,
+// and an inferred language that no named reviewer has signed off resolves to
+// the base instead. Accept-Language counts as inferred: a browser language set
+// years ago is not a choice made about this app. To change that, move "header"
+// out of INFERRED below; it is the one line.
+const INFERRED = new Set(["country", "header", "default"]);
+/** The edge's "country unknown" answers: XX (unknown), T1 (Tor). They fall through to the header. */
+const UNKNOWN_COUNTRIES = new Set(["XX", "T1"]);
+function live(rules, value) {
+    return value != null && rules.locales.includes(value) ? value : undefined;
+}
+/** Accept-Language tags, best first by q; q=0 and `*` dropped, ties keep their order. */
+export function parseAcceptLanguage(header) {
+    if (!header)
+        return [];
+    return header
+        .split(",")
+        .map((part, i) => {
+        const [tag = "", ...params] = part.trim().split(";");
+        const q = params.map((p) => /^\s*q\s*=\s*([0-9.]+)\s*$/i.exec(p)).find(Boolean);
+        const weight = q ? Math.min(1, Number(q[1])) : 1;
+        return { tag: tag.trim(), weight: Number.isFinite(weight) ? weight : 0, i };
+    })
+        .filter((t) => t.tag && t.tag !== "*" && t.weight > 0)
+        .sort((a, b) => b.weight - a.weight || a.i - b.i)
+        .map((t) => t.tag);
+}
+/** The best live locale for an Accept-Language header: exact tag, then alias, then a language only one locale has. */
+export function matchAcceptLanguage(rules, header) {
+    const aliases = new Map(Object.entries(rules.aliases).map(([k, v]) => [k.toLowerCase(), v]));
+    for (const tag of parseAcceptLanguage(header)) {
+        const lower = tag.toLowerCase();
+        const exact = rules.locales.find((l) => l.toLowerCase() === lower);
+        if (exact)
+            return exact;
+        const language = lower.split("-")[0];
+        const alias = aliases.get(lower) ?? aliases.get(language);
+        if (alias && rules.locales.includes(alias))
+            return alias;
+        const same = rules.locales.filter((l) => l.toLowerCase().split("-")[0] === language);
+        if (same.length === 1)
+            return same[0];
+    }
+    return undefined;
+}
+/** Resolves the locale for one request. */
+export function resolveLocale(signals, rules) {
+    const chosen = (live(rules, signals.prefix) && { locale: signals.prefix, source: "prefix" }) ||
+        (live(rules, signals.cookie) && { locale: signals.cookie, source: "cookie" }) ||
+        (live(rules, signals.account) && { locale: signals.account, source: "account" });
+    if (chosen)
+        return { ...chosen, gated: false };
+    const inferred = infer(signals, rules);
+    if (INFERRED.has(inferred.source) && inferred.locale !== rules.base && !rules.reviewed(inferred.locale)) {
+        return { locale: rules.base, source: inferred.source, gated: true };
+    }
+    return { ...inferred, gated: false };
+}
+function infer(signals, rules) {
+    const country = signals.country?.trim().toUpperCase();
+    const known = country !== undefined && /^[A-Z]{2}$/.test(country) && !UNKNOWN_COUNTRIES.has(country);
+    if (known) {
+        const local = rules.countries[country];
+        if (local && rules.locales.includes(local))
+            return { locale: local, source: "country" };
+    }
+    const fromHeader = matchAcceptLanguage(rules, signals.acceptLanguage);
+    if (fromHeader)
+        return { locale: fromHeader, source: "header" };
+    // Someone we know is elsewhere gets the base; the default is for the truly
+    // unknown visitor, including local development where there is no country.
+    return { locale: known ? rules.base : rules.defaultLocale, source: "default" };
+}
+/** The cookie that remembers a choice. `__Host-` makes the browser refuse it with a Domain or without Secure. */
+export const LOCALE_COOKIE = "__Host-locale";
+const YEAR = 60 * 60 * 24 * 365;
+/** A Set-Cookie value remembering `locale` for a year. Lax, so a visitor arriving from a link keeps their language. */
+export function localeCookie(locale) {
+    return `${LOCALE_COOKIE}=${encodeURIComponent(locale)}; Path=/; Max-Age=${YEAR}; Secure; SameSite=Lax`;
+}
+/** The locale cookie's value from a Cookie header, if any. */
+export function readLocaleCookie(header) {
+    if (!header)
+        return undefined;
+    for (const part of header.split(";")) {
+        const eq = part.indexOf("=");
+        if (eq === -1 || part.slice(0, eq).trim() !== LOCALE_COOKIE)
+            continue;
+        try {
+            return decodeURIComponent(part.slice(eq + 1).trim());
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return undefined;
+}

package/dist/errors.d.ts

@@ -0,0 +1,5 @@
+export type StringsErrorCode = "invalid_options" | "invalid_catalogue" | "invalid_string" | "missing_string" | "missing_value" | "no_reviewer";
+export declare class WorkbenchStringsError extends Error {
+    readonly code: StringsErrorCode;
+    constructor(code: StringsErrorCode, message: string);
+}

package/dist/errors.js

@@ -0,0 +1,10 @@
+// Every failure the package raises is a WorkbenchStringsError with a stable
+// code. Callers branch on `code`, never on the message.
+export class WorkbenchStringsError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "WorkbenchStringsError";
+        this.code = code;
+    }
+}

package/dist/format.d.ts

@@ -0,0 +1,23 @@
+export type Values = Readonly<Record<string, string | number | null | undefined>>;
+type Inner = string | {
+    v: string;
+} | {
+    count: true;
+};
+type Part = string | {
+    v: string;
+} | {
+    plural: string;
+    arms: ReadonlyMap<string, readonly Inner[]>;
+};
+export type Message = readonly Part[];
+/** Parses one string. Throws invalid_string with the reason. */
+export declare function parseMessage(src: string): Message;
+/**
+ * The placeholders a string uses, sorted, with a plural marked: "count#plural".
+ * Every language must use the same set as the base (§9.1).
+ */
+export declare function placeholdersOf(message: Message): string[];
+/** Fills a parsed string for one locale. */
+export declare function formatMessage(message: Message, locale: string, values?: Values): string;
+export {};

package/dist/format.js

@@ -0,0 +1,215 @@
+// The message format: a deliberately small subset of ICU (internationalization
+// standard §9). Named placeholders, `{name}`, and one level of plural:
+//
+//   "{count, plural, =0 {No rooms} one {# room} other {# rooms}}"
+//
+// No select, no selectordinal, no nesting, no escaping. Widen it when a string
+// needs it, not in advance. It lives in this one module so that if it is ever
+// replaced, the keys, the files, the chain and every call site survive.
+//
+// - A missing value leaves `{name}` visible: a visible placeholder is a bug
+//   report, a silently empty sentence is a bug that ships.
+// - The plural arm is chosen by `Intl.PluralRules` for the real locale, never
+//   `n === 1`, with exact arms (`=0`) checked first; `other` is required.
+// - `#` renders through `Intl.NumberFormat` (2,000). A `{name}` value renders
+//   as given, so a year or an order number is never grouped: format amounts
+//   and dates before passing them (workbench-country does it per country).
+import { WorkbenchStringsError } from "./errors.js";
+const NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const SELECTOR = /^(=\d+|zero|one|two|few|many|other)$/;
+function fail(src, why) {
+    throw new WorkbenchStringsError("invalid_string", `${why} in "${src}"`);
+}
+/** Parses one string. Throws invalid_string with the reason. */
+export function parseMessage(src) {
+    const parts = [];
+    let text = "";
+    let i = 0;
+    while (i < src.length) {
+        const c = src[i];
+        if (c === "}")
+            fail(src, "an unmatched }");
+        if (c !== "{") {
+            text += c;
+            i++;
+            continue;
+        }
+        if (text)
+            parts.push(text);
+        text = "";
+        const close = src.indexOf("}", i);
+        const comma = src.indexOf(",", i);
+        if (close === -1)
+            fail(src, "an unclosed {");
+        if (comma === -1 || comma > close) {
+            const name = src.slice(i + 1, close).trim();
+            if (!NAME.test(name))
+                fail(src, `a bad placeholder name "{${name}}"`);
+            parts.push({ v: name });
+            i = close + 1;
+            continue;
+        }
+        const name = src.slice(i + 1, comma).trim();
+        if (!NAME.test(name))
+            fail(src, `a bad placeholder name "${name}"`);
+        const kindEnd = src.indexOf(",", comma + 1);
+        if (kindEnd === -1 || src.slice(comma + 1, kindEnd).trim() !== "plural") {
+            fail(src, `"{${name}, ...}" that is not a plural (only plural is supported)`);
+        }
+        i = kindEnd + 1;
+        const arms = new Map();
+        for (;;) {
+            while (i < src.length && /\s/.test(src[i]))
+                i++;
+            if (i >= src.length)
+                fail(src, "an unclosed plural");
+            if (src[i] === "}") {
+                i++;
+                break;
+            }
+            const open = src.indexOf("{", i);
+            if (open === -1)
+                fail(src, "a plural arm with no text");
+            const selector = src.slice(i, open).trim();
+            if (!SELECTOR.test(selector))
+                fail(src, `a bad plural arm "${selector}"`);
+            if (arms.has(selector))
+                fail(src, `the plural arm "${selector}" twice`);
+            const end = src.indexOf("}", open + 1);
+            if (end === -1)
+                fail(src, "an unclosed plural arm");
+            // An arm may hold {name} placeholders: walk to the brace that closes it.
+            const inner = [];
+            let j = open + 1;
+            let armText = "";
+            for (;;) {
+                if (j >= src.length)
+                    fail(src, "an unclosed plural arm");
+                const d = src[j];
+                if (d === "}")
+                    break;
+                if (d === "{") {
+                    const k = src.indexOf("}", j);
+                    if (k === -1)
+                        fail(src, "an unclosed {");
+                    const v = src.slice(j + 1, k).trim();
+                    if (!NAME.test(v))
+                        fail(src, `a plural inside a plural, or a bad placeholder "{${v}}"`);
+                    if (armText)
+                        inner.push(armText);
+                    armText = "";
+                    inner.push({ v });
+                    j = k + 1;
+                    continue;
+                }
+                if (d === "#") {
+                    if (armText)
+                        inner.push(armText);
+                    armText = "";
+                    inner.push({ count: true });
+                }
+                else {
+                    armText += d;
+                }
+                j++;
+            }
+            if (armText)
+                inner.push(armText);
+            arms.set(selector, inner);
+            i = j + 1;
+        }
+        if (!arms.has("other"))
+            fail(src, `the plural on "${name}" with no "other" arm`);
+        parts.push({ plural: name, arms });
+    }
+    if (text)
+        parts.push(text);
+    return parts;
+}
+/**
+ * The placeholders a string uses, sorted, with a plural marked: "count#plural".
+ * Every language must use the same set as the base (§9.1).
+ */
+export function placeholdersOf(message) {
+    const out = new Set();
+    for (const p of message) {
+        if (typeof p === "string")
+            continue;
+        if ("v" in p) {
+            out.add(p.v);
+            continue;
+        }
+        out.add(`${p.plural}#plural`);
+        for (const arm of p.arms.values())
+            for (const q of arm)
+                if (typeof q !== "string" && "v" in q)
+                    out.add(q.v);
+    }
+    return [...out].sort();
+}
+const numberFormats = new Map();
+const pluralRules = new Map();
+/**
+ * A tag Intl will take: the locale itself, else its language, else the
+ * runtime default. A tag Intl refuses never throws here (§11, "unknown locale
+ * survives"). Intl only picks plural arms and formats numbers; it never
+ * supplies words (§9.4).
+ */
+function intlLocale(locale) {
+    const tries = [locale, locale.split("-")[0]];
+    for (const t of tries) {
+        try {
+            if (Intl.PluralRules.supportedLocalesOf([t]).length)
+                return t;
+        }
+        catch {
+            // RangeError for a malformed tag: try the next.
+        }
+    }
+    return undefined;
+}
+function numberFormat(locale) {
+    let f = numberFormats.get(locale);
+    if (!f)
+        numberFormats.set(locale, (f = new Intl.NumberFormat(intlLocale(locale))));
+    return f;
+}
+function pluralRule(locale) {
+    let r = pluralRules.get(locale);
+    if (!r)
+        pluralRules.set(locale, (r = new Intl.PluralRules(intlLocale(locale))));
+    return r;
+}
+function value(name, values) {
+    const v = values[name];
+    if (v === undefined || v === null)
+        return `{${name}}`;
+    return String(v);
+}
+/** Fills a parsed string for one locale. */
+export function formatMessage(message, locale, values = {}) {
+    let out = "";
+    for (const p of message) {
+        if (typeof p === "string")
+            out += p;
+        else if ("v" in p)
+            out += value(p.v, values);
+        else {
+            const n = values[p.plural];
+            if (typeof n !== "number" || !Number.isFinite(n)) {
+                out += `{${p.plural}}`;
+                continue;
+            }
+            const arm = p.arms.get(`=${n}`) ?? p.arms.get(pluralRule(locale).select(n)) ?? p.arms.get("other");
+            for (const q of arm) {
+                if (typeof q === "string")
+                    out += q;
+                else if ("v" in q)
+                    out += value(q.v, values);
+                else
+                    out += numberFormat(locale).format(n);
+            }
+        }
+    }
+    return out;
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { defineStrings, NAMESPACES, type EmailName, type EmailPart, type MissingString, type StringKey, type Strings, type StringsOptions } from "./strings.ts";
+export { LOCALE_COOKIE, localeCookie, matchAcceptLanguage, parseAcceptLanguage, readLocaleCookie, resolveLocale, type Detection, type DetectionSource, type LocaleRules, type LocaleSignals, } from "./detect.ts";
+export { readCatalogue, readReview, stripGlosses, type Catalogue, type Review } from "./catalogue.ts";
+export { formatMessage, parseMessage, placeholdersOf, type Message, type Values } from "./format.ts";
+export { WORKBENCH_LANGUAGES, type WorkbenchLanguage } from "./languages.ts";
+export { WorkbenchStringsError, type StringsErrorCode } from "./errors.ts";

package/dist/index.js

@@ -0,0 +1,10 @@
+// @mccaskie-labs/workbench-strings: the words an app's own screens and emails
+// say. SERVER ONLY: the catalogue holds every language, so importing it into
+// browser code would ship them all to every visitor. Look words up on the
+// server and pass the finished words to the page.
+export { defineStrings, NAMESPACES } from "./strings.js";
+export { LOCALE_COOKIE, localeCookie, matchAcceptLanguage, parseAcceptLanguage, readLocaleCookie, resolveLocale, } from "./detect.js";
+export { readCatalogue, readReview, stripGlosses } from "./catalogue.js";
+export { formatMessage, parseMessage, placeholdersOf } from "./format.js";
+export { WORKBENCH_LANGUAGES } from "./languages.js";
+export { WorkbenchStringsError } from "./errors.js";

package/dist/languages.d.ts

@@ -0,0 +1,4 @@
+import { capabilities } from "@mccaskie-labs/workbench-config";
+export type WorkbenchLanguage = (typeof capabilities.ai.allowed.spellings)[number];
+/** Every language an app may serve, as BCP 47 tags. */
+export declare const WORKBENCH_LANGUAGES: readonly WorkbenchLanguage[];

package/dist/languages.js

@@ -0,0 +1,7 @@
+// The one Workbench language list. It is the spelling list the Gateway's
+// voices already use (docs/spec.md §2.8, capabilities/ai.json `spellings`), so
+// an app's screens and its AI writing name languages the same way. A new
+// language is added to that manifest first.
+import { capabilities } from "@mccaskie-labs/workbench-config";
+/** Every language an app may serve, as BCP 47 tags. */
+export const WORKBENCH_LANGUAGES = [...capabilities.ai.allowed.spellings];

package/dist/strings.d.ts

@@ -0,0 +1,96 @@
+import type { WorkbenchEnv } from "@mccaskie-labs/workbench-config";
+import { type Catalogue, type Review } from "./catalogue.ts";
+import { type Detection, type LocaleRules } from "./detect.ts";
+import { type Values } from "./format.ts";
+/** The name groups a key must start with (§5.3). A new class of string adds a group here, by PR. */
+export declare const NAMESPACES: readonly ["ui", "enum", "question", "validation", "email", "notification", "page", "error", "meta"];
+/** A key of the base catalogue that holds words (not a `_` marker). */
+export type StringKey<B> = Exclude<Extract<keyof B, string>, `_${string}`>;
+/** The email names among a catalogue's keys: `email.<name>.<part>`. */
+export type EmailName<K extends string> = string extends K ? string : K extends `email.${infer N}.${string}` ? N : never;
+/** The parts of one email. */
+export type EmailPart<K extends string, N extends string> = string extends K ? string : K extends `email.${N}.${infer P}` ? P : never;
+/** A missing word: logged with the locale asked for and the one it came from. */
+export interface MissingString {
+    key: string;
+    requested: string;
+    /** Where the word was found instead, or null when it is missing everywhere. */
+    resolved: string | null;
+}
+export interface StringsOptions<B extends Catalogue> {
+    /** WORKBENCH_ENV. In production a translated language needs a named reviewer. */
+    env: WorkbenchEnv;
+    /** The base locale and its catalogue: the language the words are written in, complete, with no glosses. */
+    base: {
+        locale: string;
+        strings: B;
+    };
+    /** Every other live locale's GENERATED catalogue (strings/runtime/), never the authored one. */
+    translations?: Readonly<Record<string, Catalogue>>;
+    /** The live locales in the order the switcher shows them, the base included. Each must be a Workbench language. */
+    locales: readonly string[];
+    /** What an unknown visitor sees. Defaults to the base. Often not the base: it is the audience's language. */
+    defaultLocale?: string;
+    /** Locales planned but not live. Declared here, absent from `locales`, with no catalogue. */
+    planned?: readonly string[];
+    /** A locale's parent, e.g. a register's parent language. Every chain ends at the base. */
+    parents?: Readonly<Record<string, string>>;
+    /** Country code to locale. Defaults to each live locale's region when only one locale has it (en-PH: PH). */
+    countries?: Readonly<Record<string, string>>;
+    /** Extra Accept-Language tags to locale, such as an old tag some phones still send. */
+    aliases?: Readonly<Record<string, string>>;
+    /** URL prefixes. Defaults to the lower-case tag (en-ph). Every locale has one; none owns the bare tree. */
+    prefixes?: Readonly<Record<string, string>>;
+    /** Where missing words are reported. Defaults to one JSON line on console.warn per key and locale. */
+    onMissing?: (missing: MissingString) => void;
+}
+export interface Strings<K extends string = string> {
+    readonly base: string;
+    readonly locales: readonly string[];
+    readonly defaultLocale: string;
+    readonly planned: readonly string[];
+    /** Every key with words in the base. */
+    readonly keys: readonly K[];
+    /** The rules detect() uses, the review gate included. */
+    readonly rules: LocaleRules;
+    /** Each live locale's URL prefix. */
+    readonly prefixes: Readonly<Record<string, string>>;
+    /** The parents passed in, for the test kit. */
+    readonly parents: Readonly<Record<string, string>>;
+    /** A live locale's catalogue as defineStrings was given it, for the test kit. */
+    catalogue(locale: string): Catalogue;
+    /** The fallback chain for a locale: itself, its parents, then the base. */
+    chain(locale: string): readonly string[];
+    /** A live locale's review markers. */
+    review(locale: string): Review;
+    /** True for the base, or a locale whose catalogue, and every translated one on its chain, has `_review.signed_off`. */
+    reviewed(locale: string): boolean;
+    /** True when the base has words for `key`. For keys built at run time, such as workbench-forms' validation codes. */
+    has(key: string): key is K;
+    /** The words for a key. A word missing in `locale` comes from the next locale on its chain and is logged. */
+    t(locale: string, key: K, values?: Values): string;
+    /** Several keys at once, to pass to a page as finished words. Use t() for a string with placeholders. */
+    pick<P extends K>(locale: string, keys: readonly P[]): Record<P, string>;
+    /**
+     * An email's words, `email.<name>.<part>`, in the recipient's saved
+     * language (pass it through recipientLocale). Missing in that language and
+     * in the base, it throws missing_string, and a value it needs that is not
+     * passed throws missing_value: an email has nobody watching it fail.
+     */
+    email<N extends EmailName<K>>(locale: string, name: N, part: EmailPart<K, N>, values?: Values): string;
+    /** A saved language as a live locale; anything else is the base. For emails sent with nobody present. */
+    recipientLocale(saved: string | null | undefined): string;
+    /** The language for a request, from its URL prefix, cookie, the account's saved language, country and header. */
+    detect(request: Request, options?: {
+        account?: string | null;
+    }): Detection;
+    /** The locale a path's prefix names, and the rest of the path. Null when the path has no prefix. */
+    localeFromPath(pathname: string): {
+        locale: string;
+        rest: string;
+    } | null;
+    /** A Set-Cookie value that remembers a chosen locale for a year. */
+    cookie(locale: string): string;
+}
+/** Sets up an app's strings. Throws WorkbenchStringsError at start when a rule is broken. */
+export declare function defineStrings<B extends Catalogue>(options: StringsOptions<B>): Strings<StringKey<B>>;