@vestra-player/sdk 1.5.12 → 1.5.13

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 1.5.13
+
+**`i18n extract` keeps the translator's comments and writes the right number of plural forms.** A fix; `apiVersion` stays `vestra/1`.
+
+- Merging into a `locales/<lang>.po` kept only the header's text: comment lines before the header (`# Reviewed by an AI reviewer on 2026-10-25`, `# Translator: …`, `#, fuzzy`) and the translator's own `# ` comments on entries were dropped. Both are now kept as written (`parsePo` returns `headerComments`, entries carry `comments`; `writePo` writes them).
+- A plural entry has exactly `nplurals` `msgstr[n]` lines, from the file's `Plural-Forms` (or the language: one for `ja`, `ko`, `zh-Hans`). Before, every plural entry got an empty `msgstr[1]`, also in one-form languages; a merge now removes such an extra empty line (a filled one stays).
+
 ## 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`.

package/dist/i18n-tools.js

@@ -648,10 +648,17 @@ export function extract(options) {
     const findings = extractor.findings.sort((a, b) => a.file === b.file ? a.line - b.line : a.file < b.file ? -1 : 1);
     return { messages: [...messages.values()], findings };
 }
-const entryOf = (message) => {
+/** `msgstr[n]` lines a plural entry has: the header's `nplurals`, else the language's. */
+const formsOf = (language, header) => {
+    const declared = /nplurals\s*=\s*(\d+)/.exec(header ?? "")?.[1];
+    if (declared !== undefined && Number(declared) >= 1)
+        return Number(declared);
+    return ONE_FORM.has(language) ? 1 : 2;
+};
+const entryOf = (message, forms = 2) => {
     const entry = {
         id: message.id,
-        strings: message.plural === undefined ? [""] : ["", ""],
+        strings: message.plural === undefined ? [""] : Array(forms).fill(""),
         fuzzy: false,
         notes: [...message.notes],
         references: [...message.references],
@@ -669,7 +676,7 @@ export function template(manifest, messages) {
     const project = [manifest.id, manifest.version]
         .filter((part) => typeof part === "string")
         .join(" ");
-    return writePo(`Project-Id-Version: ${project}\nContent-Type: text/plain; charset=UTF-8\nContent-Transfer-Encoding: 8bit\n`, messages.map(entryOf));
+    return writePo(`Project-Id-Version: ${project}\nContent-Type: text/plain; charset=UTF-8\nContent-Transfer-Encoding: 8bit\n`, messages.map((message) => entryOf(message)));
 }
 /** The header of a new `<lang>.po`. */
 export const newHeader = (language) => `Language: ${language}\nContent-Type: text/plain; charset=UTF-8\nContent-Transfer-Encoding: 8bit\nPlural-Forms: ${pluralForms(language)}\n`;
@@ -687,20 +694,30 @@ export function merge(existing, language, messages) {
         old.set(keyOf(entry.context, entry.id), entry);
     const result = [];
     const present = new Set();
+    // A plural entry has exactly nplurals msgstr[n] (one for ja, ko,
+    // zh-Hans); extra empty ones are dropped, filled ones kept.
+    const forms = formsOf(language, parsed?.header ?? newHeader(language));
     let added = 0;
     let translated = 0;
     for (const message of messages) {
         const key = keyOf(message.context, message.id);
         present.add(key);
-        const entry = entryOf(message);
+        const entry = entryOf(message, forms);
         const before = old.get(key);
+        // The translator's own comments stay with their message.
+        if (before?.comments?.length)
+            entry.comments = [...before.comments];
         if (before && hasText(before)) {
             entry.strings = [...before.strings];
             if (message.plural === undefined)
                 entry.strings = [entry.strings[0]];
-            else
-                while (entry.strings.length < 2)
+            else {
+                while (entry.strings.length < forms)
                     entry.strings.push("");
+                while (entry.strings.length > forms &&
+                    entry.strings[entry.strings.length - 1] === "")
+                    entry.strings.pop();
+            }
             entry.fuzzy = before.fuzzy;
             entry.flags = [...before.flags];
         }
@@ -718,7 +735,7 @@ export function merge(existing, language, messages) {
         obsolete++;
     }
     return {
-        text: writePo(parsed?.header ?? newHeader(language), result),
+        text: writePo(parsed?.header ?? newHeader(language), result, parsed?.headerComments ?? []),
         total: messages.length,
         translated,
         added,

package/dist/i18n.d.ts

@@ -25,16 +25,23 @@ export interface PoEntry {
     flags: string[];
     /** A `#~` entry: no longer in the source. */
     obsolete: boolean;
+    /** `# ` lines: the translator's own comments, kept as written. */
+    comments?: string[];
 }
 /** The catalog key: `msgid`, or `msgctxt` U+0004 `msgid`. */
 export declare const keyOf: (context: string | undefined, id: string) => string;
 /** Parse a `.po` (or `.pot`) file. Throws with the line number on errors. */
 export declare function parsePo(text: string): {
     header: string;
+    /** The comment lines before the header entry, as written (`# Reviewed…`, `#, fuzzy`). */
+    headerComments: string[];
     entries: PoEntry[];
 };
-/** Write a `.po` file: the header, then the entries in the given order. */
-export declare function writePo(header: string, entries: readonly PoEntry[]): string;
+/**
+ * Write a `.po` file: the header (after its comment lines, as written),
+ * then the entries in the given order.
+ */
+export declare function writePo(header: string, entries: readonly PoEntry[], headerComments?: readonly string[]): string;
 /** A message of a compiled catalog: a translation, or `[one, other]`. */
 export type CompiledMessage = string | [string, string];
 /**

package/dist/i18n.js

@@ -23,6 +23,9 @@ const translated = (entry) => !entry.fuzzy && !entry.obsolete && (entry.strings[
 export function parsePo(text) {
     const entries = [];
     let header = "";
+    let headerComments = [];
+    // Every comment line of the entry being read, as written.
+    let raw = [];
     const blank = () => ({
         id: "",
         strings: [],
@@ -39,11 +42,14 @@ export function parsePo(text) {
     let pending = blank();
     const finish = () => {
         if (started) {
-            if (entry.id === "" && entry.context === undefined)
+            if (entry.id === "" && entry.context === undefined) {
                 header = entry.strings[0] ?? "";
+                headerComments = raw;
+            }
             else
                 entries.push(entry);
         }
+        raw = [];
         entry = blank();
         started = false;
         field = "none";
@@ -66,8 +72,11 @@ export function parsePo(text) {
         else if (line.startsWith("#")) {
             if (started)
                 finish();
+            raw.push(lines[index].trimEnd());
             const body = line.slice(2).trim();
-            if (line.startsWith("#."))
+            if (line === "#" || line.startsWith("# "))
+                (pending.comments ??= []).push(line.slice(2));
+            else if (line.startsWith("#."))
                 pending.notes.push(body);
             else if (line.startsWith("#:"))
                 pending.references.push(...body.split(/\s+/).filter(Boolean));
@@ -135,7 +144,7 @@ export function parsePo(text) {
         field = next;
     }
     finish();
-    return { header, entries };
+    return { header, headerComments, entries };
 }
 function unquote(text, at) {
     if (text.length < 2 || !text.startsWith('"') || !text.endsWith('"'))
@@ -172,12 +181,19 @@ function field(keyword, text) {
         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)}`];
+/**
+ * Write a `.po` file: the header (after its comment lines, as written),
+ * then the entries in the given order.
+ */
+export function writePo(header, entries, headerComments = []) {
+    const blocks = [
+        [...headerComments, `msgid ""`, field("msgstr", header)].join("\n"),
+    ];
     for (const entry of entries) {
         const prefix = entry.obsolete ? "#~ " : "";
         const lines = [];
+        for (const comment of entry.comments ?? [])
+            lines.push(comment === "" ? "#" : `# ${comment}`);
         for (const note of entry.notes)
             lines.push(`#. ${note}`);
         if (entry.references.length && !entry.obsolete)

package/llms-full.txt

@@ -1,4 +1,4 @@
-# @vestra-player/sdk 1.5.12: full reference
+# @vestra-player/sdk 1.5.13: full reference
 
 > Everything needed to write a Vestra Player plugin (plugin API `vestra/1`): the guides, every public declaration of `@vestra-player/sdk` and `@vestra-player/sdk/testing` with its documentation, and the complete source of the example plugins. Generated from the SDK's sources by scripts/llms.mjs; the short index is llms.txt.
 

package/llms.txt

@@ -1,6 +1,6 @@
 # Vestra Player SDK
 
-> @vestra-player/sdk 1.5.12: write plugins for Vestra Player in TypeScript (plugin API `vestra/1`). A plugin is a folder with `manifest.json` and an entry module whose default export `activate(plugin)` the player calls; it runs in its own Node.js process. llms-full.txt, next to this file, has every declaration, the guides and the examples; L<n> below are its line numbers.
+> @vestra-player/sdk 1.5.13: write plugins for Vestra Player in TypeScript (plugin API `vestra/1`). A plugin is a folder with `manifest.json` and an entry module whose default export `activate(plugin)` the player calls; it runs in its own Node.js process. llms-full.txt, next to this file, has every declaration, the guides and the examples; L<n> below are its line numbers.
 
 **How plugins run**
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vestra-player/sdk",
-  "version": "1.5.12",
+  "version": "1.5.13",
   "description": "Plugin API types, test host and plugin CLI for Vestra Player (apiVersion vestra/1)",
   "license": "Apache-2.0",
   "repository": {