@vestra-player/sdk 1.5.9 → 1.5.12

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## 1.5.12
+
+**Keys of disabled commands pass on; `i18n check` fails on stale catalogs; translator notes in tables; the Button follows its text.** A fix release; `apiVersion` stays `vestra/1`.
+
+- **`TestHost.press` matches the player (0.4.3) for disabled commands.** A disabled command no longer swallows its key: the key goes to the next command bound to it (the one it shadowed in a conflict, then the global scope after a panel binding). With only disabled commands left, the first one with a `reason` shows the reason on the OSD and eats the key; without a reason the key reaches the focused control. `press` now resolves with what happened, `"ran"`, `"reason"` (see `host.osd`) or `"passed"`, instead of rejecting for a disabled command; it still rejects when nothing is bound and when the command that runs is busy. A test that expected `press` to reject for a disabled command now gets `"passed"` or `"reason"`.
+- **`vestra-plugin i18n check` exits with 1** when `locales/messages.pot` is out of date, missing while `.po` files exist, or a `.po` lacks some of the template's messages, so CI catches a forgotten `extract`. Before, it printed these and exited 0. The other findings stay warnings, and `vestra-plugin check` still only prints them.
+- **`TRANSLATORS:` notes on `as const` table entries.** A comment before a property or element of an object or array literal under `as const` (at any depth) now reaches the translators like one at a call site; before, texts extracted through a table lost their notes.
+- **`slint/vestra/widgets.slint`** (the copy of the player's library): `Button`'s preferred width follows its label (the minimum width is unchanged), so a longer translated label widens the button instead of overflowing it.
+
+## 1.5.11
+
+**Text values: words mixed with data, translated by the player** (player 0.4.3). Additive; `apiVersion` stays `vestra/1`, and plugins that worked need no change. 1.5.9 and 1.5.10 were not published to npm; this release includes them. Round-2 i18n requests R2-audio-1, R2-video-1, R2-subtitles-1/2, R2-playlist-1/2, R2-store-1, R2-workshop-1, R2-nes-1, capture #1, P-2, the info and hotkeys export texts, timeline and subtitle titles: one mechanism. Guide: [Translate a plugin ▸ Text that mixes words and data](docs/how-to/i18n.md#text-that-mixes-words-and-data).
+
+- **`plugin.i18n.text(source, args?)`** returns a `Text`: plain, frozen data (`{ $vestraText, args }`), not a translation. The player translates `source` with the plugin's catalog and fills in `args` wherever it shows it. Arguments are data, or text values that are translated too, so a sentence can be built from translated parts without composing it in TypeScript.
+- **`plugin.i18n.list(items, style?)`** returns a `TextList`: items joined with the interface language's separator (`ListStyle`: `"list"` `, ` / `、`, `"clauses"` `, ` / `，`, `"semicolons"`, `"sentences"`, `"lines"`; `LIST_SEPARATORS` in `@vestra-player/sdk/testing`).
+- **Accepted wherever the player shows a plugin's text**: command `title`, `path` segments (the menu merges by the English rendering) and `reason`; `osd.show` and `OsdPanel.set` as the text or an argument (`TemplateArgs` now takes `TextArg`); every `dialogs.confirm` text; file dialog `title` and `saveFile`'s `fileName` (a string `fileName` stays data); property values where Slint has a `string`, at any depth (`PropData` takes `Text` and `TextList`), so a ComboBox model can mix fixed words and data; `TimelineLayer.set` mark titles; `subtitles.load({ title })`.
+- **`plugin.i18n.error(source, args?)`**: an `Error` (`TextError`) whose words the player shows translated when a file or web resolver's `resolve` throws it (also a stream failing while it starts): the open's failure and `player.state.error`. `message` is the English rendering.
+- **`plugin.i18n.resolve(value)`**: the translated string, for text that leaves the player only (clipboard, files). Never for the interface.
+- **`OsdPanel.set(text, args, { maxColumns })`** (`OsdPanelOptions`): the player cuts each line after translation (a wide character is two columns).
+- **`BindingInfo.key`**: the menu path's English keys, the same in every language (P-2). Find a command by its place in the menu with it, not with `path`.
+- **Limits** (`TEXT_LIMITS` in `@vestra-player/sdk/testing`): nesting 8, 1024 values in one text, 16 arguments per text, 256 items per list, 4096 bytes per source or string argument (template string arguments were 1024 bytes). A malformed value throws `invalid` where it is made, and the player refuses it with `invalid`. A property value's limits count a text value as the string it becomes.
+- **`vestra-plugin i18n extract`** collects the source of every `plugin.i18n.text(…)`, `error(…)` and `resolve("…")` call (also destructured: `const { text } = plugin.i18n`) and of a `{ $vestraText: "…" }` literal. Every source is collected, also one made only of placeholders and punctuation (`"{} ({})"`, which Chinese writes `"{}（{}）"`). It now reads fields spread into a call's options (`commands.add({ ...extra })`) by their types and reports the ones it cannot extract; before, it skipped them without a word. A field typed as a text value is not reported as "not a literal".
+- **Type note**: the option fields that now take a text value (`ConfirmOptions.message` and the other dialog texts, `CommandOptions.title`/`path`/`reason`, `CommandState.reason`, file dialog `title`/`fileName`, `TemplateArgs`) are wider types. Code that only passes them is unchanged; code that reads such a field back as a `string` (a helper that cuts `options.message`) needs a `typeof … === "string"` check.
+- **`TestHost`** shows text values as the player does: `FakeCommand.display` (and the non-enumerable `display.reason`), `host.osd`, `host.osdPanel` (cut to `maxColumns`), `host.confirmTexts`, new `host.fileDialogs` (`FileDialogText`), window, panel and settings page `props` (text values replaced by their strings; `host.sent(...)` keeps what the plugin sent), timeline titles, subtitle titles, a resolver's `TextError`, and `BindingInfo.key`. `host.translate` takes a text value too. It refuses malformed text values with the player's messages.
+
+## 1.5.10
+
+**Property value limits: documented, higher, enforced by `TestHost`, reported loudly** (player 0.4.3). A fix; `apiVersion` stays `vestra/1`, and plugins that worked need no change. 1.5.9 was not published to npm; this release includes its changes.
+
+- **`UI_VALUE_LIMITS`** in `@vestra-player/sdk/testing`: the player's limits on one property value, which used to appear only in the `PropValue` description. Raised in player 0.4.3 (older players in brackets): nesting depth 8, **16384 values** (4096), **4096 rows per array** (1024), 64 KiB per string or field name, 1 MiB of text. A list of 8-field rows is 9 values per row, so about 1800 rows fit (about 450 before). The player's tests check that the constant agrees with the player.
+- **`TestHost` enforces them** on `ui.open`, `ui.set`, `ui.mount`, `ui.setMount`, `settings.register` and `settings.set`, with the player's code and message. Before, it took any value, so a plugin whose list outgrew the limit passed its tests and showed a stale list in the player (D1: a 3000-row playlist). A test that writes a value over the limits now sees the failure in `onError` (or, for a tool window's initial property, a rejected `Window.show`).
+- **Failures say what they are.** A value over the limits fails with code **`limit`** (was `host`) and the message names the property (`rows: UI array exceeds 4096 rows`). A panel's or settings page's initial property over the limits is still left out (the panel mounts without it; a failed mount during activation would fail the plugin), but the player now reports it to `onError` instead of only writing its log.
+- **`ui.error` reaches `onError`.** The player reports failures nobody asked about: a callback whose arguments it could not convert, a property it could not show again when it rebuilt a panel or the Options window (an image file removed since), a detached sidebar it could not prepare. The SDK used to drop these; it now reports them to the root scope's `onError` with the player's code (`ui` from older players).
+- The player's runner (player 0.4.3) refuses a request longer than the player's 1 MiB message with `limit`; before, the player stopped the plugin.
+
 ## 1.5.9
 
 **Translations** (player 0.4.3). Additive; `apiVersion` stays `vestra/1`, and plugins written for 1.5.8 need no change. One test-visible change: a core action's `declaration.path` in `TestHost` is now the player's English key (read `display` for what the menu shows). The player now shows its interface in English, Simplified Chinese, Japanese, Korean, German, French or Spanish, chosen at start-up; a plugin writes every text in English and ships one gettext file per language. Plugins write no translation code: the player translates. Guides: [Translate a plugin](docs/how-to/i18n.md), [Migrate a plugin to English source text](docs/how-to/i18n-migration.md); example: `examples/i18n`.

