@gjsify/vite-plugin-gettext 0.47.0 → 0.48.0

package/README.md

@@ -16,6 +16,54 @@ yarn add @gjsify/vite-plugin-gettext
 
 Requires `gettext` tools (`msgfmt`, `xgettext`) to be installed on the system.
 
+## Extraction refuses to destroy translations
+
+`xgettextPlugin` fails the build instead of writing a POT that would silently gut the catalogs:
+
+- **Every `sources` pattern must match at least one file**, and the run as a whole must find at
+  least one. A pattern that matches nothing is almost always a build-order or path mistake —
+  typically it points at a build artifact of another package that has not been built yet — and
+  extracting anyway drops that whole group of strings. A group that really is optional is named in
+  `optionalSources`, one pattern at a time. Negated patterns (`!plugins/**/*.ui`) are exclusions
+  over the whole set, not groups of their own, so they are never required to match.
+- **`autoUpdatePo` will not prune a catalog set beyond `maxCatalogEntryLoss`** (default `1/3`).
+  What is compared is the *set of msgids* the new POT still carries against the largest catalog's,
+  because that is what `msgmerge` acts on: it moves every entry the POT no longer has into `#~`
+  comments, which `msgfmt` ignores. A POT that came out short costs real translations, and so does
+  one that is the same length but re-worded — `msgmerge` fuzzy-matches those, and `msgfmt` leaves
+  fuzzy entries out of the `.mo`. A run that really does replace that many strings raises the
+  option.
+
+```typescript
+xgettextPlugin({
+    sources: ['src/**/*.blp', 'data/**/*.desktop.in', '!src/**/*.generated.blp'],
+    output: 'po/messages.pot',
+    autoUpdatePo: true,
+    // optionalSources: ['plugins/**/*.ui'],
+    // maxCatalogEntryLoss: 0.5, // a FRACTION, not a percentage; 1 turns the check off
+});
+```
+
+Both guards throw. `xgettext`, `msgcat` and `msgmerge` failures are no longer reported to the
+console beside a zero exit code either — a build that could not write the catalogs it was asked to
+write fails.
+
+### A `sources` pattern reaching into a sibling package is a build dependency
+
+`sources` is read at extraction time, so a pattern like `../learn/dist/**/*.ui` requires that the
+sibling package has already been built. Declaring it in `dependencies` is not enough on its own:
+building the one package (`gjsify workspace <name> build`) does not build what it depends on.
+Either run the extracting package with `-t`, which pre-builds its workspace dependencies in
+topological order:
+
+```bash
+gjsify workspace @scope/translations build -t
+```
+
+or make the dependency's build an explicit step of the script that needs it. Without one of the
+two, the artifact is whatever the last run left behind, which is the state the pattern guard above
+exists to catch.
+
 ## Usage
 
 ```typescript

package/lib/guards.d.ts

@@ -0,0 +1,121 @@
+/** Base class so the plugin can rethrow a guard verbatim instead of wrapping it. */
+export declare class GettextGuardError extends Error {
+}
+/** A `sources` pattern matched nothing, and was not declared optional. */
+export declare class EmptySourcePatternError extends GettextGuardError {
+    /** The patterns that matched no files, verbatim as configured. */
+    readonly patterns: readonly string[];
+    constructor(message: string, 
+    /** The patterns that matched no files, verbatim as configured. */
+    patterns: readonly string[]);
+}
+/** `msgmerge` would obsolete more of the catalogs than this build allows. */
+export declare class CatalogShrinkError extends GettextGuardError {
+    /** Entries the reference catalog holds that the new POT no longer carries. */
+    readonly lostEntries: number;
+    readonly catalogEntries: number;
+    constructor(message: string, 
+    /** Entries the reference catalog holds that the new POT no longer carries. */
+    lostEntries: number, catalogEntries: number);
+}
+/** A `maxCatalogEntryLoss` that is not a fraction — the guard cannot act on it. */
+export declare class InvalidEntryLossError extends GettextGuardError {
+    constructor(message: string);
+}
+/** One `sources` pattern and how many files it actually resolved to. */
+export interface SourcePatternMatch {
+    /** The pattern verbatim as configured — it is what an error has to name. */
+    pattern: string;
+    fileCount: number;
+}
+/** A catalog's language and the msgids it currently still uses. */
+export interface CatalogMsgids {
+    language: string;
+    msgids: ReadonlySet<string>;
+}
+/**
+ * Fraction of its entries a catalog set may lose in one extraction.
+ *
+ * Why a RATIO: an absolute count cannot be right for both a twelve-string dialog
+ * and a nine-hundred-string tutorial. Why a THIRD: the two populations this has
+ * to separate are far apart. Ordinary churn between two runs of the same build is
+ * a handful of strings — single-digit percent of any real catalog — while the
+ * failure above drops a whole source group at once. A third sits in the empty
+ * space between them. Half, the other candidate, is worse: a project with two
+ * source groups of similar size loses one of them at ~50% and slips under.
+ *
+ * A deliberate rewrite that really does delete more says so with
+ * `maxCatalogEntryLoss`, which is the point of it being an option.
+ */
+export declare const DEFAULT_MAX_CATALOG_ENTRY_LOSS: number;
+/**
+ * Fails unless every source pattern resolved to at least one file.
+ *
+ * FAILING IS THE DEFAULT ON PURPOSE. A pattern that matches nothing is almost
+ * always a build-order or path mistake, and the cost of being wrong is
+ * asymmetric: a false failure costs one build, a missed one costs every
+ * translation the group carried. A project that genuinely has an optional group
+ * names those patterns in `optionalSources` — per pattern, never a blanket
+ * boolean, so the guard stays armed for every other entry.
+ */
+export declare function assertEverySourcePatternMatched(matches: readonly SourcePatternMatch[], context: {
+    pluginName: string;
+    cwd: string;
+    optionalSources?: readonly string[];
+    ignore?: readonly string[];
+}): void;
+/**
+ * Reads `maxCatalogEntryLoss`, which has to be a FRACTION.
+ *
+ * Validated separately, and before the catalogs are looked at, because the two
+ * ways of getting it wrong both end in silence. `50` — the option read as a
+ * percentage — is `<= 50` for every possible ratio, so the guard passes
+ * everything and reports nothing; `NaN` fails every comparison, so the guard
+ * fires on a build that lost nothing and gets raised out of the way. Neither
+ * would ever be traced back to the option.
+ */
+export declare function resolveMaxEntryLoss(value: number | undefined, pluginName: string): number;
+/**
+ * Fails when merging the freshly written POT would obsolete more of the catalogs
+ * than `maxEntryLoss` allows.
+ *
+ * What is measured is the SET of msgids the POT no longer carries, not how much
+ * shorter it got. `msgmerge` matches by msgid, so an equally long POT whose
+ * strings have changed obsoletes just as much as a short one — and measured on
+ * gettext 0.26, a msgid that only gained a space is fuzzy-matched, keeps its
+ * translation, and is then excluded from the `.mo` by `msgfmt` anyway. A count
+ * cannot see that; a set difference is the quantity `msgmerge` acts on.
+ *
+ * The reference is the LARGEST catalog rather than each one in turn: `msgmerge`
+ * gives every catalog the POT's msgid set (measured — a 1-entry and a 2-entry
+ * catalog both came back with the POT's 3), so the biggest one is the best
+ * evidence of what the project had before this run. Comparing per language would
+ * let one catalog that a previous bad run already gutted excuse gutting the rest.
+ */
+export declare function assertCatalogsSurviveMerge(args: {
+    potMsgids: ReadonlySet<string>;
+    catalogs: readonly CatalogMsgids[];
+    potFile: string;
+    pluginName: string;
+    maxEntryLoss?: number;
+}): void;
+/**
+ * The msgids a PO/POT file still USES, keyed the way gettext keys them.
+ *
+ * Obsolete entries (`#~ msgid`) are excluded because `msgfmt` excludes them: a
+ * gutted catalog keeps every line and loses every translation, so a line count
+ * would report it as healthy. The header is excluded by being the one entry whose
+ * msgid is empty and uncontextualised.
+ *
+ * Continuation lines are CONCATENATED rather than counted, which is what makes a
+ * POT comparable with a catalog at all: the same string is wrapped differently
+ * depending on `--no-wrap` and on how long the surrounding lines were, and only
+ * the joined value is stable. `msgctxt` joins its msgid through gettext's own
+ * `\u0004` separator, so two entries that differ only in context stay two.
+ */
+export declare function activeMsgids(text: string): Set<string>;
+/**
+ * Entries a PO/POT file still USES — the size of {@link activeMsgids}, and the
+ * same measurement, so the number and the set can never disagree.
+ */
+export declare function countActiveEntries(text: string): number;

