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

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# @mccaskie-labs/workbench-strings
+
+## 0.1.1
+
+### Patch Changes
+
+- No code change. The first version published by the publish workflow, which confirms the package's npm trusted publisher.
+
+## 0.1.0
+
+- First version: `defineStrings` (lookup with named placeholders and one level of plural, one fallback chain, detection with country before Accept-Language, the review gate, `email.<name>.<part>` lookups), the `workbench-strings build|check` command that strips back-translation glosses, and the test kit at `/testing` (`docs/spec.md` §10, 11 November 2026).

package/README.md

@@ -1,3 +1,115 @@
-# Temporary Holding Version
+# @mccaskie-labs/workbench-strings
 
-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.
+The words an app's own screens and emails say, for apps built on Workbench, a private platform. One file per language in the app's repository, one lookup with named placeholders and plurals, one fallback chain, language detection, back-translation notes stripped at build, the translation review gate, and the internationalization standard's tests as a kit. Published publicly so Workbench projects can install it with no token; it is not supported for other uses.
+
+It is separate from the Gateway's voices and language packs for AI writing (`docs/spec.md` §2.8): those guide what the AI drafts; this holds the product's fixed, reviewed words. It follows `internationalization.md` in Robert's project standards; section numbers below (§) are that standard's.
+
+**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. A browser bundle that imports the package gets a module that throws.
+
+```sh
+npm install @mccaskie-labs/workbench-strings @mccaskie-labs/workbench-config zod
+```
+
+## Files
+
+```
+strings/
+  strings.en-AU.json            the base: authored, complete, no glosses
+  strings.en-PH.json            a translation: words plus `_gloss.` back-translations
+  runtime/
+    strings.en-PH.json          GENERATED by `npx workbench-strings build --base en-AU`
+```
+
+Flat JSON, one entry per line. Keys start with a name group (§5.3): `ui.`, `enum.`, `question.`, `validation.`, `email.`, `notification.`, `page.`, `error.`, `meta.`. A new class of string adds a group to this package by PR. Keys starting `_` are metadata, never words:
+
+| Key | In | Meaning |
+|---|---|---|
+| `_gloss.<key>` | translations only | A literal back-translation of what the translation says, next to it so an edit to one shows beside the other. Stripped at build. Never counts as review |
+| `_review.status` | every translation | How it was made and reviewed, e.g. "AI-DRAFTED, NOT REVIEWED BY A NATIVE SPEAKER". Survives the strip |
+| `_review.reviewer` | every translation, before production | The named native-speaker reviewer and cadence: `"Maria Santos, monthly"` |
+| `_review.signed_off` | when reviewed | `"Maria Santos, 2026-11-11"`. Its presence is the only thing that lets the language be served to someone who did not choose it |
+
+Commit the generated files. `npx workbench-strings check --base en-AU` runs the file checks in CI and fails on a stale generated file.
+
+## Use
+
+```ts
+// SERVER ONLY: the catalogue holds every language. Pass finished words to the page.
+import { defineStrings } from '@mccaskie-labs/workbench-strings'
+import { workbenchEnv } from '@mccaskie-labs/workbench-config'
+import enAU from '../strings/strings.en-AU.json'
+import enPH from '../strings/runtime/strings.en-PH.json'
+
+export const strings = defineStrings({
+  env: workbenchEnv(env),
+  base: { locale: 'en-AU', strings: enAU },
+  translations: { 'en-PH': enPH },
+  locales: ['en-PH', 'en-AU'],      // switcher order; each must be a Workbench language
+  defaultLocale: 'en-PH',           // what an unknown visitor sees
+})
+
+const { locale } = strings.detect(request, { account: user?.locale })
+strings.t(locale, 'ui.cart.count', { count: 3 })        // "3 items in your cart"
+strings.email(strings.recipientLocale(user.locale), 'welcome', 'subject', { app: 'Sulok' })
+```
+
+`defineStrings` checks everything at start and throws `WorkbenchStringsError` (`invalid_options`, `invalid_catalogue`, `invalid_string`, `no_reviewer`). Keys are typed from the base file, so a key that does not exist is a type error.
+
+### Strings
+
+- `{name}` placeholders, named only, and one level of plural: `"{count, plural, =0 {Your cart is empty} one {# item} other {# items}}"`. The arm is chosen by `Intl.PluralRules` for the real locale; `=0` arms first; `other` is required; `#` goes through `Intl.NumberFormat`. No select, no nesting.
+- A `{name}` value is inserted as given, so a year or an order number is never grouped. Format money and dates first (`workbench-country`).
+- On a page a missing value stays visible as `{name}`; in an email it throws `missing_value`.
+- One key holds one complete sentence. Never branch on a count in code.
+
+### The fallback chain
+
+Each locale falls back to its parent (`parents`) and then to the base. A register (a dialect or formality tier with its own tag) needs its tag in the shared language list first, which today holds only `lang-REGION` tags. A word missing in a translation comes from the next locale on the chain and is logged as one JSON line (`strings.missing`, with `requested` and `resolved`); pass `onMissing` to send it elsewhere. `t()` and `email()` use the same chain.
+
+- A key missing even in the base is a bug the kit catches: `t()` shows the key and logs an error; `email()` throws `missing_string`, because an email has nobody watching it fail.
+
+### Detection
+
+`detect(request, { account })` checks, in order: the URL prefix (`/en-ph/...`), the `__Host-locale` cookie, the account's saved language, the country (`request.cf.country`), `Accept-Language`, then `defaultLocale`.
+
+- **Country before Accept-Language.** In the Philippines a phone reports English whatever its owner reads. The header stays below country for someone abroad who set their home language.
+- An unknown country (`XX`, Tor, none in local development) falls through to the header. A known country with no locale and no usable header gets the base.
+- Countries default to each locale's region when only one locale has it (en-PH serves PH); set `countries` to change that. `aliases` adds other header tags.
+- `localeFromPath`, `cookie(locale)` (Secure, Lax, a year, no Domain) and `prefixes` (lower-case tags by default; none owns the bare tree) help with routing.
+
+### The review gate
+
+A language nobody has signed off is served only to someone who chose it: the URL prefix, the cookie and the account are honoured; country, `Accept-Language` and the default resolve to the base instead (`gated: true`). The browser's language counts as inferred, not chosen; that is one line in `src/detect.ts`. Lifting the gate is a catalogue edit: name the reviewer, agree the cadence, they review, write `_review.signed_off`.
+
+In production a translated language with no `_review.reviewer` refuses to start (`no_reviewer`): a named native-speaker reviewer is needed before any translated word goes public. Staging sits behind Access, so it can carry unreviewed words for the review itself.
+
+### Emails
+
+This package owns the `email.<name>.<part>` keys. `email(locale, name, part, values)` looks up `email.welcome.subject` and so on in the recipient's saved language, at send time, one recipient at a time. The sign-in kit's email catalogue (`workbench-email`) names the emails and their parts.
+
+### Languages
+
+`WORKBENCH_LANGUAGES` is the one list, shared with the Gateway's spelling choices (`capabilities/ai.json`): en-AU, en-PH, en-GB, en-US today. A new language is added there first. Planned locales go in `planned`, not in `locales`, and have no file until they have words.
+
+## The test kit
+
+```ts
+import { checkStrings } from '@mccaskie-labs/workbench-strings/testing'
+import { strings } from '../src/strings'
+
+const authored = import.meta.glob('../strings/strings.*.json', { query: '?raw', import: 'default', eager: true })
+// ...map paths to locales, the same for runtime/ and for the app's sources
+
+for (const check of checkStrings({ strings, authored, runtime, sources, emails, composed: ['validation.'] }))
+  it(check.name, () => expect(check.problems).toEqual([]))
+```
+
+It runs the standard's tests (§11) on the app's own files, settings and code: key coverage, no empty base values, placeholder parity, review status declared, chain termination and shape, each step of the detection order, country before header, unknown country falls through, quality weights, aliases, prefix distinctness, a host-bound cookie, unknown locales survive, gloss presence and orphans (on the authored files), the runtime file is byte for byte the authored file minus glosses and keeps its marker, the dead-key sweep and unknown keys (exact matches, never substrings), forbidden voice words on word boundaries, every declared email part exists, plurals render in every locale, `defineStrings` was given these very files, and the gate is armed. Glosses are needed only for a language other than the base's (an en-AU reviewer reads en-PH). It needs no test framework and reads text, not paths, so it runs in the Workers test runtime.
+
+- `emails` (required, `[]` for none): the app's emails and their parts. The `email.` keys are checked against these, never swept as dead.
+- `chains`: each locale's expected fallback chain. Required when the app sets `parents`, so a register's route through its parent is pinned.
+- `sources`: the app's own code only. A catalogue file among them would vouch for its own keys, and the kit says so.
+- `composed`: other key prefixes built at run time, never swept as dead. Add `validation.` when the app uses `workbench-forms`, whose codes become `validation.<form>.<field>.<code>` and `validation.<code>`.
+- `forbidden`: words the brand voice forbids, per locale (the standard's question E6).
+
+What the kit cannot check: whether a page actually renders in each language. Fetch every page in every locale by hand before the first translated release (§14.1).

package/dist/browser.js

@@ -0,0 +1,6 @@
+"use strict";
+// What a browser bundle gets instead of the package (the "browser" export
+// condition). The catalogue holds every language, so it must never ship to a
+// phone: look words up on the server and pass the finished words to the page
+// (internationalization standard §7.5).
+throw new Error("@mccaskie-labs/workbench-strings is server only. Look the words up on the server and pass the finished words to the page.");

package/dist/catalogue.d.ts

@@ -0,0 +1,32 @@
+export type Catalogue = Readonly<Record<string, string>>;
+export declare const GLOSS = "_gloss.";
+export declare const REVIEW_STATUS = "_review.status";
+export declare const isMeta: (key: string) => boolean;
+/**
+ * Reads an authored or generated file. It must be a flat object of strings
+ * with one entry per line and no key twice (JSON.parse would keep the last
+ * duplicate without a word).
+ */
+export declare function readCatalogue(text: string, name?: string): Catalogue;
+/**
+ * The generated runtime file: the authored text minus its `_gloss.` lines,
+ * byte for byte otherwise. The `_review.` markers stay, because a marker that
+ * exists to stop a release must travel with the thing being released.
+ */
+export declare function stripGlosses(text: string, name?: string): string;
+export interface Review {
+    /** How the language was produced and reviewed, from `_review.status`. */
+    status: string | undefined;
+    /** The named native-speaker reviewer and their cadence. */
+    reviewer: {
+        name: string;
+        cadence: string;
+    } | undefined;
+    /** Who signed it off, and when. Undefined means not signed off. */
+    signedOff: {
+        name: string;
+        date: string;
+    } | undefined;
+}
+/** Reads a catalogue's review markers. A malformed marker throws: fix it, don't guess. */
+export declare function readReview(catalogue: Catalogue, name?: string): Review;

package/dist/catalogue.js

@@ -0,0 +1,115 @@
+// Catalogue files (internationalization standard §5.4, §10.3, §10.4).
+//
+//   strings/strings.<base>.json             authored, the source of truth, no glosses
+//   strings/strings.<locale>.json           authored: strings plus `_gloss.<key>` twins
+//   strings/runtime/strings.<locale>.json   GENERATED: the authored file minus glosses
+//
+// Flat JSON, one entry per line. Keys starting `_` are metadata, never words:
+// every lookup and check skips them.
+//
+// - `_gloss.<key>` is a literal back-translation of what the translation
+//   says, kept next to it in the authored file so an edit to one shows beside
+//   the other in the diff. It is stripped at build, line by line, so the
+//   generated file is byte for byte the authored file minus those lines.
+// - `_review.status` says how the language was produced and reviewed. Every
+//   translated catalogue carries it, and it survives the strip.
+// - `_review.reviewer` is "Name, cadence": the named native-speaker reviewer.
+//   A translated language can't reach production without one.
+// - `_review.signed_off` is "Name, YYYY-MM-DD". Its presence is the only
+//   thing that lets a language be served to someone who did not choose it.
+import { WorkbenchStringsError } from "./errors.js";
+export const GLOSS = "_gloss.";
+export const REVIEW_STATUS = "_review.status";
+const REVIEW_REVIEWER = "_review.reviewer";
+const REVIEW_SIGNED_OFF = "_review.signed_off";
+export const isMeta = (key) => key.startsWith("_");
+// One `"key": "value"` entry per line, with an optional trailing comma.
+const ENTRY = /^\s*"((?:[^"\\]|\\.)*)"\s*:\s*"(?:[^"\\]|\\.)*"\s*,?\s*$/;
+function bad(name, why) {
+    throw new WorkbenchStringsError("invalid_catalogue", `${name}: ${why}`);
+}
+/**
+ * Reads an authored or generated file. It must be a flat object of strings
+ * with one entry per line and no key twice (JSON.parse would keep the last
+ * duplicate without a word).
+ */
+export function readCatalogue(text, name = "catalogue") {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (e) {
+        bad(name, `not valid JSON (${e.message})`);
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+        bad(name, "not a JSON object");
+    const entries = Object.entries(parsed);
+    for (const [k, v] of entries)
+        if (typeof v !== "string")
+            bad(name, `"${k}" is not a string (the file must be flat)`);
+    const seen = new Set();
+    let lines = 0;
+    for (const line of text.split("\n")) {
+        const m = ENTRY.exec(line);
+        if (!m)
+            continue;
+        lines++;
+        const key = JSON.parse(`"${m[1]}"`);
+        if (seen.has(key))
+            bad(name, `"${key}" appears twice`);
+        seen.add(key);
+    }
+    if (lines !== entries.length)
+        bad(name, "write one entry per line");
+    return Object.freeze(Object.fromEntries(entries));
+}
+/**
+ * The generated runtime file: the authored text minus its `_gloss.` lines,
+ * byte for byte otherwise. The `_review.` markers stay, because a marker that
+ * exists to stop a release must travel with the thing being released.
+ */
+export function stripGlosses(text, name = "catalogue") {
+    readCatalogue(text, name);
+    const kept = [];
+    for (const line of text.split("\n")) {
+        const m = ENTRY.exec(line);
+        if (m && JSON.parse(`"${m[1]}"`).startsWith(GLOSS))
+            continue;
+        kept.push(line);
+    }
+    // Dropping the last entry leaves a trailing comma on the one before it.
+    for (let i = kept.length - 1; i >= 0; i--) {
+        if (!ENTRY.test(kept[i]))
+            continue;
+        kept[i] = kept[i].replace(/,(\s*)$/, "$1");
+        break;
+    }
+    const out = kept.join("\n");
+    readCatalogue(out, `${name} (generated)`);
+    return out;
+}
+/** Reads a catalogue's review markers. A malformed marker throws: fix it, don't guess. */
+export function readReview(catalogue, name = "catalogue") {
+    const status = catalogue[REVIEW_STATUS]?.trim() || undefined;
+    let reviewer;
+    const r = catalogue[REVIEW_REVIEWER];
+    if (r !== undefined) {
+        const m = /^\s*([^,]*\S)\s*,\s*(\S.*?)\s*$/.exec(r);
+        if (!m)
+            bad(name, `${REVIEW_REVIEWER} must be "Name, cadence", e.g. "Maria Santos, monthly"`);
+        reviewer = { name: m[1], cadence: m[2] };
+    }
+    let signedOff;
+    const s = catalogue[REVIEW_SIGNED_OFF];
+    if (s !== undefined) {
+        const m = /^\s*([^,]*\S)\s*,\s*(\d{4}-\d{2}-\d{2})\s*$/.exec(s);
+        const date = m ? new Date(`${m[2]}T00:00:00Z`) : undefined;
+        if (!m || !date || Number.isNaN(date.getTime()) || date.toISOString().slice(0, 10) !== m[2]) {
+            bad(name, `${REVIEW_SIGNED_OFF} must be "Name, YYYY-MM-DD", e.g. "Maria Santos, 2026-11-11"`);
+        }
+        if (date.getTime() > Date.now() + 86_400_000)
+            bad(name, `${REVIEW_SIGNED_OFF} is dated in the future (${m[2]})`);
+        signedOff = { name: m[1], date: m[2] };
+    }
+    return { status, reviewer, signedOff };
+}

package/dist/checks.d.ts

@@ -0,0 +1,15 @@
+export interface StringsCheck {
+    /** What the check asserts, from the standard's table. */
+    name: string;
+    /** Empty when it passes. */
+    problems: string[];
+}
+export interface FileInputs {
+    /** The base locale. */
+    base: string;
+    /** Raw text of every authored file, strings/strings.<locale>.json, by locale. */
+    authored: Readonly<Record<string, string>>;
+    /** Raw text of every generated file, strings/runtime/strings.<locale>.json, by locale (no base). */
+    runtime: Readonly<Record<string, string>>;
+}
+export declare function checkFiles(input: FileInputs): StringsCheck[];

package/dist/checks.js

@@ -0,0 +1,128 @@
+// The file checks (internationalization standard §11) that need only the
+// files. The test kit runs them with the rest, and `workbench-strings check`
+// runs them in CI without the app's code.
+//
+// The gloss checks read the AUTHORED files: against the generated ones every
+// assertion would pass with nothing to check.
+import { GLOSS, isMeta, readCatalogue, readReview, REVIEW_STATUS, stripGlosses } from "./catalogue.js";
+import { parseMessage, placeholdersOf } from "./format.js";
+const words = (c) => Object.keys(c).filter((k) => !isMeta(k));
+export function checkFiles(input) {
+    const read = { name: "Files are flat, one entry per line, no key twice", problems: [] };
+    const cats = new Map();
+    for (const [l, text] of Object.entries(input.authored)) {
+        try {
+            cats.set(l, readCatalogue(text, `strings.${l}.json`));
+        }
+        catch (e) {
+            read.problems.push(e.message);
+        }
+    }
+    const baseCat = cats.get(input.base);
+    if (!(input.base in input.authored))
+        read.problems.push(`no authored file for the base, ${input.base}`);
+    if (!baseCat)
+        return [read];
+    const others = [...cats].filter(([l]) => l !== input.base);
+    const baseKeys = new Set(words(baseCat));
+    const coverage = { name: "Key coverage: no locale has a key the base lacks", problems: [] };
+    const empty = { name: "No empty base values", problems: [] };
+    const parse = { name: "Every string's placeholders and plurals parse", problems: [] };
+    const parity = { name: "Placeholder parity with the base", problems: [] };
+    const status = { name: "Review status declared in every translated catalogue", problems: [] };
+    const markers = { name: "Review markers are well formed", problems: [] };
+    const baseGloss = { name: "The base carries no gloss", problems: [] };
+    const glossPresent = { name: "Gloss presence: every translated key has a gloss (not needed in the base's own language)", problems: [] };
+    const glossOrphans = { name: "Gloss orphans: no gloss without its key", problems: [] };
+    const equal = { name: "Runtime catalogue is byte for byte the authored file minus glosses", problems: [] };
+    const runtimeMarker = { name: "Runtime carries no gloss and keeps the review marker", problems: [] };
+    const basePlaceholders = new Map();
+    for (const [l, cat] of cats) {
+        for (const k of words(cat)) {
+            let ph;
+            try {
+                ph = placeholdersOf(parseMessage(cat[k])).join(",");
+            }
+            catch (e) {
+                parse.problems.push(`${l} ${k}: ${e.message}`);
+                continue;
+            }
+            if (l === input.base)
+                basePlaceholders.set(k, ph);
+        }
+        try {
+            readReview(cat, l);
+        }
+        catch (e) {
+            markers.problems.push(e.message);
+        }
+    }
+    for (const k of baseKeys)
+        if (baseCat[k].trim() === "")
+            empty.problems.push(`${input.base} ${k} is empty`);
+    for (const k of Object.keys(baseCat))
+        if (k.startsWith(GLOSS))
+            baseGloss.problems.push(`${input.base} has ${k}`);
+    const language = (l) => l.toLowerCase().split("-")[0];
+    for (const [l, cat] of others) {
+        // A reviewer who reads en-AU reads en-PH: a gloss would only repeat the string.
+        const needsGloss = language(l) !== language(input.base);
+        for (const k of words(cat)) {
+            if (!baseKeys.has(k)) {
+                coverage.problems.push(`${l} has ${k}, which the base does not`);
+                continue;
+            }
+            try {
+                const ph = placeholdersOf(parseMessage(cat[k])).join(",");
+                const want = basePlaceholders.get(k);
+                if (want !== undefined && ph !== want)
+                    parity.problems.push(`${l} ${k} uses {${ph}}, the base uses {${want}}`);
+            }
+            catch {
+                // Reported by the parse check.
+            }
+            const gloss = cat[`${GLOSS}${k}`];
+            if (needsGloss && gloss === undefined)
+                glossPresent.problems.push(`${l} ${k} has no ${GLOSS}${k}`);
+            if (gloss !== undefined && gloss.trim() === "")
+                glossPresent.problems.push(`${l} ${GLOSS}${k} is empty`);
+        }
+        for (const g of Object.keys(cat).filter((k) => k.startsWith(GLOSS))) {
+            if (cat[g.slice(GLOSS.length)] === undefined)
+                glossOrphans.problems.push(`${l} ${g} has no ${g.slice(GLOSS.length)}`);
+        }
+        if (!cat[REVIEW_STATUS]?.trim())
+            status.problems.push(`${l} has no ${REVIEW_STATUS}`);
+        const runtime = input.runtime[l];
+        if (runtime === undefined) {
+            equal.problems.push(`${l} has no generated file. Run: npx workbench-strings build`);
+            continue;
+        }
+        try {
+            if (runtime !== stripGlosses(input.authored[l], `strings.${l}.json`)) {
+                equal.problems.push(`runtime/strings.${l}.json is stale. Run: npx workbench-strings build`);
+            }
+            const rc = readCatalogue(runtime, `runtime/strings.${l}.json`);
+            // Checked again without stripGlosses, so a strip bug can't vouch for itself.
+            const want = Object.entries(cat).filter(([k]) => !k.startsWith(GLOSS));
+            if (JSON.stringify(Object.entries(rc)) !== JSON.stringify(want)) {
+                equal.problems.push(`runtime/strings.${l}.json does not hold exactly the authored entries minus glosses`);
+            }
+            if (Object.keys(rc).some((k) => k.startsWith(GLOSS)))
+                runtimeMarker.problems.push(`runtime/strings.${l}.json has glosses`);
+            if (cat[REVIEW_STATUS] !== undefined && rc[REVIEW_STATUS] !== cat[REVIEW_STATUS]) {
+                runtimeMarker.problems.push(`runtime/strings.${l}.json lost ${REVIEW_STATUS}`);
+            }
+        }
+        catch (e) {
+            equal.problems.push(e.message);
+        }
+    }
+    for (const l of Object.keys(input.runtime)) {
+        if (l === input.base)
+            equal.problems.push(`the base, ${l}, gets no generated file: delete runtime/strings.${l}.json`);
+        else if (!(l in input.authored))
+            equal.problems.push(`runtime/strings.${l}.json has no authored file`);
+    }
+    return [read, coverage, empty, parse, parity, status, markers, baseGloss, glossPresent, glossOrphans, equal, runtimeMarker];
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function main(argv: string[]): number;

package/dist/cli.js

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+// `npx workbench-strings build [dir] --base <locale>`
+//   Writes strings/runtime/strings.<locale>.json for every translated
+//   language: the authored file minus its back-translation glosses. The base
+//   gets no generated file.
+// `npx workbench-strings check [dir] --base <locale>`
+//   The file checks (internationalization standard §11) and a stale-runtime
+//   check, for CI. Exit 1 on any problem.
+import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { stripGlosses } from "./catalogue.js";
+import { checkFiles } from "./checks.js";
+const FILE = /^strings\.([A-Za-z0-9-]+)\.json$/;
+function readDir(dir) {
+    if (!existsSync(dir))
+        return {};
+    const out = {};
+    for (const f of readdirSync(dir)) {
+        const m = FILE.exec(f);
+        if (m)
+            out[m[1]] = readFileSync(join(dir, f), "utf8");
+    }
+    return out;
+}
+export function main(argv) {
+    const args = [...argv];
+    const baseAt = args.indexOf("--base");
+    const base = baseAt === -1 ? undefined : args.splice(baseAt, 2)[1];
+    const [command, dir = "strings"] = args;
+    if ((command !== "build" && command !== "check") || !base) {
+        console.error("Usage: workbench-strings build|check [dir] --base <locale>   (dir defaults to strings)");
+        return 2;
+    }
+    const authored = readDir(dir);
+    if (!(base in authored)) {
+        console.error(`No ${join(dir, `strings.${base}.json`)}`);
+        return 1;
+    }
+    const runtimeDir = join(dir, "runtime");
+    if (command === "build") {
+        if (/"_gloss\./.test(authored[base])) {
+            console.error(`strings.${base}.json is the base and must have no glosses`);
+            return 1;
+        }
+        mkdirSync(runtimeDir, { recursive: true });
+        for (const locale of Object.keys(readDir(runtimeDir))) {
+            if (locale === base || !(locale in authored)) {
+                rmSync(join(runtimeDir, `strings.${locale}.json`));
+                console.log(`removed ${join(runtimeDir, `strings.${locale}.json`)}`);
+            }
+        }
+        for (const [locale, text] of Object.entries(authored)) {
+            if (locale === base)
+                continue;
+            try {
+                writeFileSync(join(runtimeDir, `strings.${locale}.json`), stripGlosses(text, `strings.${locale}.json`));
+            }
+            catch (e) {
+                console.error(e.message);
+                return 1;
+            }
+            console.log(`wrote ${join(runtimeDir, `strings.${locale}.json`)}`);
+        }
+        return 0;
+    }
+    let failed = 0;
+    for (const c of checkFiles({ base, authored, runtime: readDir(runtimeDir) })) {
+        if (c.problems.length === 0)
+            continue;
+        failed++;
+        console.error(`✗ ${c.name}`);
+        for (const p of c.problems)
+            console.error(`  ${p}`);
+    }
+    if (failed === 0)
+        console.log("Strings files pass every file check.");
+    return failed === 0 ? 0 : 1;
+}
+// Run only when this file is the program, compared by resolved path: a test
+// that imports main() must never rewrite the files it is checking.
+const self = realpathSync(fileURLToPath(import.meta.url));
+const program = process.argv[1] ? realpathSync(resolve(process.argv[1])) : "";
+if (self === program)
+    process.exitCode = main(process.argv.slice(2));

package/dist/detect.d.ts

@@ -0,0 +1,49 @@
+export type DetectionSource = "prefix" | "cookie" | "account" | "country" | "header" | "default";
+export interface LocaleSignals {
+    /** The locale named by the URL's prefix, from localeFromPath. */
+    prefix?: string | null | undefined;
+    /** The remembered choice, from the `__Host-locale` cookie. */
+    cookie?: string | null | undefined;
+    /** The signed-in person's saved language. */
+    account?: string | null | undefined;
+    /** The two-letter country the edge reports (`request.cf.country` on Cloudflare). */
+    country?: string | null | undefined;
+    /** The raw Accept-Language header. */
+    acceptLanguage?: string | null | undefined;
+}
+export interface LocaleRules {
+    /** The live locales, in switcher order. */
+    locales: readonly string[];
+    /** Where every fallback chain ends. */
+    base: string;
+    /** What an unknown visitor sees. */
+    defaultLocale: string;
+    /** Country code to locale. */
+    countries: Readonly<Record<string, string>>;
+    /** Other Accept-Language tags (old or bare ones) to locale, matched without case. */
+    aliases: Readonly<Record<string, string>>;
+    /**
+     * Whether a locale has been signed off by a named reviewer. Required, so a
+     * caller that forgets the gate gets a type error, not unreviewed words.
+     */
+    reviewed: (locale: string) => boolean;
+}
+export interface Detection {
+    locale: string;
+    /** Which signal decided it. */
+    source: DetectionSource;
+    /** True when the review gate replaced an unreviewed inferred locale with the base. */
+    gated: boolean;
+}
+/** Accept-Language tags, best first by q; q=0 and `*` dropped, ties keep their order. */
+export declare function parseAcceptLanguage(header: string | null | undefined): string[];
+/** The best live locale for an Accept-Language header: exact tag, then alias, then a language only one locale has. */
+export declare function matchAcceptLanguage(rules: Pick<LocaleRules, "locales" | "aliases">, header: string | null | undefined): string | undefined;
+/** Resolves the locale for one request. */
+export declare function resolveLocale(signals: LocaleSignals, rules: LocaleRules): Detection;
+/** The cookie that remembers a choice. `__Host-` makes the browser refuse it with a Domain or without Secure. */
+export declare const LOCALE_COOKIE = "__Host-locale";
+/** A Set-Cookie value remembering `locale` for a year. Lax, so a visitor arriving from a link keeps their language. */
+export declare function localeCookie(locale: string): string;
+/** The locale cookie's value from a Cookie header, if any. */
+export declare function readLocaleCookie(header: string | null | undefined): string | undefined;