package/README.md

@@ -83,7 +83,7 @@ Complete, tested plugins in [`examples/`](https://github.com/vestrasys/vestra-pl
 | `vestra-plugin build [dir...] [--version x.y.z]`            | Writes `dist/`: types stripped, files copied, manifest versioned.          |
 | `vestra-plugin pack [dir...] [--version x.y.z] [--out dir]` | Builds, then packs `dist/` as `<id>-<version>.vxp`.                        |
 | `vestra-plugin i18n extract [dir...] [--locale lang]`       | Collects the texts to translate into `locales/`, keeping translations.     |
-| `vestra-plugin i18n check [dir...]`                         | Translation coverage and untranslatable text (warnings only).              |
+| `vestra-plugin i18n check [dir...]`                         | Translation coverage and untranslatable text; fails on stale catalogs.     |
 
 ## Compatibility
 

package/bin/vestra-plugin.mjs

@@ -29,7 +29,8 @@
  *   i18n check    coverage per language, placeholder and plural problems, a
  *                 stale messages.pot, and texts that cannot be translated
  *                 (composed in TypeScript, not literals, not English, Slint
- *                 text without @tr); warnings only, an unreadable .po fails
+ *                 text without @tr) as warnings; fails (exit 1) on a stale
+ *                 messages.pot, a .po missing messages, an unreadable file
  *
  * `check` prints the same i18n warnings when the plugin has locales/;
  * `build` compiles locales/<lang>.po to dist/locales/<lang>.json (the .po
@@ -430,7 +431,8 @@ async function i18nCheck(target) {
   dependencies(target);
   const { warnings, errors } = await i18nReport(target);
   for (const line of warnings) console.log(`${target.name}: i18n: ${line}`);
-  if (errors.length) fail(`${target.name}: ${errors.join("; ")}`);
+  // A stale messages.pot, a .po missing messages, an unreadable file.
+  if (errors.length) fail(`${target.name}: i18n: ${errors.join("; ")}`);
   if (!warnings.length) console.log(`${target.name}: i18n: no problems`);
 }
 

package/dist/commands.d.ts

@@ -1,5 +1,6 @@
 /** Finite candidate command registry. Host authenticates owner; no plugin supplies an owner id. */
 import type { Transport } from "./wire.ts";
+import type { ListJson, TextJson } from "./i18n.ts";
 /**
  * The player's command registry caps, the same values as the player's own
  * table (the player's tests check that they agree). They are runaway guards,
@@ -47,12 +48,14 @@ export type CommandState = {
     enabled: boolean;
     checked: boolean | null;
     busy: boolean;
-    reason: string | null;
+    /** Source text, or a text value (player 0.4.3). */
+    reason: string | TextJson | ListJson | null;
 };
 export type CommandDeclaration = {
-    title: string;
-    /** Complete primary menu path INCLUDING its leaf; empty = not in the main menu. */
-    path: string[];
+    /** Source text, or a text value (player 0.4.3). */
+    title: string | TextJson;
+    /** Complete primary menu path INCLUDING its leaf; empty = not in the main menu. Segments may be text values (player 0.4.3). */
+    path: (string | TextJson)[];
     /** Sibling order, ascending; a submenu takes its first command's order (a built-in menu keeps a fixed one). */
     order: number;
     /** Separator label: adjacent siblings of different groups get a line. */

package/dist/i18n-tools.js

@@ -26,7 +26,7 @@ export const pluralForms = (language) => ONE_FORM.has(language)
     : "nplurals=2; plural=(n != 1);";
 const slash = (path) => path.split(sep).join("/");
 const CJK = /[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Hangul}]/u;
