@vestra-player/sdk 1.5.8 → 1.5.11

package/dist/plugin/types.d.ts

@@ -73,11 +73,11 @@ export interface Disposable {
  * | `timeout` | A time limit ran out (`openStream` start-up, `tools.run`, `system.*` after 10 s). |
  * | `stream`, `device` | `openStream`: the producer failed / the audio device is not ready. |
  * | `backend-uncertain` | The player's backend blocked a filter stage; call `retry()`. |
- * | `limit` | A player-wide limit was reached (for example the number of commands). |
+ * | `limit` | A player-wide limit was reached (for example the number of commands), a property value is over the limits of {@link PropValue}, or a request is longer than the player's 1 MiB message. |
  * | `reserved` | {@link Packages.validate}, {@link PackageCandidate.install}: the id is `vestra` or starts with `vestra.` (any case), which only the player's built-in plugins use (player 0.4.1). |
  * | `versionMismatch` | The package needs a newer player (`minPlayerVersion`) or another `apiVersion`. |
  * | `ui-prepare` | The player could not prepare a mounted panel or a settings page (its Slint file does not compile, a bound property is not declared, or another plugin's panel holds the slot); `message` has the diagnostics. |
- * | `ui` | The player could not apply a property to a tool window or a settings page, or could not build the Options window (a property the Slint file does not declare, a value of the wrong type); `message` has Slint's reason. |
+ * | `ui` | The player could not apply a property to a tool window or a settings page, or could not build the Options window (a property the Slint file does not declare, a value of the wrong type); `message` has Slint's reason. Also reported to {@link Scope.onError} without a request: a callback whose arguments the player could not convert, a property it could not show again when it rebuilt a view (an image file removed since). |
  * | `host` | Any other failure inside the player; `message` is the player's reason. |
  * | `disabled` | The plugin is being stopped; pending requests fail with it. |
  * | `unknown`, `rejected`, `expired` | After a transport problem the SDK could not confirm the outcome (does not happen in normal operation). |
@@ -224,8 +224,10 @@ export interface Scope extends Disposable {
     readonly timeline: Timeline;
     /** Files dropped on the video area, by extension (`ui.drop`). */
     readonly drops: Drops;
-    /** The player's palette. */
+    /** The player's palette and the saved interface language. */
     readonly appearance: Appearance;
+    /** The interface language of this run (read-only). */
+    readonly i18n: I18n;
     /** Pages in the player's options window (`ui.settings`). */
     readonly settings: Settings;
     /**
@@ -339,8 +341,11 @@ export interface CommandState {
     checked: boolean | null;
     /** Shown as busy; like `enabled: false`, the player does not call `run`. Default false. */
     busy: boolean;
-    /** Shown when the command is disabled or busy. */
-    reason: string | null;
+    /**
+     * Shown when the command is disabled or busy: English source text the
+     * player translates, or a {@link Text} (SDK 1.5.11).
+     */
+    reason: TextValue | null;
 }
 /**
  * A value, or a function the SDK re-evaluates on every update pass (see
@@ -360,9 +365,9 @@ export interface CommandState {
 export type Bindable<T> = T | (() => T);
 /**
  * A built-in top-level menu of the player, named in a command path as
- * `@<id>` (see {@link CommandOptions.path}): Open (打开), Playback (播放),
- * Subtitles (字幕), Video (视频), Audio (声音), Screen (屏幕), Settings (设置).
- * The list is `MENU_IDS` in `@vestra-player/sdk/testing`.
+ * `@<id>` or by its English key (see {@link CommandOptions.path}): Open,
+ * Playback, Subtitles, Video, Audio, Screen, Settings. The list is
+ * `MENU_IDS` in `@vestra-player/sdk/testing`.
  */
 export type MenuId = "open" | "playback" | "subtitles" | "video" | "audio" | "screen" | "settings";
 /**
@@ -379,7 +384,7 @@ export type MenuId = "open" | "playback" | "subtitles" | "video" | "audio" | "sc
  * ({@link MenuId}) sit at fixed orders, whatever is inside them: Open 110,
  * Playback 200, Subtitles 300, Video 400, Audio 500, Screen 710, Settings
  * 830 (player 0.3.0). This holds whether the path names the menu by id
- * (`["@video", "Blur"]`) or by its title (`["视频", "Blur"]`), so a plugin's
+ * (`["@video", "Blur"]`) or by its key (`["Video", "Blur"]`), so a plugin's
  * item never moves the player's menu. Directly inside a built-in menu,
  * `order` 0 (the default) sorts after every other order: an item without
  * `order` goes at the end, after the player's own items (which all use 100
@@ -402,22 +407,43 @@ export interface CommandOptions {
      * one segment is a top-level item. Omit it for a command that is not in the
      * main menu (bindings and panel menus only); `title` is then required.
      *
-     * Segments are menu titles, matched exactly. The player's own menus have
-     * Chinese titles, so `["Video", "Blur"]` would add a second top-level menu
-     * "Video". To join a built-in menu, start the path with its id, `@` plus a
-     * {@link MenuId}: `@open`, `@playback`, `@subtitles`, `@video`, `@audio`,
-     * `@screen` or `@settings`. Only the first segment is read as an id; an
-     * unknown id, or an id with nothing after it, fails with `invalid`. Needs
-     * player 0.3.0 (set `"minPlayerVersion": "0.3.0"`).
+     * Segments are English source text, and menus merge by them: commands
+     * of different plugins with the same leading segments share a submenu.
+     * The player shows each segment and the title in the interface language
+     * from the declaring plugin's catalog (`locales/<lang>.po`, see the
+     * [i18n guide](../../docs/how-to/i18n.md)); the player's own menus
+     * (Open, Playback, Subtitles, Video, Audio, Screen, Settings, and
+     * Playback ▸ Speed, Playback ▸ Seek) always show the player's words.
+     * A built-in menu can also be named by its id, `@` plus a {@link MenuId}:
+     * `@open`, `@playback`, `@subtitles`, `@video`, `@audio`, `@screen` or
+     * `@settings`. Only the first segment is read as an id; an unknown id, or
+     * an id with nothing after it, fails with `invalid`. Players up to 0.4.2
+     * titled their menus in Chinese (视频…): there `["Video", "Blur"]` is a
+     * menu of its own, so plugins for those players write `@video`; player
+     * 0.4.3 still accepts the old Chinese titles of its own menus.
+     *
+     * A segment that mixes words with data (a track number, a count) is a
+     * {@link Text} (SDK 1.5.11, player 0.4.3): `plugin.i18n.text("Track {}
+     * ({})", [n, codec])`. The menu shows it translated and filled in; it
+     * merges by its English rendering ("Track 2 (opus)").
      *
      * @example
      * ```ts
      * plugin.commands.add({ id: "blur", path: ["@video", "Blur"], run: toggle });
+     * const { text } = plugin.i18n;
+     * plugin.commands.add({
+     *   id: "track-2",
+     *   path: ["@audio", "Audio Track", text("Track {} ({})", [2, "opus"])],
+     *   run: select,
+     * });
      * ```
      */
-    path?: string[];
-    /** Menu label; defaults to the last path segment. */
-    title?: string;
+    path?: (string | Text)[];
+    /**
+     * Menu label (English source text, shown translated, or a {@link Text});
+     * defaults to the last path segment.
+     */
+    title?: string | Text;
     /**
      * Sibling order in the menu, ascending (integer, default 0). A submenu sits
      * where its first command sits, except a built-in menu, which keeps its
@@ -463,8 +489,11 @@ export interface CommandOptions {
     checked?: Bindable<boolean | null>;
     /** Busy state (default false); the player does not call `run` while busy. */
     busy?: Bindable<boolean>;
-    /** Why the command is disabled or busy (shown to the user). */
-    reason?: Bindable<string | null>;
+    /**
+     * Why the command is disabled or busy (shown to the user): English
+     * source text, or a {@link Text} for one with data in it (SDK 1.5.11).
+     */
+    reason?: Bindable<TextValue | null>;
     /**
      * Run the command (menu item, binding, panel menu or
      * `host.command(id).run()` in tests). It may return a promise; errors
@@ -631,15 +660,31 @@ export interface MarkdownOptions {
  * is refused (Slint treats `_` and `-` as the same, so use camelCase or
  * kebab-case).
  *
+ * A {@link Text} or {@link TextList} goes where the Slint type is `string`,
+ * at any depth (SDK 1.5.11, player 0.4.3): the player shows it translated
+ * with the plugin's catalog, so a `[string]` model (a ComboBox) can mix
+ * words and data. The limits below count it as the string it becomes.
+ *
  * A {@link MarkdownRef} goes where the Slint type is `[MarkdownBlock]`: the
  * whole value, or a field at any depth (SDK 1.5.4; older players refuse a
  * nested one). An {@link ImageRef} only as the whole value: nested in an
  * array or object it is `invalid`.
  *
- * Limits per value: nesting depth 8, 4096 values in total (a document is
- * one), 1024 rows per array, 64 KiB per string and 1 MiB of text in total,
- * the text of its Markdown documents included (256 KB per document). A
- * value over a limit is a failed write (see {@link View}).
+ * Limits per value (`UI_VALUE_LIMITS` in `@vestra-player/sdk/testing`,
+ * player 0.4.3; older players: 4096 values and 1024 rows): nesting depth 8,
+ * 16384 values in total (every array, object, string, number, boolean and
+ * null counts, the value itself included; a document is one), 4096 rows
+ * per array, 64 KiB per string or field name and 1 MiB of text in total,
+ * field names and the text of its Markdown documents included (256 KB per
+ * document). A list of rows with 8 fields is 9 values per row, so about
+ * 1800 rows fit. The whole request must also fit the player's 1 MiB
+ * message. A value over a limit is refused with code `limit` and the
+ * property keeps what it showed (see {@link View.set}); `TestHost` refuses
+ * it the same way.
+ *
+ * The limits bound the work of one write, not the size of your data: for
+ * a list that can grow without bound, send the rows near the view and the
+ * row count, and move that window as the user scrolls.
  *
  * @since 1.0.0
  * @category UI
@@ -659,7 +704,7 @@ export type PropValue = PropData | ImageRef;
  * @since 1.5.4
  * @category UI
  */
-export type PropData = null | boolean | number | string | MarkdownRef | PropData[] | {
+export type PropData = null | boolean | number | string | MarkdownRef | Text | TextList | PropData[] | {
     [key: string]: PropData;
 };
 /**
@@ -902,7 +947,13 @@ export interface View {
      * the next update pass replaces the set value with the bound one.
      *
      * Never throws. A write that fails is retried with back-off and reported
-     * to {@link Scope.onError}.
+     * to {@link Scope.onError} (the first failure of a run of failures; the
+     * message names the property). A value over the limits of
+     * {@link PropValue} fails with `limit`. As an initial property (written
+     * while the view is not open) it makes {@link Window.show} reject; a
+     * panel or settings page still opens without it (the property keeps its
+     * default) and the failure goes to the plugin's `onError` (player 0.4.3;
+     * older players left it out silently).
      *
      * @capability That of the view: `ui.window`, `ui.mount` or `ui.settings`.
      *
@@ -935,7 +986,9 @@ export interface View {
      * run. A view can have several bindings; when two return the same name,
      * the one bound later wins.
      *
-     * Never throws. Writes that fail are not repeated until the value changes.
+     * Never throws. Writes that fail are not repeated until the value
+     * changes, and are reported to {@link Scope.onError} like a failed
+     * {@link View.set} (a value over the limits of {@link PropValue}: `limit`).
      *
      * @capability That of the view: `ui.window`, `ui.mount` or `ui.settings`.
      *
@@ -1940,6 +1993,330 @@ export interface Appearance {
      * @since 1.0.0
      */
     set(theme: ThemeId): Promise<void>;
+    /**
+     * The saved interface language: `"system"` (follow the system's
+     * languages, the default) or a {@link Locale}.
+     *
+     * @remarks
+     * This is the choice for the next start. The language of this run is
+     * {@link I18n.locale} and never changes while the player runs. Read before
+     * activation; with `events` it follows other plugins' changes, without it
+     * only this plugin's own. Players before 0.4.3 report `"system"`.
+     *
+     * @since 1.5.9
+     */
+    readonly language: LanguagePreference;
+    /**
+     * Save the interface language for the next start.
+     *
+     * @remarks
+     * The player keeps the choice in its interface state; the language
+     * changes when the player starts again (tell the user, for example "Takes
+     * effect after restart"). Every plugin with `events` hears the change in
+     * {@link Appearance.language}.
+     *
+     * @capability ui.theme
+     * @player 0.4.3
+     *
+     * @param language - `"system"` or a {@link Locale}.
+     * @returns Resolves once the player saved it; {@link Appearance.language}
+     *   has the new value.
+     *
+     * @throws `invalid` (rejects) `language` is not `"system"` or a {@link Locale}.
+     * @throws `capability` (rejects) The manifest does not declare `ui.theme`.
+     * @throws `unsupported` (rejects) A player before 0.4.3.
+     *
+     * @example
+     * ```ts
+     * await plugin.appearance.setLanguage("de");
+     * await plugin.osd.show("Takes effect after restart");
+     * ```
+     *
+     * @since 1.5.9
+     */
+    setLanguage(language: LanguagePreference): Promise<void>;
+}
+/**
+ * An interface language of the player: English (`en`, the source language
+ * of every plugin text) or a translation. The list is `LOCALES` in
+ * `@vestra-player/sdk/testing`.
+ *
+ * @remarks
+ * Simplified Chinese is `zh-Hans`. There is no Traditional Chinese: a
+ * system set to Traditional Chinese (Taiwan, Hong Kong, Macao) gets English.
+ *
+ * @since 1.5.9
+ * @category UI
+ */
+export type Locale = "en" | "zh-Hans" | "ja" | "ko" | "de" | "fr" | "es";
+/**
+ * The saved interface language ({@link Appearance.language}): follow the
+ * system, or one {@link Locale}.
+ *
+ * @since 1.5.9
+ * @category UI
+ */
+export type LanguagePreference = "system" | Locale;
+/**
+ * Arguments of a template sentence ({@link Osd.show},
+ * {@link OsdPanel.set}, {@link ConfirmOptions.args}, {@link I18n.text}): an
+ * array for `{}` and `{0}`, `{1}` placeholders, or an object for `{name}`
+ * placeholders. At most 16. Strings and finite numbers are data, shown as
+ * they are (whole numbers without a fraction); a {@link Text} or
+ * {@link TextList} argument (SDK 1.5.11, player 0.4.3) is translated too,
+ * so a sentence can be built from translated parts.
+ *
+ * @since 1.5.9
+ * @category UI
+ */
+export type TemplateArgs = readonly TextArg[] | Readonly<Record<string, TextArg>>;
+/**
+ * A text the player translates with the plugin's catalog and fills in:
+ * English source text with its arguments. Made by {@link I18n.text}; plain
+ * data, not a translation (the plugin never sees the translated string).
+ *
+ * @remarks
+ * Accepted wherever the player shows a plugin's text: command titles, path
+ * segments and reasons, {@link Osd.show} and {@link OsdPanel.set} (as the
+ * text or an argument), the texts of {@link Dialogs.confirm}, file dialog
+ * titles and `saveFile`'s `fileName`, and property values where Slint
+ * expects a `string` (at any depth: a `[string]` model, a struct field).
+ * Nested in another text's arguments it is translated too. Requires player
+ * 0.4.3. Limits: `TEXT_LIMITS` in `@vestra-player/sdk/testing`.
+ *
+ * The wire form `{ $vestraText, args }` is what the player reads; write it
+ * with {@link I18n.text}, so that `vestra-plugin i18n extract` finds the
+ * source text.
+ *
+ * @since 1.5.11
+ * @category UI
+ */
+export interface Text {
+    /** The English source text: a template with `{}`, `{0}` or `{name}`. */
+    readonly $vestraText: string;
+    /** Values for its placeholders. */
+    readonly args?: TemplateArgs;
+}
+/**
+ * Values joined the way the interface language joins them ("a, b" in
+ * English, "a、b" in Chinese). Made by {@link I18n.list}; accepted where a
+ * {@link Text} is.
+ *
+ * @since 1.5.11
+ * @category UI
+ */
+export interface TextList {
+    /** The items: data, or texts the player translates. */
+    readonly $vestraList: readonly TextArg[];
+    /** How they are joined; `"list"` by default. */
+    readonly style?: ListStyle;
+}
+/**
+ * How a {@link TextList} is joined, per interface language:
+ *
+ * | style | English | 简体中文 | 日本語 |
+ * | --- | --- | --- | --- |
+ * | `list` (enumeration) | `, ` | `、` | `、` |
+ * | `clauses` (parts of one sentence) | `, ` | `，` | `、` |
+ * | `semicolons` | `; ` | `；` | `；` |
+ * | `sentences` (no final full stop) | `. ` | `。` | `。` |
+ * | `lines` | line break | line break | line break |
+ *
+ * Korean, German and Spanish join as English; French puts a narrow space
+ * before `;`.
+ *
+ * @since 1.5.11
+ * @category UI
+ */
+export type ListStyle = "list" | "clauses" | "semicolons" | "sentences" | "lines";
+/**
+ * An argument of a template: data (a string or a finite number, shown as it
+ * is) or a {@link Text} or {@link TextList} (translated).
+ *
+ * @since 1.5.11
+ * @category UI
+ */
+export type TextArg = string | number | Text | TextList;
+/**
+ * A text the player shows: English source text (translated as a whole), a
+ * {@link Text} or a {@link TextList}.
+ *
+ * @since 1.5.11
+ * @category UI
+ */
+export type TextValue = string | Text | TextList;
+/**
+ * The interface language of this run. `plugin.i18n`.
+ *
+ * @remarks
+ * Plugins write no translation code. Every user-visible text is English
+ * source text in one of three places, and the player translates it with
+ * the plugin's own catalog (`locales/<lang>.po`, compiled into the package
+ * by `vestra-plugin build`):
+ *
+ * 1. declarations: command titles and paths, settings page and panel
+ *    titles, the manifest's `name`, `punchline`, `description` and `tags`;
+ * 2. Slint: `@tr("…")` in the plugin's `.slint` files;
+ * 3. sentences the plugin hands the player: {@link Osd.show},
+ *    {@link OsdPanel.set} and {@link Dialogs.confirm} take a template and
+ *    its arguments (`osd.show("Speed {}×", [rate])`), never a sentence
+ *    composed in TypeScript.
+ *
+ * Where words and data cannot be separated that way (a menu item with a
+ * number, a `[string]` model, a sentence made of translated parts), the
+ * plugin passes a text value ({@link I18n.text}, {@link I18n.list}; SDK
+ * 1.5.11): data the player translates, never a translated string.
+ *
+ * The language is fixed when the player starts: {@link I18n.locale} never
+ * changes during a run. Read it for what is not text, such as the order of
+ * names or a date format. `vestra-plugin i18n extract` collects the texts
+ * into `locales/messages.pot`; see the
+ * [i18n guide](../../docs/how-to/i18n.md).
+ *
+ * @capability None.
+ *
+ * @example Format a date the way the interface language writes it
+ * ```ts
+ * const day = new Date().toLocaleDateString(plugin.i18n.locale);
+ * await plugin.osd.show("Today is {}", [day]);
+ * ```
+ *
+ * @since 1.5.9
+ * @category UI
+ */
+export interface I18n {
+    /**
+     * The interface language of this run, chosen at start-up from the saved
+     * {@link Appearance.language} or the system's languages; English when
+     * neither names a {@link Locale}. Players before 0.4.3 report `"en"`.
+     */
+    readonly locale: Locale;
+    /**
+     * A text that mixes words with data, for the player to translate: the
+     * English source text (a template) and its arguments. It returns a plain
+     * {@link Text} value, not a translation; pass it where the player shows
+     * text (see {@link Text}) and the player shows it translated with this
+     * plugin's catalog. `vestra-plugin i18n extract` collects `source` from
+     * every call, so write it as a literal (or a conditional of literals, or
+     * an `as const` table entry).
+     *
+     * Arguments are data unless they are texts themselves, so a sentence can
+     * be built from translated parts without composing it in TypeScript.
+     * `text` does not use `this`: `const { text, list } = plugin.i18n` works.
+     *
+     * @param source - English source text; `{}`, `{0}` or `{name}` for the
+     *   arguments, `{{` and `}}` for braces.
+     * @param args - Values for its placeholders.
+     * @throws `invalid` A malformed or over-limit value (`TEXT_LIMITS`).
+     *
+     * @example A ComboBox model with fixed words and data
+     * ```ts
+     * const { text } = plugin.i18n;
+     * const picker = plugin.windows.create("ui/clip.slint");
+     * const tracks = [{ id: 7, title: "en" }];
+     * picker.set({
+     *   labels: [text("No Audio"), ...tracks.map((t) => text("Track {} · {}", [t.id, t.title]))],
+     * });
+     * ```
+     *
+     * @example A message built from translated parts
+     * ```ts
+     * await plugin.osd.show("Download failed: {}", [plugin.i18n.text("Connection timed out")]);
+     * ```
+     *
+     * @capability None.
+     *
+     * @since 1.5.11
+     */
+    text(source: string, args?: TemplateArgs): Text;
+    /**
+     * Items joined the way the interface language joins them (see
+     * {@link ListStyle}): `list(["a.glsl", "b.glsl"])` shows "a.glsl, b.glsl"
+     * in English and "a.glsl、b.glsl" in Chinese. Items are data, or texts the
+     * player translates. Accepted where a {@link Text} is.
+     *
+     * @param items - At most 256.
+     * @param style - `"list"` by default.
+     * @throws `invalid` A malformed or over-limit value.
+     *
+     * @example
+     * ```ts
+     * const missing = ["a.glsl", "b.glsl"];
+     * await plugin.osd.show("Removed missing shaders: {}", [plugin.i18n.list(missing)]);
+     * ```
+     *
+     * @capability None.
+     *
+     * @since 1.5.11
+     */
+    list(items: readonly TextArg[], style?: ListStyle): TextList;
+    /**
+     * An `Error` whose words the player shows translated: throw it where the
+     * player shows a plugin's failure to the user, such as from a
+     * file or web resolver's `resolve` ({@link FileResolverOptions}, {@link WebResolverOptions}) (also when a stream
+     * fails while it starts). The player shows `text` translated with this
+     * plugin's catalog (as `player.state.error` and the failure message);
+     * `message` is the English rendering, for logs and older players.
+     * Elsewhere it is an ordinary `Error`.
+     *
+     * @param source - English source text, as {@link I18n.text}'s.
+     * @param args - Values for its placeholders.
+     * @throws `invalid` A malformed or over-limit value.
+     *
+     * @example
+     * ```ts
+     * plugin.resolvers.add({
+     *   id: "nes",
+     *   extensions: ["nes"],
+     *   async resolve() {
+     *     throw plugin.i18n.error("The ROM file was not found.");
+     *   },
+     * });
+     * ```
+     *
+     * @capability None.
+     *
+     * @since 1.5.11
+     */
+    error(source: string, args?: TemplateArgs): TextError;
+    /**
+     * The string a text shows in this run's language, for text that leaves
+     * the player: what the plugin copies to the clipboard or writes to a file
+     * ("Copy info", "Save as…"). Translated with this plugin's catalog (a
+     * string as a whole, a {@link Text} or {@link TextList} with its
+     * arguments), the way the player would show it.
+     *
+     * Only for text leaving the player. Never use it for the interface (a
+     * window, the menu, the OSD, a dialog): pass the value itself there, so
+     * the player translates it and `vestra-plugin i18n check` can see the
+     * sentence is whole.
+     *
+     * @param value - Source text, or a text value.
+     * @returns The translated string.
+     * @throws `invalid` A malformed value.
+     *
+     * @example
+     * ```ts
+     * const { text, list, resolve } = plugin.i18n;
+     * const lines = list([text("Version {}", ["1.0"]), text("Cores: {}", [8])], "lines");
+     * await plugin.clipboard.writeText(resolve(lines));
+     * ```
+     *
+     * @capability None.
+     *
+     * @since 1.5.11
+     */
+    resolve(value: TextValue): string;
+}
+/**
+ * An `Error` the player shows translated ({@link I18n.error}).
+ *
+ * @since 1.5.11
+ * @category UI
+ */
+export interface TextError extends Error {
+    /** What the player shows. */
+    readonly text: Text;
 }
 /**
  * The categories of the Options window. The tree shows them in this order:
@@ -2352,6 +2729,9 @@ export interface TimelineLayer extends Disposable {
      * Replace the layer (last write wins; `[]` clears it). At most 1000 marks,
      * titles ≤ 100 characters, times within the media. Failures go to `onError`;
      * with `ifCurrent`, a write for another source is dropped silently.
+     * A title is data (a chapter's or bookmark's own name), or a {@link Text}
+     * the player translates (`text("Chapter {}", [n])`, SDK 1.5.11); other
+     * plugins read the shown string.
      *
      * @example
      * ```ts
@@ -2366,7 +2746,7 @@ export interface TimelineLayer extends Disposable {
     set(marks: {
         time: number;
         kind: MarkKind;
-        title?: string;
+        title?: string | Text;
     }[], options?: {
         ifCurrent?: PlayerState;
     }): void;
@@ -2560,17 +2940,17 @@ export interface DisplayInfo {
  */
 export interface ConfirmOptions {
     /** The question, shown in bold; 1–200 characters. */
-    message: string;
+    message: TextValue;
     /** More text under the message; at most 2000 characters. */
-    detail?: string;
+    detail?: TextValue;
     /** The confirm button's text (the default button: Enter picks it); 1–40 characters. */
-    confirm: string;
+    confirm: TextValue;
     /**
      * The cancel button's text (Escape picks it); 1–40 characters.
      *
      * @defaultValue "Cancel", in the player's language
      */
-    cancel?: string;
+    cancel?: TextValue;
     /**
      * Mark the confirm button as destructive: red text on macOS, a warning
      * icon on Windows.
@@ -2579,7 +2959,19 @@ export interface ConfirmOptions {
      */
     destructive?: boolean;
     /** A checkbox under the text, such as "Don't ask again"; 1–40 characters. */
-    checkbox?: string;
+    checkbox?: TextValue;
+    /**
+     * Values for the placeholders of `message` and `detail` (player 0.4.3).
+     * Any of the texts may instead be a {@link Text} (SDK 1.5.11), which
+     * carries its own arguments; `args` only fills the string ones.
+     * Every text of the dialog is English source text that the player shows
+     * translated from the plugin's catalog; `message` and `detail` are
+     * templates like {@link Osd.show}'s. The length limits apply to the shown
+     * text.
+     *
+     * @since 1.5.9
+     */
+    args?: TemplateArgs;
 }
 /**
  * The system's own dialogs: a confirmation alert and the open and save file
@@ -2690,8 +3082,8 @@ export interface Dialogs {
      * @since 1.0.0
      */
     openFile(options?: {
-        /** The dialog's title, at most 256 bytes. */
-        title?: string;
+        /** The dialog's title (English source text or a {@link Text}), at most 256 bytes. */
+        title?: TextValue;
     }): Promise<string | null>;
     /**
      * Ask the user for one or more files to open.
@@ -2715,8 +3107,8 @@ export interface Dialogs {
      * @since 1.0.0
      */
     openFiles(options?: {
-        /** The dialog's title, at most 256 bytes. */
-        title?: string;
+        /** The dialog's title (English source text or a {@link Text}), at most 256 bytes. */
+        title?: TextValue;
     }): Promise<string[]>;
     /**
      * Ask the user for a folder.
@@ -2740,8 +3132,8 @@ export interface Dialogs {
      * @since 1.0.0
      */
     openDirectory(options?: {
-        /** The dialog's title, at most 256 bytes. */
-        title?: string;
+        /** The dialog's title (English source text or a {@link Text}), at most 256 bytes. */
+        title?: TextValue;
     }): Promise<string | null>;
     /**
      * Ask the user where to save a file.
@@ -2771,10 +3163,15 @@ export interface Dialogs {
      * @since 1.0.0
      */
     saveFile(options?: {
-        /** The dialog's title, at most 256 bytes. */
-        title?: string;
-        /** The proposed file name: a plain name, at most 256 bytes. */
-        fileName?: string;
+        /** The dialog's title (English source text or a {@link Text}), at most 256 bytes. */
+        title?: TextValue;
+        /**
+         * The proposed file name: a plain name, at most 256 bytes. A string is
+         * data (not translated); a {@link Text} (SDK 1.5.11) is shown
+         * translated, `text("Playlist.m3u8")` (a `/` or `\\` in a translation
+         * becomes `-`).
+         */
+        fileName?: TextValue;
     }): Promise<string | null>;
 }
 /** One audio track of the current media ({@link PlayerState.audioTracks}). */
@@ -3349,18 +3746,38 @@ export interface OsdPanel extends Disposable {
      * @capability ui.osd
      *
      * @param text - The text, with `\n` between lines: at most 32 lines and
-     *   4096 bytes. `null` hides the block.
+     *   4096 bytes once translated and formatted. `null` hides the block. A
+     *   template, like {@link Osd.show}'s.
+     * @param args - Values for its placeholders (player 0.4.3); `null` or
+     *   omitted for none.
+     * @param options - `maxColumns`: cut long lines (SDK 1.5.11).
      *
      * @example
      * ```ts
      * const info = plugin.osd.panel();
-     * info.set("A: 12.0 s\nB: 18.5 s");
+     * info.set("A: {} s\nB: {} s", ["12.0", "18.5"]);
      * info.set(null); // hide it
      * ```
      *
      * @since 1.0.0
      */
-    set(text: string | null): void;
+    set(text: TextValue | null, args?: TemplateArgs | null, options?: OsdPanelOptions): void;
+}
+/**
+ * Options of {@link OsdPanel.set}.
+ *
+ * @since 1.5.11
+ * @category UI
+ */
+export interface OsdPanelOptions {
+    /**
+     * Cut every line longer than this many columns, after translation and
+     * formatting, ending it with `…`: a wide character (Chinese, Japanese,
+     * Korean, full-width forms) is two columns, a combining mark none, any
+     * other one. An integer from 8 to 1000 (player 0.4.3; older players show
+     * whole lines). Measure the video area to choose it.
+     */
+    maxColumns?: number;
 }
 /**
  * Text the player draws over the video: short messages and an information
@@ -3398,24 +3815,38 @@ export interface Osd {
      * Replaces the message on screen, whichever plugin showed it. A message
      * that is on screen when the plugin stops still disappears on time.
      *
+     * The text is a template in English: the player shows its translation
+     * from the plugin's catalog, with the placeholders (`{}`, `{0}`, `{name}`;
+     * `{{` and `}}` for braces) filled from `args`. Without `args` the text
+     * shows as it is (braces included). Untranslated, the English template is
+     * formatted. Never compose the sentence in TypeScript
+     * (`` `Speed ${rate}×` ``): translators can only translate whole templates.
+     * An argument that is itself words is a {@link Text} (SDK 1.5.11), and a
+     * message made of a varying number of parts is a {@link TextList} of
+     * texts; `text` may also be a `Text` (then without `args`).
+     *
      * @capability ui.osd
      *
-     * @param text - 1–200 characters; line breaks become spaces.
+     * @param text - The template, 1–200 characters once translated and
+     *   formatted; line breaks become spaces.
+     * @param args - Values for its placeholders (player 0.4.3; older players
+     *   show the template as it is).
      * @returns Resolves once the message is on screen.
      *
-     * @throws `invalid` (rejects) `text` is empty, only white space, or longer
-     *   than 200 characters.
+     * @throws `invalid` (rejects) The shown text is empty, only white space,
+     *   or longer than 200 characters, or `args` is not a {@link TemplateArgs}.
      * @throws `unavailable` (rejects) The player runs without a user interface.
      * @throws `capability` (rejects) The manifest does not declare `ui.osd`.
      *
      * @example
      * ```ts
      * await plugin.osd.show("Bookmark added");
+     * await plugin.osd.show("Speed {}×", [plugin.player.state.rate]);
      * ```
      *
      * @since 1.0.0
      */
-    show(text: string): Promise<void>;
+    show(text: TextValue, args?: TemplateArgs): Promise<void>;
     /**
      * Create this plugin's information block.
      *
@@ -3720,7 +4151,9 @@ export interface Subtitles {
     /**
      * Upload a subtitle file's bytes (UTF-8 SRT, or ASS/SSA with
      * `format: "ass"`) for the current source; select it unless
-     * `select: "none"`. `title` (1–200 characters) names the track. Aborting
+     * `select: "none"`. `title` (1–200 characters) names the track: data, or
+     * a {@link Text} the player translates (`text("{} · {}", [text("Simplified
+     * Chinese"), file])`, SDK 1.5.11). Aborting
      * `signal` before the commit discards the upload (rejects with AbortError);
      * once the commit was sent it completes.
      *
@@ -3730,7 +4163,7 @@ export interface Subtitles {
      */
     load(bytes: Uint8Array, options?: SubtitleConditional & {
         format?: "srt" | "ass";
-        title?: string;
+        title?: string | Text;
         select?: "primary" | "secondary" | "none";
         signal?: AbortSignal;
     }): Promise<SubtitleTrack>;
@@ -4207,6 +4640,30 @@ export interface PluginInfo {
      * @since 1.5.2
      */
     warnings?: readonly PluginWarning[];
+    /**
+     * The manifest's display texts in the interface language, translated
+     * with that package's catalog; absent from players before 0.4.3 (read
+     * `manifest.json` there).
+     *
+     * @since 1.5.9
+     */
+    display?: PluginDisplay;
+}
+/**
+ * {@link PluginInfo.display}: a package's `name`, `punchline`,
+ * `description` and `tags` as the player shows them.
+ *
+ * @since 1.5.9
+ */
+export interface PluginDisplay {
+    /** `name`, translated; `null` when the manifest has none. */
+    readonly name: string | null;
+    /** `punchline`, translated; `null` when the manifest has none. */
+    readonly punchline: string | null;
+    /** `description`, translated; `null` when the manifest has none. */
+    readonly description: string | null;
+    /** `tags`, each translated. */
+    readonly tags: readonly string[];
 }
 /**
  * One refusal in {@link PluginInfo.warnings}.
@@ -4293,8 +4750,20 @@ export interface BindingRef {
 export interface BindingInfo extends BindingRef {
     /** Menu title. */
     title: string;
-    /** Menu path; `null` for a command outside the menu. */
+    /** Menu path as shown; `null` for a command outside the menu. */
     path: string[] | null;
+    /**
+     * The menu path's keys: the English text menus merge by, the same in
+     * every interface language (`["Playback", "Seek", "Back 5 s"]`; a
+     * built-in menu by its key, `"Video"`, also when declared as `@video`).
+     * `null` for a command outside the menu, and from players before 0.4.3.
+     * Find a command by where it is in the menu with this, not with `path`.
+     * Always set by `list()`; optional so that test fakes written for older
+     * SDKs still type-check.
+     *
+     * @since 1.5.11
+     */
+    key?: string[] | null;
     /** Global, or only while the plugin's panel has focus. */
     scope: "global" | "panel";
     /** The command's own bindings. */