package/lib/guards.js

@@ -0,0 +1,234 @@
+// What must be true before a POT is written over catalogs people have already
+// translated.
+//
+// THE INCIDENT (JumpLink/Learn6502, 2026-09-03). Its `xgettext` sources included
+// `../learn/dist/**/*.ui`, a build artifact of a SIBLING workspace package.
+// Build `@learn6502/translations` before `@learn6502/learn` and that pattern
+// matches nothing — the whole `ui` group silently ceases to exist. `xgettext`
+// happily extracted the rest, `msgcat` wrote a POT 902 lines shorter, and
+// `autoUpdatePo` then ran `msgmerge --update` over all 16 catalogs, which moved
+// every entry the POT had lost into `#~` obsolete comments: ~1573 lines per
+// language, every MDX-derived tutorial string among them. `msgfmt` ignores `#~`,
+// so those translations were gone. Exit code 0, no warning. It was caught by
+// reading the diff before committing; in CI, or on a machine with a stale
+// `dist/`, it would have landed.
+//
+// The build-order dependency is real and implicit — extraction reads an artifact
+// another package produces and nothing declares that edge — so the fix cannot be
+// "order the build correctly". It has to be that the mistake FAILS.
+//
+// The decisions live here, apart from the I/O that feeds them, so they can be
+// tested without gettext installed and without a filesystem.
+/** Base class so the plugin can rethrow a guard verbatim instead of wrapping it. */
+export class GettextGuardError extends Error {
+}
+/** A `sources` pattern matched nothing, and was not declared optional. */
+export class EmptySourcePatternError extends GettextGuardError {
+    patterns;
+    constructor(message, 
+    /** The patterns that matched no files, verbatim as configured. */
+    patterns) {
+        super(message);
+        this.patterns = patterns;
+        this.name = 'EmptySourcePatternError';
+    }
+}
+/** `msgmerge` would obsolete more of the catalogs than this build allows. */
+export class CatalogShrinkError extends GettextGuardError {
+    lostEntries;
+    catalogEntries;
+    constructor(message, 
+    /** Entries the reference catalog holds that the new POT no longer carries. */
+    lostEntries, catalogEntries) {
+        super(message);
+        this.lostEntries = lostEntries;
+        this.catalogEntries = catalogEntries;
+        this.name = 'CatalogShrinkError';
+    }
+}
+/** A `maxCatalogEntryLoss` that is not a fraction — the guard cannot act on it. */
+export class InvalidEntryLossError extends GettextGuardError {
+    constructor(message) {
+        super(message);
+        this.name = 'InvalidEntryLossError';
+    }
+}
+/**
+ * Fraction of its entries a catalog set may lose in one extraction.
+ *
+ * Why a RATIO: an absolute count cannot be right for both a twelve-string dialog
+ * and a nine-hundred-string tutorial. Why a THIRD: the two populations this has
+ * to separate are far apart. Ordinary churn between two runs of the same build is
+ * a handful of strings — single-digit percent of any real catalog — while the
+ * failure above drops a whole source group at once. A third sits in the empty
+ * space between them. Half, the other candidate, is worse: a project with two
+ * source groups of similar size loses one of them at ~50% and slips under.
+ *
+ * A deliberate rewrite that really does delete more says so with
+ * `maxCatalogEntryLoss`, which is the point of it being an option.
+ */
+export const DEFAULT_MAX_CATALOG_ENTRY_LOSS = 1 / 3;
+/**
+ * Fails unless every source pattern resolved to at least one file.
+ *
+ * FAILING IS THE DEFAULT ON PURPOSE. A pattern that matches nothing is almost
+ * always a build-order or path mistake, and the cost of being wrong is
+ * asymmetric: a false failure costs one build, a missed one costs every
+ * translation the group carried. A project that genuinely has an optional group
+ * names those patterns in `optionalSources` — per pattern, never a blanket
+ * boolean, so the guard stays armed for every other entry.
+ */
+export function assertEverySourcePatternMatched(matches, context) {
+    const optional = new Set(context.optionalSources ?? []);
+    const empty = matches
+        .filter((match) => match.fileCount === 0 && !optional.has(match.pattern))
+        .map((match) => match.pattern);
+    if (empty.length === 0) {
+        return;
+    }
+    const list = empty.map((pattern) => `  - ${pattern}`).join('\n');
+    // The negated patterns are named whenever there are any: a pattern whose every
+    // hit was excluded looks exactly like a wrong path, and the two have different
+    // fixes.
+    const excluded = context.ignore?.length
+        ? `After excluding ${context.ignore.map((pattern) => `!${pattern}`).join(', ')}.\n`
+        : '';
+    throw new EmptySourcePatternError(`[${context.pluginName}] ${empty.length === 1 ? 'a source pattern' : `${empty.length} source patterns`} matched no files:\n` +
+        `${list}\n` +
+        `Resolved relative to ${context.cwd}.\n` +
+        excluded +
+        'Nothing was extracted. Extracting anyway writes a POT without those strings, and with ' +
+        'autoUpdatePo that prunes the same strings out of every catalog. Usual cause: the pattern ' +
+        'points at a build artifact of another package that has not been built yet.\n' +
+        "If the group really is optional, list the pattern verbatim in the plugin's `optionalSources`.", empty);
+}
+/**
+ * Reads `maxCatalogEntryLoss`, which has to be a FRACTION.
+ *
+ * Validated separately, and before the catalogs are looked at, because the two
+ * ways of getting it wrong both end in silence. `50` — the option read as a
+ * percentage — is `<= 50` for every possible ratio, so the guard passes
+ * everything and reports nothing; `NaN` fails every comparison, so the guard
+ * fires on a build that lost nothing and gets raised out of the way. Neither
+ * would ever be traced back to the option.
+ */
+export function resolveMaxEntryLoss(value, pluginName) {
+    if (value === undefined) {
+        return DEFAULT_MAX_CATALOG_ENTRY_LOSS;
+    }
+    if (typeof value !== 'number' || !Number.isFinite(value) || value < 0 || value > 1) {
+        throw new InvalidEntryLossError(`[${pluginName}] maxCatalogEntryLoss must be a fraction between 0 and 1, and is ${String(value)}. ` +
+            'It is a fraction, not a percentage: a third is 0.33, half is 0.5, and 1 turns the check off.');
+    }
+    return value;
+}
+/**
+ * Fails when merging the freshly written POT would obsolete more of the catalogs
+ * than `maxEntryLoss` allows.
+ *
+ * What is measured is the SET of msgids the POT no longer carries, not how much
+ * shorter it got. `msgmerge` matches by msgid, so an equally long POT whose
+ * strings have changed obsoletes just as much as a short one — and measured on
+ * gettext 0.26, a msgid that only gained a space is fuzzy-matched, keeps its
+ * translation, and is then excluded from the `.mo` by `msgfmt` anyway. A count
+ * cannot see that; a set difference is the quantity `msgmerge` acts on.
+ *
+ * The reference is the LARGEST catalog rather than each one in turn: `msgmerge`
+ * gives every catalog the POT's msgid set (measured — a 1-entry and a 2-entry
+ * catalog both came back with the POT's 3), so the biggest one is the best
+ * evidence of what the project had before this run. Comparing per language would
+ * let one catalog that a previous bad run already gutted excuse gutting the rest.
+ */
+export function assertCatalogsSurviveMerge(args) {
+    const limit = resolveMaxEntryLoss(args.maxEntryLoss, args.pluginName);
+    const reference = args.catalogs.reduce((largest, candidate) => (largest && largest.msgids.size >= candidate.msgids.size ? largest : candidate), undefined);
+    // No catalogs yet, or an empty one: there is nothing a merge can destroy, and
+    // a ratio against zero is not a number.
+    if (!reference || reference.msgids.size === 0) {
+        return;
+    }
+    const held = reference.msgids.size;
+    let lost = 0;
+    for (const msgid of reference.msgids) {
+        if (!args.potMsgids.has(msgid)) {
+            lost++;
+        }
+    }
+    if (lost === 0 || lost / held <= limit) {
+        return;
+    }
+    const percent = (value) => `${Math.round(value * 100)}%`;
+    throw new CatalogShrinkError(`[${args.pluginName}] refusing to update the catalogs: ${args.potFile} no longer carries ${lost} of the ` +
+        `${held} entries ${reference.language}.po holds. That is a loss of ${percent(lost / held)}, over the ` +
+        `${percent(limit)} this build allows, across ${args.catalogs.length} ` +
+        `${args.catalogs.length === 1 ? 'catalog' : 'catalogs'}.\n` +
+        'msgmerge would move every missing entry into `#~` comments, which msgfmt ignores — the ' +
+        'translations would be gone. Usual cause: a source group went missing from this run.\n' +
+        "If the strings really were deleted, raise the plugin's `maxCatalogEntryLoss` for the run that does it.", lost, held);
+}
+/**
+ * The msgids a PO/POT file still USES, keyed the way gettext keys them.
+ *
+ * Obsolete entries (`#~ msgid`) are excluded because `msgfmt` excludes them: a
+ * gutted catalog keeps every line and loses every translation, so a line count
+ * would report it as healthy. The header is excluded by being the one entry whose
+ * msgid is empty and uncontextualised.
+ *
+ * Continuation lines are CONCATENATED rather than counted, which is what makes a
+ * POT comparable with a catalog at all: the same string is wrapped differently
+ * depending on `--no-wrap` and on how long the surrounding lines were, and only
+ * the joined value is stable. `msgctxt` joins its msgid through gettext's own
+ * `\u0004` separator, so two entries that differ only in context stay two.
+ */
+export function activeMsgids(text) {
+    const msgids = new Set();
+    let reading;
+    let pieces = [];
+    let context;
+    const finish = () => {
+        if (reading === 'msgctxt') {
+            context = pieces.join('');
+        }
+        else if (reading === 'msgid') {
+            const msgid = pieces.join('');
+            if (msgid !== '' || context !== undefined) {
+                msgids.add(context === undefined ? msgid : `${context}\u0004${msgid}`);
+            }
+            context = undefined;
+        }
+        reading = undefined;
+        pieces = [];
+    };
+    for (const line of text.split('\n')) {
+        const opener = /^(msgctxt|msgid)[ \t]/.exec(line);
+        if (opener) {
+            finish();
+            reading = opener[1];
+            pieces = [literal(line)];
+            continue;
+        }
+        // A bare string literal continues whatever keyword opened the entry. An
+        // obsolete entry's own continuations are prefixed `#~ `, so they never
+        // reach here and never re-open one either.
+        if (reading && /^[ \t]*"/.test(line)) {
+            pieces.push(literal(line));
+            continue;
+        }
+        finish();
+    }
+    finish();
+    return msgids;
+}
+/** The quoted payload of a PO line, unescaped no further than both files are. */
+function literal(line) {
+    const first = line.indexOf('"');
+    const last = line.lastIndexOf('"');
+    return first < 0 || last <= first ? '' : line.slice(first + 1, last);
+}
+/**
+ * Entries a PO/POT file still USES — the size of {@link activeMsgids}, and the
+ * same measurement, so the number and the set can never disagree.
+ */
+export function countActiveEntries(text) {
+    return activeMsgids(text).size;
+}