-const COMPOSED = 'user-visible text composed in TypeScript: pass a template with args (osd.show("Speed {}×", [rate])) or move it into Slint';
+const COMPOSED = 'user-visible text composed in TypeScript: pass a template with args (osd.show("Speed {}×", [rate]), plugin.i18n.text("Track {}", [n])) or move it into Slint';
 const DYNAMIC = (what) => `${what} is not a literal; its text cannot be extracted (use a string literal or an \`as const\` table)`;
 const SITES = {
     "Commands.add": { object: 0, fields: ["title", "reason"], path: true },
@@ -43,6 +43,9 @@ const SITES = {
     "Dialogs.openFiles": { object: 0, fields: ["title"] },
     "Dialogs.openDirectory": { object: 0, fields: ["title"] },
     "Dialogs.saveFile": { object: 0, fields: ["title"] },
+    "I18n.text": { argument: 0 },
+    "I18n.error": { argument: 0 },
+    "I18n.resolve": { argument: 0 },
 };
 /** Without the SDK's types: the module property names in front of the method. */
 const BY_NAME = {
@@ -55,6 +58,9 @@ const BY_NAME = {
     "dialogs.openFiles": "Dialogs.openFiles",
     "dialogs.openDirectory": "Dialogs.openDirectory",
     "dialogs.saveFile": "Dialogs.saveFile",
+    "i18n.text": "I18n.text",
+    "i18n.error": "I18n.error",
+    "i18n.resolve": "I18n.resolve",
 };
 const none = () => ({ values: [], dynamic: false, composed: false });
 const join2 = (a, b) => ({
@@ -94,6 +100,34 @@ function ignored(node, text) {
         .slice(node.getFullStart(), node.getStart())
         .includes("i18n-ignore");
 }
+/**
+ * A string that is an entry (a property value or an element) of an object
+ * or array literal inside `… as const`, at any depth.
+ */
+function inConstTable(node) {
+    let current;
+    if (ts.isPropertyAssignment(node.parent) && node.parent.initializer === node)
+        current = node.parent.parent;
+    else if (ts.isArrayLiteralExpression(node.parent))
+        current = node.parent;
+    else
+        return false;
+    for (;;) {
+        const parent = current.parent;
+        if (ts.isAsExpression(parent) &&
+            ts.isTypeReferenceNode(parent.type) &&
+            ts.isIdentifier(parent.type.typeName) &&
+            parent.type.typeName.text === "const")
+            return true;
+        if (ts.isPropertyAssignment(parent))
+            current = parent.parent;
+        else if (ts.isArrayLiteralExpression(parent) ||
+            ts.isParenthesizedExpression(parent))
+            current = parent;
+        else
+            return false;
+    }
+}
 /** The statement (or class member) a node belongs to. */
 function statementOf(node) {
     let current = node;
@@ -105,6 +139,11 @@ function statementOf(node) {
 }
 class Extractor {
     found = [];
+    /**
+     * `TRANSLATORS:` notes on entries of `as const` tables, by text: a table
+     * entry is extracted through its literal type, which has no comments.
+     */
+    tableNotes = new Map();
     findings = [];
     #checker;
     constructor(checker) {
@@ -125,6 +164,11 @@ class Extractor {
         for (const part of parts) {
             if (part.isStringLiteral())
                 result.values.push(part.value);
+            // A text value (`plugin.i18n.text(…)`): its source is extracted where
+            // it is made.
+            else if (part.getProperty("$vestraText") ||
+                part.getProperty("$vestraList"))
+                continue;
             else if (part.flags &
                 (ts.TypeFlags.Null |
                     ts.TypeFlags.Undefined |
@@ -249,10 +293,22 @@ class Extractor {
     /** `Interface.method` of a call to the SDK, if it is one of `SITES`. */
     #site(call) {
         const callee = call.expression;
-        if (!ts.isPropertyAccessExpression(callee))
+        const declaration = this.#checker?.getResolvedSignature(call)?.declaration;
+        if (!ts.isPropertyAccessExpression(callee)) {
+            // `const { text } = plugin.i18n; text("…")`: by the declaration.
+            if (declaration &&
+                !ts.isJSDocSignature(declaration) &&
+                declaration.parent &&
+                ts.isInterfaceDeclaration(declaration.parent) &&
+                declaration.name &&
+                ts.isIdentifier(declaration.name) &&
+                /\/plugin\/types\.(d\.)?ts$/.test(slash(declaration.getSourceFile().fileName))) {
+                const name = `${declaration.parent.name.text}.${declaration.name.text}`;
+                return name in SITES ? name : undefined;
+            }
             return undefined;
+        }
         const method = callee.name.text;
-        const declaration = this.#checker?.getResolvedSignature(call)?.declaration;
         if (declaration &&
             !ts.isJSDocSignature(declaration) &&
             declaration.parent &&
@@ -279,6 +335,27 @@ class Extractor {
         const visit = (node) => {
             if (ts.isCallExpression(node))
                 this.#call(node, file, source, text);
+            if ((ts.isStringLiteral(node) ||
+                ts.isNoSubstitutionTemplateLiteral(node)) &&
+                inConstTable(node)) {
+                // The comment sits before the entry: the property, or the element.
+                const entry = ts.isPropertyAssignment(node.parent) ? node.parent : node;
+                const notes = notesOf(entry, text);
+                if (notes.length) {
+                    const known = this.tableNotes.get(node.text) ?? [];
+                    for (const note of notes)
+                        if (!known.includes(note))
+                            known.push(note);
+                    this.tableNotes.set(node.text, known);
+                }
+            }
+            // A text value written as data: `{ $vestraText: "…" }`.
+            if (ts.isPropertyAssignment(node) &&
+                (ts.isIdentifier(node.name) || ts.isStringLiteral(node.name)) &&
+                node.name.text === "$vestraText" &&
+                !ignored(node, text) &&
+                !ignored(statementOf(node), text))
+                this.#emit(this.values(node.initializer), node.initializer, file, source, "the source of a text", () => true, [...notesOf(statementOf(node), text), ...notesOf(node, text)]);
             if ((ts.isStringLiteral(node) ||
                 ts.isNoSubstitutionTemplateLiteral(node)) &&
                 CJK.test(node.text) &&
@@ -330,6 +407,32 @@ class Extractor {
             return;
         }
         for (const property of object.properties) {
+            if (ts.isSpreadAssignment(property)) {
+                // `{ ...extra }`: the spread object's fields, by their types; a
+                // field that is not a literal (or a text value) is reported.
+                const checker = this.#checker;
+                const at = source.getLineAndCharacterOfPosition(property.getStart(source)).line +
+                    1;
+                if (!checker) {
+                    this.finding(file, at, "dynamic", `fields spread into ${name} cannot be read without types; write ${fields.join(", ")} explicitly`);
+                    continue;
+                }
+                if (ignored(property, text))
+                    continue;
+                const type = checker.getTypeAtLocation(property.expression);
+                for (const field of fields) {
+                    const symbol = type.getProperty(field);
+                    if (!symbol)
+                        continue;
+                    if (field === "path") {
+                        this.finding(file, at, "dynamic", `a path spread into ${name} cannot be extracted; write path explicitly`);
+                        continue;
+                    }
+                    const fieldType = checker.getTypeOfSymbolAtLocation(symbol, property.expression);
+                    this.#emit(this.#fromType(fieldType), property, file, source, `${field} spread into ${name}`, () => true, statementNotes);
+                }
+                continue;
+            }
             const key = property.name &&
                 (ts.isIdentifier(property.name) || ts.isStringLiteral(property.name))
                 ? property.name.text
@@ -533,7 +636,10 @@ export function extract(options) {
         }
         if (occurrence.plural !== undefined && message.plural === undefined)
             message.plural = occurrence.plural;
-        for (const note of occurrence.notes)
+        const tableNotes = occurrence.context === undefined
+            ? (extractor.tableNotes.get(occurrence.id) ?? [])
+            : [];
+        for (const note of [...occurrence.notes, ...tableNotes])
             if (!message.notes.includes(note))
                 message.notes.push(note);
         if (!message.references.includes(reference))
@@ -627,24 +733,26 @@ export function checkCatalogs(directory, messages, findings) {
     const pot = join(locales, "messages.pot");
     const keys = (entries) => new Set(entries.map((e) => `${keyOf(e.context, e.id)}\u0000${e.plural ?? ""}`));
     const wanted = keys(messages);
+    const files = existsSync(locales)
+        ? readdirSync(locales)
+            .filter((name) => name.endsWith(".po"))
+            .sort()
+        : [];
+    // A stale template or a .po without some of its messages fails
+    // `i18n check` (an error); `check` prints it like the warnings.
     if (!existsSync(pot))
-        warnings.push("locales/messages.pot is missing: run vestra-plugin i18n extract");
+        (files.length ? errors : warnings).push("locales/messages.pot is missing: run vestra-plugin i18n extract");
     else {
         try {
             const have = keys(parsePo(readFileSync(pot, "utf8")).entries);
             const same = have.size === wanted.size && [...wanted].every((key) => have.has(key));
             if (!same)
-                warnings.push("locales/messages.pot is out of date: run vestra-plugin i18n extract");
+                errors.push("locales/messages.pot is out of date: run vestra-plugin i18n extract");
         }
         catch (error) {
             errors.push(`locales/messages.pot: ${error.message}`);
         }
     }
-    const files = existsSync(locales)
-        ? readdirSync(locales)
-            .filter((name) => name.endsWith(".po"))
-            .sort()
-        : [];
     for (const name of files) {
         const language = name.slice(0, -3);
         if (language === "en") {
@@ -673,7 +781,7 @@ export function checkCatalogs(directory, messages, findings) {
         const inFile = keys(live);
         const missing = [...wanted].filter((key) => !inFile.has(key)).length;
         if (missing)
-            warnings.push(`locales/${name}: ${missing} ${missing === 1 ? "message is" : "messages are"} not in this file: run vestra-plugin i18n extract`);
+            errors.push(`locales/${name}: ${missing} ${missing === 1 ? "message is" : "messages are"} not in this file: run vestra-plugin i18n extract`);
         for (const entry of live) {
             entry.strings.forEach((text, form) => {
                 if (text === "")

package/dist/i18n.d.ts

@@ -1,3 +1,4 @@
+import type { ListStyle, Locale } from "./plugin/types.ts";
 /**
  * The player's interface languages: English (the source language) first,
  * then the translations, as the player's own table (its tests check that
@@ -78,6 +79,83 @@ export declare function format(template: string, args: TemplateArgsValue): strin
  * number (`{n}` of a Slint plural is `"n"`). Translations must keep them.
  */
 export declare function placeholders(text: string): string[];
+/**
+ * The ways a `TextList` is joined (`ListStyle`), as the player
+ * joins them in each interface language (`LIST_SEPARATORS`).
+ */
+export declare const LIST_STYLES: readonly ListStyle[];
+/**
+ * The separator of each list style per interface language, as the player's
+ * table (`i18n::text::SEPARATORS`; its tests check that they agree).
+ */
+export declare const LIST_SEPARATORS: Readonly<Record<Locale, Readonly<Record<ListStyle, string>>>>;
+/**
+ * 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 declare const TEXT_LIMITS: {
+    /** Nesting depth of texts and lists; the value itself is depth 0 (8). */
+    readonly depth: 8;
+    /** Texts, lists and arguments in all, the value itself included (1024). */
+    readonly nodes: 1024;
+    /** Arguments of one text (16). */
+    readonly args: 16;
+    /** Items of one list (256). */
+    readonly items: 256;
+    /** UTF-8 bytes of a source text or a string argument (4096). */
+    readonly stringBytes: 4096;
+};
+/** A translatable text on the wire: English source text and its arguments. */
+export type TextJson = {
+    $vestraText: string;
+    args?: ArgJson[] | {
+        [name: string]: ArgJson;
+    };
+};
+/** A list on the wire: items joined the interface language's way. */
+export type ListJson = {
+    $vestraList: ArgJson[];
+    style?: ListStyle;
+};
+/** An argument of a text: data (strings and numbers) or another text. */
+export type ArgJson = string | number | TextJson | ListJson;
+/** A text or list value (by its marker key). */
+export declare function isTextValue(value: unknown): value is TextJson | ListJson;
+/**
+ * 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 declare function textProblem(value: unknown, mode?: "value" | "args"): string | null;
+type TemplateArgsLike = readonly ArgJson[] | Readonly<Record<string, ArgJson>> | null;
+/**
+ * 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 declare function renderText(value: TextJson | ListJson, catalog: Catalog, locale: string): string;
+/**
+ * Template arguments with their texts rendered (for `format`): what the
+ * player fills a template with.
+ */
+export declare function renderTemplateArgs(args: TemplateArgsLike | undefined, catalog: Catalog, locale: string): TemplateArgsValue | undefined;
+/** The English rendering of a text value: the key a menu merges by. */
+export declare function textKey(value: TextJson | ListJson): string;
+/**
+ * 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 declare function resolveTexts<T>(value: T, catalog: Catalog, locale: string): {
+    value: T;
+} | {
+    problem: string;
+};
+/** Whether a value holds a text value anywhere (a cheap pre-check). */
+export declare function hasTexts(value: unknown): boolean;
 /** One `@tr("context" => "id" | "plural" % n, args…)` call. */
 export interface TrCall {
     context?: string;
@@ -128,3 +206,17 @@ export declare function menuKeys(path: readonly string[]): string[];
  * agree).
  */
 export declare const HOST_ZH_HANS: Readonly<Record<string, string>>;
+/**
+ * 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 declare function loadPackageCatalog(directory: string, locale: string): Catalog;
+/**
+ * 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 declare function fitColumns(text: string, max: number): string;
+export {};