@vestra-player/sdk 1.5.8 → 1.5.11

package/dist/i18n.js

@@ -0,0 +1,972 @@
+/*
+ * Translation catalogs, the same way the player reads them (the player's
+ * `src/host/src/i18n/`): gettext `.po` files, the compiled
+ * `locales/<lang>.json` a package carries, template formatting and the
+ * Slint `@tr` scanner. Used by `vestra-plugin i18n`, `vestra-plugin build`
+ * and {@link TestHost}; not part of the plugin API (plugins write no
+ * translation code: see docs/how-to/i18n.md).
+ * Internal: the player's runner and tests reach it through
+ * `@vestra-player/sdk/runtime`, `LOCALES` through `./testing`.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+/**
+ * The player's interface languages: English (the source language) first,
+ * then the translations, as the player's own table (its tests check that
+ * they agree).
+ */
+export const LOCALES = ["en", "zh-Hans", "ja", "ko", "de", "fr", "es"];
+/** The catalog key: `msgid`, or `msgctxt` U+0004 `msgid`. */
+export const keyOf = (context, id) => context === undefined ? id : `${context}\u0004${id}`;
+const translated = (entry) => !entry.fuzzy && !entry.obsolete && (entry.strings[0] ?? "") !== "";
+/** Parse a `.po` (or `.pot`) file. Throws with the line number on errors. */
+export function parsePo(text) {
+    const entries = [];
+    let header = "";
+    const blank = () => ({
+        id: "",
+        strings: [],
+        fuzzy: false,
+        notes: [],
+        references: [],
+        flags: [],
+        obsolete: false,
+    });
+    let entry = blank();
+    let started = false;
+    let field = "none";
+    // Comments seen before the entry's first keyword.
+    let pending = blank();
+    const finish = () => {
+        if (started) {
+            if (entry.id === "" && entry.context === undefined)
+                header = entry.strings[0] ?? "";
+            else
+                entries.push(entry);
+        }
+        entry = blank();
+        started = false;
+        field = "none";
+    };
+    const lines = text.split(/\r?\n/);
+    for (let index = 0; index < lines.length; index++) {
+        let line = lines[index].trim();
+        const at = (message) => new Error(`line ${index + 1}: ${message}`);
+        if (line === "") {
+            finish();
+            continue;
+        }
+        let obsolete = false;
+        if (line.startsWith("#~")) {
+            obsolete = true;
+            line = line.slice(2).trim();
+            if (line === "")
+                continue;
+        }
+        else if (line.startsWith("#")) {
+            if (started)
+                finish();
+            const body = line.slice(2).trim();
+            if (line.startsWith("#."))
+                pending.notes.push(body);
+            else if (line.startsWith("#:"))
+                pending.references.push(...body.split(/\s+/).filter(Boolean));
+            else if (line.startsWith("#,"))
+                for (const flag of body.split(",").map((f) => f.trim()))
+                    if (flag === "fuzzy")
+                        pending.fuzzy = true;
+                    else if (flag)
+                        pending.flags.push(flag);
+            continue;
+        }
+        let keyword = "";
+        let rest = line;
+        if (!line.startsWith('"')) {
+            const split = line.search(/\s/);
+            if (split < 0)
+                throw at("a keyword without a string");
+            keyword = line.slice(0, split);
+            rest = line.slice(split).trim();
+        }
+        let next;
+        if (keyword === "") {
+            if (field === "none")
+                throw at("a string without a keyword");
+            next = field;
+        }
+        else if (keyword === "msgctxt")
+            next = "context";
+        else if (keyword === "msgid")
+            next = "id";
+        else if (keyword === "msgid_plural")
+            next = "plural";
+        else if (keyword === "msgstr")
+            next = 0;
+        else {
+            const match = /^msgstr\[(\d+)\]$/.exec(keyword);
+            if (!match || Number(match[1]) > 16)
+                throw at(`unknown keyword ${keyword}`);
+            next = Number(match[1]);
+        }
+        if (keyword !== "") {
+            const opens = next === "context" || (next === "id" && field !== "context");
+            if (opens && started)
+                finish();
+            if (!started) {
+                if (!opens)
+                    throw at("an entry starts with msgctxt or msgid");
+                started = true;
+                entry = { ...pending, obsolete };
+                pending = blank();
+            }
+        }
+        const value = unquote(rest, at);
+        if (next === "context")
+            entry.context = (entry.context ?? "") + value;
+        else if (next === "id")
+            entry.id += value;
+        else if (next === "plural")
+            entry.plural = (entry.plural ?? "") + value;
+        else if (typeof next === "number") {
+            while (entry.strings.length <= next)
+                entry.strings.push("");
+            entry.strings[next] += value;
+        }
+        field = next;
+    }
+    finish();
+    return { header, entries };
+}
+function unquote(text, at) {
+    if (text.length < 2 || !text.startsWith('"') || !text.endsWith('"'))
+        throw at("expected a quoted string");
+    let out = "";
+    const inner = text.slice(1, -1);
+    for (let i = 0; i < inner.length; i++) {
+        const c = inner[i];
+        if (c !== "\\") {
+            out += c;
+            continue;
+        }
+        const n = inner[++i];
+        if (n === "n")
+            out += "\n";
+        else if (n === "t")
+            out += "\t";
+        else if (n === "r")
+            out += "\r";
+        else if (n === '"')
+            out += '"';
+        else if (n === "\\")
+            out += "\\";
+        else
+            throw at(`unknown escape \\${n ?? ""}`);
+    }
+    return out;
+}
+const poString = (text) => `"${text.replaceAll("\\", "\\\\").replaceAll('"', '\\"').replaceAll("\t", "\\t").replaceAll("\r", "\\r").replaceAll("\n", "\\n")}"`;
+/** A `.po` string field: one line, or `""` then one line per `\n`. */
+function field(keyword, text) {
+    const parts = text.split(/(?<=\n)/);
+    if (parts.length <= 1)
+        return `${keyword} ${poString(text)}`;
+    return [`${keyword} ""`, ...parts.map(poString)].join("\n");
+}
+/** Write a `.po` file: the header, then the entries in the given order. */
+export function writePo(header, entries) {
+    const blocks = [`msgid ""\n${field("msgstr", header)}`];
+    for (const entry of entries) {
+        const prefix = entry.obsolete ? "#~ " : "";
+        const lines = [];
+        for (const note of entry.notes)
+            lines.push(`#. ${note}`);
+        if (entry.references.length && !entry.obsolete)
+            lines.push(`#: ${entry.references.join(" ")}`);
+        const flags = [...(entry.fuzzy ? ["fuzzy"] : []), ...entry.flags];
+        if (flags.length)
+            lines.push(`#, ${flags.join(", ")}`);
+        const body = [];
+        if (entry.context !== undefined)
+            body.push(field("msgctxt", entry.context));
+        body.push(field("msgid", entry.id));
+        if (entry.plural !== undefined) {
+            body.push(field("msgid_plural", entry.plural));
+            const strings = entry.strings.length ? entry.strings : ["", ""];
+            strings.forEach((text, n) => body.push(field(`msgstr[${n}]`, text)));
+        }
+        else
+            body.push(field("msgstr", entry.strings[0] ?? ""));
+        for (const text of body)
+            for (const line of text.split("\n"))
+                lines.push(prefix + line);
+        blocks.push(lines.join("\n"));
+    }
+    return `${blocks.join("\n\n")}\n`;
+}
+/**
+ * The compiled catalog of one language (`locales/<lang>.json`): translated
+ * entries only (not fuzzy, not obsolete, not empty), keys sorted. Plurals
+ * have two forms, as the player shows them: `msgstr[0]` for `n == 1` and
+ * `msgstr[1]` (else `msgstr[0]`) for every other `n`.
+ */
+export function compileCatalog(language, entries) {
+    const messages = {};
+    for (const entry of [...entries].sort((a, b) => keyOf(a.context, a.id) < keyOf(b.context, b.id) ? -1 : 1)) {
+        if (!translated(entry))
+            continue;
+        const key = keyOf(entry.context, entry.id);
+        if (key in messages)
+            continue;
+        const one = entry.strings[0];
+        messages[key] =
+            entry.plural === undefined ? one : [one, entry.strings[1] || one];
+    }
+    return { language, messages };
+}
+/** Lookups in one language's messages, as the player does them. */
+export class Catalog {
+    messages;
+    constructor(messages = {}) {
+        this.messages = new Map(Object.entries(messages));
+    }
+    /** From parsed `.po` entries. */
+    static fromEntries(entries) {
+        return new Catalog(compileCatalog("", entries).messages);
+    }
+    /** The translation of `id` (the one form of a plural), or `undefined`. */
+    lookup(id, context) {
+        const message = this.messages.get(keyOf(context, id));
+        return Array.isArray(message) ? message[0] : message;
+    }
+    /** The translation of `id`, or `id` itself. */
+    text(id) {
+        return this.lookup(id) ?? id;
+    }
+    /**
+     * A plugin sentence (`osd.show(template, args)`, dialogs): translated,
+     * then formatted with `args` when given; without `args` the text shows
+     * as it is, braces included.
+     */
+    template(text, args) {
+        const template = this.text(text);
+        return args === undefined || args === null
+            ? template
+            : format(template, args);
+    }
+    /** What an `@tr` call becomes, `undefined` when untranslated. */
+    slint(call) {
+        const message = this.messages.get(keyOf(call.context, call.id));
+        if (message === undefined)
+            return undefined;
+        if (Array.isArray(message) !== (call.plural !== undefined))
+            return undefined;
+        return Array.isArray(message)
+            ? [message[0], message[1]]
+            : [message, undefined];
+    }
+}
+const argument = (value) => typeof value === "number"
+    ? Number.isInteger(value)
+        ? value.toFixed(0)
+        : String(value)
+    : (value ?? "");
+/**
+ * Format a template the way Slint's `@tr` and the player do: `{}` takes
+ * the next argument, `{0}` the first, `{name}` a field of an object; `{{`
+ * and `}}` are braces. A placeholder without an argument stays as written.
+ */
+export function format(template, args) {
+    let out = "";
+    let next = 0;
+    let rest = template;
+    for (;;) {
+        const at = rest.search(/[{}]/);
+        if (at < 0)
+            break;
+        out += rest.slice(0, at);
+        const tail = rest.slice(at);
+        if (tail.startsWith("{{") || tail.startsWith("}}")) {
+            out += tail[0];
+            rest = tail.slice(2);
+            continue;
+        }
+        if (tail.startsWith("}")) {
+            out += "}";
+            rest = tail.slice(1);
+            continue;
+        }
+        const close = tail.indexOf("}");
+        if (close < 0) {
+            out += tail;
+            rest = "";
+            break;
+        }
+        const name = tail.slice(1, close);
+        let value;
+        const list = Array.isArray(args)
+            ? args
+            : null;
+        if (name === "")
+            value = list?.[next++];
+        else if (/^\d+$/.test(name))
+            value = list?.[Number(name)];
+        else if (args && !list)
+            value = args[name];
+        out += value === undefined ? tail.slice(0, close + 1) : argument(value);
+        rest = tail.slice(close + 1);
+    }
+    return out + rest;
+}
+/**
+ * The placeholders of a template, sorted: `""` per `{}`, else the name or
+ * number (`{n}` of a Slint plural is `"n"`). Translations must keep them.
+ */
+export function placeholders(text) {
+    const found = [];
+    const plain = text.replaceAll("{{", "").replaceAll("}}", "");
+    for (const match of plain.matchAll(/\{([^{}]*)\}/g))
+        found.push(match[1]);
+    return found.sort();
+}
+// ---------------------------------------------------------------- texts
+/**
+ * The ways a `TextList` is joined (`ListStyle`), as the player
+ * joins them in each interface language (`LIST_SEPARATORS`).
+ */
+export const LIST_STYLES = [
+    "list",
+    "clauses",
+    "semicolons",
+    "sentences",
+    "lines",
+];
+/**
+ * The separator of each list style per interface language, as the player's
+ * table (`i18n::text::SEPARATORS`; its tests check that they agree).
+ */
+export const LIST_SEPARATORS = {
+    en: {
+        list: ", ",
+        clauses: ", ",
+        semicolons: "; ",
+        sentences: ". ",
+        lines: "\n",
+    },
+    "zh-Hans": {
+        list: "、",
+        clauses: "，",
+        semicolons: "；",
+        sentences: "。",
+        lines: "\n",
+    },
+    ja: {
+        list: "、",
+        clauses: "、",
+        semicolons: "；",
+        sentences: "。",
+        lines: "\n",
+    },
+    ko: {
+        list: ", ",
+        clauses: ", ",
+        semicolons: "; ",
+        sentences: ". ",
+        lines: "\n",
+    },
+    de: {
+        list: ", ",
+        clauses: ", ",
+        semicolons: "; ",
+        sentences: ". ",
+        lines: "\n",
+    },
+    fr: {
+        list: ", ",
+        clauses: ", ",
+        semicolons: " ; ",
+        sentences: ". ",
+        lines: "\n",
+    },
+    es: {
+        list: ", ",
+        clauses: ", ",
+        semicolons: "; ",
+        sentences: ". ",
+        lines: "\n",
+    },
+};
+/**
+ * The player's limits on one text value (a
+ * {@link @vestra-player/sdk!Text | Text} or
+ * {@link @vestra-player/sdk!TextList | TextList} with everything nested in it), as the player's
+ * `i18n::text` (its tests check that they agree).
+ */
+export const TEXT_LIMITS = {
+    /** Nesting depth of texts and lists; the value itself is depth 0 (8). */
+    depth: 8,
+    /** Texts, lists and arguments in all, the value itself included (1024). */
+    nodes: 1024,
+    /** Arguments of one text (16). */
+    args: 16,
+    /** Items of one list (256). */
+    items: 256,
+    /** UTF-8 bytes of a source text or a string argument (4096). */
+    stringBytes: 4096,
+};
+const plainObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+/** A text or list value (by its marker key). */
+export function isTextValue(value) {
+    return (plainObject(value) && ("$vestraText" in value || "$vestraList" in value));
+}
+const utf8 = (text) => new TextEncoder().encode(text).length;
+/**
+ * Why the player would refuse a text value or template arguments, or
+ * `null`. `args` mode checks template arguments (an array or object of
+ * arguments) instead of one value. The same rules and messages as the
+ * player's `i18n::text::check`.
+ */
+export function textProblem(value, mode = "value") {
+    let nodes = 0;
+    const L = TEXT_LIMITS;
+    const args = (list, depth) => {
+        const values = Array.isArray(list)
+            ? list
+            : plainObject(list)
+                ? Object.values(list)
+                : null;
+        if (!values)
+            return "args is an array or an object";
+        if (values.length > L.args)
+            return `args holds at most ${L.args} values`;
+        for (const item of values) {
+            const problem = arg(item, depth);
+            if (problem)
+                return problem;
+        }
+        return null;
+    };
+    const arg = (item, depth) => {
+        if (typeof item === "number")
+            return Number.isFinite(item) ? count() : "a number argument is finite";
+        if (typeof item === "string")
+            return utf8(item) > L.stringBytes
+                ? `a string argument is at most ${L.stringBytes} bytes`
+                : count();
+        if (isTextValue(item))
+            return text(item, depth + 1);
+        return "args are strings, numbers, texts and lists";
+    };
+    const count = () => ++nodes > L.nodes ? `a text holds at most ${L.nodes} values` : null;
+    const text = (item, depth) => {
+        if (depth > L.depth)
+            return `texts nest at most ${L.depth} deep`;
+        if (!plainObject(item))
+            return "a text is a $vestraText or $vestraList object";
+        const over = count();
+        if (over)
+            return over;
+        if ("$vestraText" in item) {
+            const keys = Object.keys(item);
+            if (keys.some((key) => key !== "$vestraText" && key !== "args"))
+                return "a text has only $vestraText and args";
+            const source = item.$vestraText;
+            if (typeof source !== "string" || source === "")
+                return "a text's source is a non-empty string";
+            if (utf8(source) > L.stringBytes)
+                return `a text's source is at most ${L.stringBytes} bytes`;
+            return item.args === undefined ? null : args(item.args, depth);
+        }
+        const keys = Object.keys(item);
+        if (keys.some((key) => key !== "$vestraList" && key !== "style"))
+            return "a list has only $vestraList and style";
+        const items = item.$vestraList;
+        if (!Array.isArray(items))
+            return "a list's items are an array";
+        if (items.length > L.items)
+            return `a list holds at most ${L.items} items`;
+        if (item.style !== undefined &&
+            !LIST_STYLES.includes(item.style))
+            return `a list's style is one of ${LIST_STYLES.join(", ")}`;
+        for (const entry of items) {
+            const problem = arg(entry, depth);
+            if (problem)
+                return problem;
+        }
+        return null;
+    };
+    return mode === "args" ? args(value, 0) : text(value, 0);
+}
+function renderArg(arg, r) {
+    return isTextValue(arg) ? renderValue(arg, r) : arg;
+}
+function renderValue(value, r) {
+    if ("$vestraText" in value) {
+        const template = r.catalog.text(value.$vestraText);
+        return format(template, renderArgs(value.args, r) ?? []);
+    }
+    const locale = LOCALES.includes(r.locale)
+        ? r.locale
+        : "en";
+    const separator = LIST_SEPARATORS[locale][value.style ?? "list"];
+    return value.$vestraList
+        .map((item) => String(argumentText(renderArg(item, r))))
+        .join(separator);
+}
+const argumentText = (value) => typeof value === "number" ? format("{}", [value]) : value;
+function renderArgs(args, r) {
+    if (args === undefined || args === null)
+        return undefined;
+    if (Array.isArray(args))
+        return args.map((arg) => renderArg(arg, r));
+    return Object.fromEntries(Object.entries(args).map(([name, arg]) => [name, renderArg(arg, r)]));
+}
+/**
+ * A text value as the player shows it: the source translated with the
+ * plugin's catalog and formatted with its (rendered) arguments; a list's
+ * items joined with the locale's separator.
+ */
+export function renderText(value, catalog, locale) {
+    return renderValue(value, { catalog, locale });
+}
+/**
+ * Template arguments with their texts rendered (for `format`): what the
+ * player fills a template with.
+ */
+export function renderTemplateArgs(args, catalog, locale) {
+    return renderArgs(args ?? undefined, { catalog, locale });
+}
+/** The English rendering of a text value: the key a menu merges by. */
+export function textKey(value) {
+    return renderValue(value, { catalog: new Catalog(), locale: "en" });
+}
+/**
+ * A property value with every text value in it replaced by its shown
+ * string, as the player does before it hands the value to Slint. Returns
+ * a problem (`textProblem`) instead when a text value is malformed.
+ */
+export function resolveTexts(value, catalog, locale) {
+    let problem = null;
+    const walk = (item) => {
+        if (problem)
+            return item;
+        if (isTextValue(item)) {
+            problem = textProblem(item);
+            return problem ? item : renderText(item, catalog, locale);
+        }
+        if (Array.isArray(item))
+            return item.map(walk);
+        if (plainObject(item)) {
+            // A runtime image or Markdown document stays as it is.
+            if ("$vestraImage" in item || "$vestraMarkdown" in item)
+                return item;
+            return Object.fromEntries(Object.entries(item).map(([key, entry]) => [key, walk(entry)]));
+        }
+        return item;
+    };
+    const out = walk(value);
+    return problem ? { problem } : { value: out };
+}
+/** Whether a value holds a text value anywhere (a cheap pre-check). */
+export function hasTexts(value) {
+    if (isTextValue(value))
+        return true;
+    if (Array.isArray(value))
+        return value.some(hasTexts);
+    if (plainObject(value))
+        return Object.values(value).some(hasTexts);
+    return false;
+}
+const lineEnd = (s, i) => {
+    const found = s.slice(i).search(/[\n\r]/);
+    return found < 0 ? s.length : i + found;
+};
+function commentEnd(s, from) {
+    let depth = 0;
+    let i = from + 2;
+    while (i + 1 < s.length) {
+        if (s[i] === "/" && s[i + 1] === "*") {
+            depth++;
+            i += 2;
+        }
+        else if (s[i] === "*" && s[i + 1] === "/") {
+            if (depth === 0)
+                return i + 2;
+            depth--;
+            i += 2;
+        }
+        else
+            i++;
+    }
+    return s.length;
+}
+function stringEnd(s, from, templates) {
+    let i = from;
+    while (i < s.length) {
+        if (s[i] === '"')
+            return i + 1;
+        if (s[i] === "\\" && s[i + 1] === "{") {
+            templates.push(0);
+            return i + 2;
+        }
+        i += s[i] === "\\" ? 2 : 1;
+    }
+    return s.length;
+}
+function skip(s, i) {
+    for (;;) {
+        if (/\s/.test(s[i] ?? ""))
+            i++;
+        else if (s[i] === "/" && s[i + 1] === "/")
+            i = lineEnd(s, i);
+        else if (s[i] === "/" && s[i + 1] === "*")
+            i = commentEnd(s, i);
+        else
+            return i;
+    }
+}
+/** A plain string literal at `i`: its span and value (no interpolation). */
+function literal(s, i) {
+    if (s[i] !== '"')
+        return null;
+    let j = i + 1;
+    let value = "";
+    for (;;) {
+        const c = s[j];
+        if (c === undefined)
+            return null;
+        if (c === '"')
+            return [[i, j + 1], value];
+        if (c !== "\\") {
+            value += c;
+            j++;
+            continue;
+        }
+        const n = s[j + 1];
+        if (n === '"' || n === "\\")
+            value += n;
+        else if (n === "n")
+            value += "\n";
+        else if (n === "u") {
+            if (s[j + 2] !== "{")
+                return null;
+            const close = s.indexOf("}", j + 3);
+            if (close < 0)
+                return null;
+            const code = Number.parseInt(s.slice(j + 3, close), 16);
+            if (!/^[0-9a-fA-F]+$/.test(s.slice(j + 3, close)) || code > 0x10ffff)
+                return null;
+            value += String.fromCodePoint(code);
+            j = close + 1;
+            continue;
+        }
+        else
+            return null;
+        j += 2;
+    }
+}
+function callAt(s, at) {
+    let i = skip(s, at + 1);
+    if (!s.startsWith("tr", i))
+        return null;
+    i += 2;
+    if (/[A-Za-z0-9_-]/.test(s[i] ?? ""))
+        return null;
+    i = skip(s, i);
+    if (s[i] !== "(")
+        return null;
+    let found = literal(s, skip(s, i + 1));
+    if (!found)
+        return null;
+    let [span, text] = found;
+    let context;
+    let end = skip(s, span[1]);
+    if (s.startsWith("=>", end)) {
+        context = text;
+        found = literal(s, skip(s, end + 2));
+        if (!found)
+            return null;
+        [span, text] = found;
+        end = skip(s, span[1]);
+    }
+    let resume = span[1];
+    const call = {
+        id: text,
+        line: s.slice(0, at).split("\n").length,
+        idSpan: span,
+    };
+    if (context !== undefined)
+        call.context = context;
+    if (s[end] === "|") {
+        const other = literal(s, skip(s, end + 1));
+        if (!other)
+            return null;
+        call.plural = other[1];
+        call.pluralSpan = other[0];
+        resume = other[0][1];
+    }
+    return [call, resume];
+}
+/**
+ * Every `@tr` call of a Slint source, in order; the same scanner as the
+ * player's (both run the shared cases of the player's
+ * `src/host/tests/fixtures/slint-tr.json`). Comments, strings and string
+ * interpolation are skipped; a malformed call is left out.
+ */
+export function scanSlint(source) {
+    const calls = [];
+    const templates = [];
+    let i = 0;
+    while (i < source.length) {
+        const c = source[i];
+        if (c === "/" && source[i + 1] === "/")
+            i = lineEnd(source, i);
+        else if (c === "/" && source[i + 1] === "*")
+            i = commentEnd(source, i);
+        else if (c === '"')
+            i = stringEnd(source, i + 1, templates);
+        else if (c === "{" && templates.length) {
+            templates[templates.length - 1]++;
+            i++;
+        }
+        else if (c === "}" && templates.length) {
+            if (templates[templates.length - 1] === 0) {
+                templates.pop();
+                i = stringEnd(source, i + 1, templates);
+            }
+            else {
+                templates[templates.length - 1]--;
+                i++;
+            }
+        }
+        else if (c === "@") {
+            const found = callAt(source, i);
+            if (found) {
+                calls.push(found[0]);
+                i = found[1];
+            }
+            else
+                i++;
+        }
+        else
+            i++;
+    }
+    return calls;
+}
+/** A Slint string literal for `text`. */
+export function slintQuote(text) {
+    let out = '"';
+    for (const c of text) {
+        if (c === '"')
+            out += '\\"';
+        else if (c === "\\")
+            out += "\\\\";
+        else if (c === "\n")
+            out += "\\n";
+        else if (/\p{Cc}/u.test(c))
+            out += `\\u{${c.codePointAt(0).toString(16)}}`;
+        else
+            out += c;
+    }
+    return `${out}"`;
+}
+/** `source` with its `@tr` literals translated (what the player compiles). */
+export function rewriteSlint(source, catalog) {
+    let out = "";
+    let copied = 0;
+    for (const call of scanSlint(source)) {
+        const translation = catalog.slint(call);
+        if (!translation)
+            continue;
+        out += source.slice(copied, call.idSpan[0]) + slintQuote(translation[0]);
+        copied = call.idSpan[1];
+        if (call.pluralSpan && translation[1] !== undefined) {
+            out +=
+                source.slice(copied, call.pluralSpan[0]) + slintQuote(translation[1]);
+            copied = call.pluralSpan[1];
+        }
+    }
+    return out + source.slice(copied);
+}
+/**
+ * The supported locale for a BCP 47 tag, as the player maps the system's
+ * languages: Simplified Chinese is `zh-Hans`; Traditional Chinese (`zh-Hant`,
+ * or Taiwan, Hong Kong, Macao) is English; other languages by their primary
+ * subtag; `undefined` for a language the player does not have.
+ */
+export function matchLocale(tag) {
+    const parts = tag
+        .replaceAll("_", "-")
+        .toLowerCase()
+        .split(/[.@]/)[0]
+        .split("-");
+    const [language, ...rest] = parts;
+    if (language === "zh") {
+        const script = rest.find((part) => part.length === 4);
+        if (script)
+            return script === "hans" ? "zh-Hans" : "en";
+        return rest.some((r) => ["tw", "hk", "mo"].includes(r)) ? "en" : "zh-Hans";
+    }
+    return LOCALES.find((locale) => !locale.includes("-") && locale === language);
+}
+// ---------------------------------------------------------------- menus
+/**
+ * The player's built-in top-level menus: id → key (the English text paths
+ * merge by), as the player's `MENU_ANCHORS`.
+ */
+export const MENU_KEYS = {
+    open: "Open",
+    playback: "Playback",
+    subtitles: "Subtitles",
+    video: "Video",
+    audio: "Audio",
+    screen: "Screen",
+    settings: "Settings",
+};
+/** The player's old Chinese titles of its own menus: parent, title, key. */
+const LEGACY_MENUS = [
+    [[], "打开", "Open"],
+    [[], "播放", "Playback"],
+    [[], "字幕", "Subtitles"],
+    [[], "视频", "Video"],
+    [[], "声音", "Audio"],
+    [[], "屏幕", "Screen"],
+    [[], "设置", "Settings"],
+    [["Playback"], "速度", "Speed"],
+    [["Playback"], "跳转", "Seek"],
+    // Shared with a migrated built-in plugin (until all are migrated).
+    [["Settings"], "外观", "Appearance"],
+];
+/** The player's own submenus, by key path (their labels are the player's). */
+export const HOST_GROUPS = [
+    "Open",
+    "Playback",
+    "Subtitles",
+    "Video",
+    "Audio",
+    "Screen",
+    "Settings",
+    "Playback/Speed",
+    "Playback/Seek",
+];
+/**
+ * The keys a path merges by, as the player normalizes it: `@id` becomes the
+ * built-in menu's key, the player's old Chinese titles of its own submenus
+ * their keys.
+ */
+export function menuKeys(path) {
+    const keys = [...path];
+    const id = keys[0]?.startsWith("@") ? keys[0].slice(1) : null;
+    if (id !== null && MENU_KEYS[id])
+        keys[0] = MENU_KEYS[id];
+    for (const [parent, old, key] of LEGACY_MENUS) {
+        const depth = parent.length;
+        if (keys.length > depth + 1 &&
+            parent.every((segment, i) => keys[i] === segment) &&
+            keys[depth] === old)
+            keys[depth] = key;
+    }
+    return keys;
+}
+/**
+ * The player's own texts that the test host repeats (core actions, its
+ * refusals, its menus), English → the player's Simplified Chinese
+ * (`src/host/locales/zh-Hans.po` in the player; its tests check that they
+ * agree).
+ */
+export const HOST_ZH_HANS = {
+    Open: "打开",
+    Playback: "播放",
+    Subtitles: "字幕",
+    Video: "视频",
+    Audio: "声音",
+    Screen: "屏幕",
+    Settings: "设置",
+    Speed: "速度",
+    Seek: "跳转",
+    Close: "关闭",
+    Cancel: "取消",
+    "Play/Pause": "播放/暂停",
+    Previous: "上一个",
+    Next: "下一个",
+    "Previous Frame": "上一帧",
+    "Next Frame": "下一帧",
+    "Back {} s": "后退{}秒",
+    "Forward {} s": "前进{}秒",
+    Normal: "正常",
+    "Slower 0.1": "减速 0.1",
+    "Faster 0.1": "加速 0.1",
+    "Volume +": "音量 +",
+    "Volume −": "音量 −",
+    Mute: "静音",
+    "Not supported by the current source": "当前来源不支持此操作",
+    "The current source cannot step back a frame": "当前来源不支持逐帧后退",
+    "No video": "没有视频",
+    "No previous item": "没有上一个",
+    "No next item": "没有下一个",
+    Paused: "已暂停",
+    Playing: "播放",
+    "Back {} s: {} / {}": "后退 {}秒: {} / {}",
+    "Forward {} s: {} / {}": "前进 {}秒: {} / {}",
+    "Speed: {}x": "播放速度: {}x",
+    "Volume: {}%": "音量: {}%",
+    "Mute: On": "静音: 开",
+    "Mute: Off": "静音: 关",
+    "bottom bar": "底栏",
+    sidebar: "侧栏",
+    "video backdrop": "视频背景",
+    "The {} is used by {}": "{}已被 {} 使用",
+    "The sidebar holds at most {} tabs": "侧栏最多 {} 个页签",
+    "{} is resolved by {}": "{} 已由 {} 解析",
+    "File type .{}": "文件类型 .{}",
+    "Not available in fullscreen": "全屏时不可用",
+    "Picture-in-picture is not supported on this system": "此系统不支持画中画",
+};
+// ---------------------------------------------------------------- packages
+/**
+ * The catalog of a package directory for `locale`, as the player loads it:
+ * the compiled `locales/<lang>.json` of a built package, else the source
+ * `locales/<lang>.po`. Empty for English and without a file; a broken file
+ * throws.
+ */
+export function loadPackageCatalog(directory, locale) {
+    if (locale === "en")
+        return new Catalog();
+    const base = join(directory, "locales", locale);
+    if (existsSync(`${base}.json`)) {
+        const compiled = JSON.parse(readFileSync(`${base}.json`, "utf8"));
+        return new Catalog(compiled.messages ?? {});
+    }
+    if (existsSync(`${base}.po`))
+        return new Catalog(compileCatalog(locale, parsePo(readFileSync(`${base}.po`, "utf8")).entries).messages);
+    return new Catalog();
+}
+// ---------------------------------------------------------------- columns
+const WIDE = /[ᄀ-ᅟ⺀-〾ぁ-㏿㐀-䶿一-鿿ꀀ-꓏가-힣豈-﫿︰-﹏＀-｠￠-￦\u{1F300}-\u{1F64F}\u{1F900}-\u{1F9FF}\u{20000}-\u{3FFFD}]/u;
+const ZERO = /[\p{Mn}\p{Me}​-‏]/u;
+/** Columns of one character: 2 wide (East Asian), 0 combining, else 1. */
+const columnsOf = (c) => (ZERO.test(c) ? 0 : WIDE.test(c) ? 2 : 1);
+/**
+ * Each line of `text` cut to `max` columns, ending with `…` when cut, as
+ * the player cuts an OSD panel's lines (`OsdPanelOptions.maxColumns`; the
+ * player measures with Unicode's East Asian Width, this is close to it).
+ */
+export function fitColumns(text, max) {
+    return text
+        .split("\n")
+        .map((line) => {
+        let used = 0;
+        const chars = [...line];
+        if (chars.reduce((n, c) => n + columnsOf(c), 0) <= max)
+            return line;
+        let out = "";
+        for (const c of chars) {
+            const width = columnsOf(c);
+            if (used + width > max - 1)
+                break;
+            out += c;
+            used += width;
+        }
+        return `${out}…`;
+    })
+        .join("\n");
+}