package/lib/index.d.ts

@@ -1,3 +1,4 @@
+export { CatalogShrinkError, EmptySourcePatternError, GettextGuardError, InvalidEntryLossError } from './guards.js';
 export { gettextPlugin } from './gettext.js';
 export { msgfmtPlugin } from './msgfmt.js';
 export { xgettextPlugin } from './xgettext.js';

package/lib/index.js

@@ -1,3 +1,4 @@
+export { CatalogShrinkError, EmptySourcePatternError, GettextGuardError, InvalidEntryLossError } from './guards.js';
 export { gettextPlugin } from './gettext.js';
 export { msgfmtPlugin } from './msgfmt.js';
 export { xgettextPlugin } from './xgettext.js';

package/lib/types.d.ts

@@ -3,8 +3,29 @@
  * Used to extract translatable strings from source files
  */
 export interface XGettextPluginOptions {
-    /** Glob patterns for source files to extract strings from */
+    /**
+     * Glob patterns for source files to extract strings from.
+     *
+     * fast-glob syntax: a leading `!` excludes, and applies to the whole set
+     * rather than standing on its own as a group.
+     */
     sources: string[];
+    /**
+     * Entries of `sources` that are allowed to match no files.
+     *
+     * Every other pattern that matches nothing fails the build — see
+     * `assertEverySourcePatternMatched`. Listed per pattern rather than as one
+     * boolean so declaring one group optional does not disarm the rest.
+     */
+    optionalSources?: string[];
+    /**
+     * Fraction of its entries the catalog set may lose in one run before
+     * `autoUpdatePo` refuses to merge. Defaults to 1/3; `1` disables the check.
+     *
+     * A FRACTION, not a percentage — `50` would wave every possible loss through,
+     * so anything outside 0…1 is refused rather than obeyed.
+     */
+    maxCatalogEntryLoss?: number;
     /** Output path for the POT template file */
     output: string;
     /** The gettext domain name, defaults to 'messages' */

package/lib/xgettext.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 import fs from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import glob from 'fast-glob';
+import { activeMsgids, assertCatalogsSurviveMerge, assertEverySourcePatternMatched, EmptySourcePatternError, GettextGuardError, } from './guards.js';
 import { checkDependencies, ensureDirectory, processFilename } from './utils.js';
 // Add GLib preset constants
 // From https://github.com/mesonbuild/meson/blob/467da051c859ba3112803b035e317bddadd756ef/mesonbuild/modules/i18n.py
@@ -74,23 +75,67 @@ export function xgettextPlugin(options) {
         name: pluginName,
         async buildStart() {
             await checkDependencies('xgettext', pluginName, options.verbose ?? false);
-            const files = await glob(options.sources);
+            const files = await resolveSources(options, pluginName);
             await extractStrings(files, options, pluginName);
         },
         configureServer(server) {
             server.watcher.add(options.sources);
             server.watcher.on('change', async (file) => {
-                if (options.sources.some((pattern) => file.match(pattern))) {
-                    if (options.verbose) {
-                        console.log(`[${pluginName}] Source file changed: ${file}, re-running extraction`);
-                    }
-                    const files = await glob(options.sources);
-                    await extractStrings(files, options, pluginName);
+                // Membership in the RESOLVED set, not `file.match(pattern)`: that
+                // compiled the glob as a regular expression, and any `**` in it is
+                // `Nothing to repeat`, so every change event threw a SyntaxError
+                // before it could decide anything. Re-extraction in `vite dev` had
+                // never run, which is also why the guards below had never been
+                // reached from here.
+                const files = await resolveSources(options, pluginName);
+                const changed = path.resolve(file);
+                if (!files.some((candidate) => path.resolve(candidate) === changed)) {
+                    return;
+                }
+                if (options.verbose) {
+                    console.log(`[${pluginName}] Source file changed: ${file}, re-running extraction`);
                 }
+                await extractStrings(files, options, pluginName);
             });
         },
     };
 }
+/**
+ * Resolves `sources` to files, globbing each POSITIVE pattern separately under
+ * the negative ones.
+ *
+ * The union `glob(options.sources)` used to return cannot say WHICH pattern came
+ * up empty, and in the incident `guards.ts` records only one of several did — so
+ * the union was non-empty and there was nothing left to notice. Per-pattern is
+ * what makes the guard able to name the offender.
+ *
+ * The negative patterns have to stay a property of the WHOLE set, though.
+ * fast-glob reads a leading `!` as an ignore filter over the other patterns, and
+ * returns nothing at all for a list that is only negations — so globbing one on
+ * its own yields zero files, which the guard would report as a missing source
+ * group, and silencing that with `optionalSources` would then extract the very
+ * files the `!` was there to keep out. They are lifted into `ignore` instead,
+ * which is what fast-glob does with them internally.
+ */
+async function resolveSources(options, pluginName) {
+    const included = options.sources.filter((pattern) => !pattern.startsWith('!'));
+    const ignore = options.sources.filter((pattern) => pattern.startsWith('!')).map((pattern) => pattern.slice(1));
+    const perPattern = await Promise.all(included.map((pattern) => glob(pattern, { ignore })));
+    assertEverySourcePatternMatched(included.map((pattern, index) => ({ pattern, fileCount: perPattern[index].length })), { pluginName, cwd: process.cwd(), optionalSources: options.optionalSources, ignore });
+    // Two patterns may legitimately reach the same file; xgettext would then scan
+    // it twice and msgcat would have to fold the duplicate back out.
+    const files = [...new Set(perPattern.flat())];
+    // The one hole the per-pattern guard leaves: no positive pattern at all, or
+    // every pattern declared optional and every one empty. Extraction would run
+    // over nothing, write an empty POT and prune every catalog against it — the
+    // incident again, reached by a different route.
+    if (files.length === 0) {
+        throw new EmptySourcePatternError(`[${pluginName}] no source file to extract from: ${options.sources.length} pattern(s) resolved to ` +
+            `nothing under ${process.cwd()}.\n` +
+            'Extracting anyway writes an empty POT, and with autoUpdatePo that empties every catalog.', options.sources);
+    }
+    return files;
+}
 async function generatePotfiles(files, outputDir, pluginName, verbose = false) {
     // Group files by extension
     const fileGroups = new Map();
@@ -107,15 +152,14 @@ async function generatePotfiles(files, outputDir, pluginName, verbose = false) {
     for (const [group, groupFiles] of fileGroups) {
         const potfilePath = path.join(outputDir, `${group}.POTFILES`);
         const content = groupFiles.join('\n');
-        try {
-            await fs.writeFile(potfilePath, content);
-            potFiles.push(potfilePath);
-            if (verbose) {
-                console.log(`[${pluginName}] Generated ${group}.POTFILES with ${groupFiles.length} source files`);
-            }
-        }
-        catch (error) {
-            console.error(`[${pluginName}] Error writing ${group}.POTFILES:`, error);
+        // Deliberately unguarded. A caught write failure used to leave the group
+        // out of `potFiles`, so xgettext never ran for it and the whole group left
+        // the POT — the incident in `guards.ts`, reached without any pattern being
+        // wrong. Nothing here can be recovered from; it has to end the build.
+        await fs.writeFile(potfilePath, content);
+        potFiles.push(potfilePath);
+        if (verbose) {
+            console.log(`[${pluginName}] Generated ${group}.POTFILES with ${groupFiles.length} source files`);
         }
     }
     return potFiles;
@@ -306,48 +350,105 @@ async function extractStrings(files, options, pluginName) {
             }
         }
         if (options.autoUpdatePo) {
+            await assertCatalogsSurviveNextMerge(options, pluginName);
             await updatePoFiles(options.output, pluginName, options.verbose || false, options);
         }
     }
     catch (error) {
+        // A guard's message IS the guard — wrapping it in "Failed to extract
+        // translations: Error: …" buries the instruction that makes it useful.
+        if (error instanceof GettextGuardError) {
+            throw error;
+        }
         throw new Error(`Failed to extract translations: ${error}`);
     }
 }
-async function updatePoFiles(potFile, pluginName, verbose, options) {
+/** The catalogs LINGUAS declares beside a POT. */
+async function listCatalogs(potFile) {
+    const directory = path.dirname(potFile);
+    const linguas = await readTextOrEmpty(path.join(directory, 'LINGUAS'));
+    return linguas
+        .split('\n')
+        .filter(Boolean)
+        .map((language) => ({ language, file: path.join(directory, `${language}.po`) }));
+}
+/**
+ * A file that is not there yet reads as empty rather than as a failure: a project
+ * with no LINGUAS has no translations, and a language named in LINGUAS before its
+ * catalog exists holds no entries. Both are states a first run is legitimately
+ * in, and neither is something a merge can destroy.
+ */
+async function readTextOrEmpty(file) {
     try {
-        const linguasPath = path.join(path.dirname(potFile), 'LINGUAS');
-        const languages = (await fs.readFile(linguasPath, 'utf-8')).split('\n').filter(Boolean);
-        for (const lang of languages) {
-            const poFile = path.join(path.dirname(potFile), `${lang}.po`);
+        return await fs.readFile(file, 'utf-8');
+    }
+    catch (error) {
+        // ONLY "not there yet" reads as empty. A permission or I/O error must not:
+        // an unreadable catalog counted as holding nothing is the guard talking
+        // itself out of firing.
+        if (error?.code === 'ENOENT') {
+            return '';
+        }
+        throw error;
+    }
+}
+/**
+ * Reads what `msgmerge` is about to rewrite and hands the counts to the pure
+ * check.
+ *
+ * Called from `extractStrings` BEFORE `updatePoFiles` and outside that function's
+ * catch — a refusal that became one more `console.error` beside a zero exit code
+ * would be the exact silence this guards against.
+ */
+async function assertCatalogsSurviveNextMerge(options, pluginName) {
+    const catalogs = await listCatalogs(options.output);
+    const sizes = await Promise.all(catalogs.map(async ({ language, file }) => ({
+        language,
+        msgids: activeMsgids(await readTextOrEmpty(file)),
+    })));
+    assertCatalogsSurviveMerge({
+        potMsgids: activeMsgids(await readTextOrEmpty(options.output)),
+        catalogs: sizes,
+        potFile: options.output,
+        pluginName,
+        maxEntryLoss: options.maxCatalogEntryLoss,
+    });
+}
+/**
+ * Merges the POT into every catalog LINGUAS declares.
+ *
+ * Deliberately unguarded, like `generatePotfiles`. A caught error here used to be
+ * one `console.error` beside exit 0 — and by then `msgmerge --update` may already
+ * have rewritten the catalogs it got to, so "an error was printed" and "the
+ * catalogs are intact" were unrelated facts.
+ */
+async function updatePoFiles(potFile, pluginName, verbose, options) {
+    for (const { file: poFile } of await listCatalogs(potFile)) {
+        if (verbose) {
+            console.log(`[${pluginName}] Updating ${poFile}`);
+        }
+        const baseMsgmergeArgs = ['--update', '--backup=none', poFile, potFile];
+        const args = buildCommandArgs(baseMsgmergeArgs, {
+            noLocation: options.noLocation,
+            noWrap: options.noWrap,
+        });
+        const env = { ...process.env };
+        if (options.deterministic) {
+            const epoch = typeof options.sourceDateEpoch === 'number' ? options.sourceDateEpoch : 0;
+            env.SOURCE_DATE_EPOCH = String(epoch);
+        }
+        await execa('msgmerge', args, { env });
+        // Post-process with msgcat to unwrap existing wrapped lines
+        if (options.noWrap) {
+            const tempFile = poFile + '.tmp';
+            const msgcatArgs = ['--width=0', '--no-wrap', '-o', tempFile, poFile];
+            await execa('msgcat', msgcatArgs, { env });
+            await fs.rename(tempFile, poFile);
             if (verbose) {
-                console.log(`[${pluginName}] Updating ${poFile}`);
-            }
-            const baseMsgmergeArgs = ['--update', '--backup=none', poFile, potFile];
-            const args = buildCommandArgs(baseMsgmergeArgs, {
-                noLocation: options.noLocation,
-                noWrap: options.noWrap,
-            });
-            const env = { ...process.env };
-            if (options.deterministic) {
-                const epoch = typeof options.sourceDateEpoch === 'number' ? options.sourceDateEpoch : 0;
-                env.SOURCE_DATE_EPOCH = String(epoch);
-            }
-            await execa('msgmerge', args, { env });
-            // Post-process with msgcat to unwrap existing wrapped lines
-            if (options.noWrap) {
-                const tempFile = poFile + '.tmp';
-                const msgcatArgs = ['--width=0', '--no-wrap', '-o', tempFile, poFile];
-                await execa('msgcat', msgcatArgs, { env });
-                await fs.rename(tempFile, poFile);
-                if (verbose) {
-                    console.log(`[${pluginName}] Unwrapped lines in ${poFile}`);
-                }
+                console.log(`[${pluginName}] Unwrapped lines in ${poFile}`);
             }
         }
     }
-    catch (error) {
-        console.error(`[${pluginName}] Error updating PO files:`, error);
-    }
 }
 /**
  * Formats a date in gettext header format using an epoch (seconds) in UTC timezone

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/vite-plugin-gettext",
-    "version": "0.47.0",
+    "version": "0.48.0",
     "description": "Gettext PO/MO/JSON pipeline for Vite / Rollup / Rolldown — extract via xgettext, compile via msgfmt, JSON for browser targets.",
     "type": "module",
     "main": "lib/index.js",
@@ -16,9 +16,12 @@
         "lib"
     ],
     "scripts": {
-        "clear": "gjsify clear lib tsconfig.tsbuildinfo",
+        "clear": "gjsify clear lib tsconfig.tsbuildinfo test.node.mjs",
         "check": "gjsify tsc --noEmit",
-        "build": "gjsify tsc"
+        "build": "gjsify tsc -p tsconfig.build.json",
+        "build:test:node": "gjsify build src/test.mts --app node --outfile test.node.mjs",
+        "test": "gjsify run build:test:node && gjsify run test:node",
+        "test:node": "node test.node.mjs"
     },
     "repository": {
         "type": "git",
@@ -56,6 +59,8 @@
         }
     },
     "devDependencies": {
+        "@gjsify/cli": "^0.48.0",
+        "@gjsify/unit": "^0.48.0",
         "@types/gettext-parser": "^9.0.0",
         "@types/node": "^25.9.2",
         "typescript": "^6.0.3",