@gjsify/vite-plugin-gettext 0.48.0 → 0.50.0

package/README.md

@@ -34,6 +34,44 @@ Requires `gettext` tools (`msgfmt`, `xgettext`) to be installed on the system.
   fuzzy entries out of the `.mo`. A run that really does replace that many strings raises the
   option.
 
+## One catalog, three namespaces
+
+A catalog is called one thing in the repository and has to be spelled three different ways
+downstream. They disagree, so the `.po` basename is not passed through unchanged:
+
+| Target | Namespace | `zh_Hans.po` | `pt_BR.po` |
+|---|---|---|---|
+| `.mo` directory (`gettextPlugin`, `msgfmtPlugin`) | POSIX locale | `locale/zh_CN/`, `locale/zh_SG/` | `locale/pt_BR/` |
+| JSON file (`po2jsonPlugin`) | Android qualifier | `zh.json` | `pt-BR.json` |
+| the `.po` in the repo | BCP-47-ish (Weblate) | `zh_Hans` | `pt_BR` |
+
+Weblate names simplified Chinese `zh_Hans`, which is BCP-47 and **not** a POSIX locale — glibc
+never probes it, so a catalog compiled under that name ships complete and renders in English for
+every Chinese user while the build exits 0. The compiled catalog is therefore installed under the
+locale directories real users actually resolve, keeping the original name alongside them so
+nothing that already worked stops.
+
+On the JSON side the filename becomes an Android resource qualifier
+(`values-<lang>[-r<REGION>]`), where an underscore is illegal: `pt_BR.json` would yield
+`values-pt_BR`, a directory Android never consults.
+
+**A catalog whose script subtag maps to no known name fails the build**, naming every such
+catalog at once. A build that cannot say where a catalog goes must not quietly put it somewhere —
+"somewhere" is indistinguishable from "correct" until a user of that language complains. Map it
+explicitly with `localeNames`, one catalog at a time, so mapping one language does not disarm the
+check for the rest:
+
+```typescript
+gettextPlugin({
+    poDirectory: 'po',
+    moDirectory: 'dist',
+    localeNames: { az_Arab: ['az_IR'] },
+});
+```
+
+Two catalogs that would land on one output name (a Weblate `zh_Hans.po` beside a hand-made
+`zh_CN.po`) fail the same way, rather than letting one overwrite the other.
+
 ```typescript
 xgettextPlugin({
     sources: ['src/**/*.blp', 'data/**/*.desktop.in', '!src/**/*.generated.blp'],

package/lib/catalog-names.d.ts

@@ -0,0 +1,71 @@
+import { GettextGuardError } from './guards.js';
+/** A catalog name whose script subtag maps to no name we know. */
+export declare class UnmappableCatalogNameError extends GettextGuardError {
+    /** The catalog names that could not be mapped, verbatim as the `.po` is called. */
+    readonly catalogs: readonly string[];
+    constructor(message: string, 
+    /** The catalog names that could not be mapped, verbatim as the `.po` is called. */
+    catalogs: readonly string[]);
+}
+/** Two catalogs claim one output name; one would overwrite the other. */
+export declare class CollidingCatalogNameError extends GettextGuardError {
+    /** The name claimed twice, and the catalogs claiming it. */
+    readonly claimed: string;
+    readonly catalogs: readonly string[];
+    constructor(message: string, 
+    /** The name claimed twice, and the catalogs claiming it. */
+    claimed: string, catalogs: readonly string[]);
+}
+/** How one catalog is spelled in each namespace that consumes it. */
+export interface CatalogNames {
+    /** The `.po` basename, verbatim. What an error message names. */
+    catalog: string;
+    /** `.mo` locale directories, in write order. */
+    posix: readonly string[];
+    /** JSON basename — a BCP-47 tag `@nativescript/localize` can qualify. */
+    bcp47: string;
+}
+/** Which generated namespace a lookup is for, so errors can say what broke. */
+export type CatalogNamespace = 'posix' | 'bcp47';
+/**
+ * How one catalog is spelled everywhere, or `undefined` when its script subtag
+ * has no name in the namespace asked for.
+ *
+ * The ORIGINAL name is always kept among the POSIX directories. It is additive —
+ * no deployment that already found a catalog can stop finding it — and it keeps
+ * the compiled tree greppable against the catalogs it came from. It is never the
+ * only entry, because on its own it is precisely what nothing probes. The JSON
+ * side gets no such alias: a filename is one name, and a second copy under the
+ * dead spelling is what left two generations in the tree to begin with.
+ */
+export declare function catalogNames(catalog: string, overrides?: Readonly<Record<string, readonly string[]>>): CatalogNames | undefined;
+/**
+ * The POSIX directories alone.
+ *
+ * A script with a POSIX mapping but no safe Android qualifier (`sr_Latn`) is
+ * answerable here and not by {@link catalogNames}: the `.mo` side knows exactly
+ * where it goes. Splitting the lookup this way is what lets the gettext plugin
+ * stay correct for catalogs the JSON plugin has to refuse.
+ */
+export declare function posixLocaleDirectories(catalog: string, overrides?: Readonly<Record<string, readonly string[]>>): readonly string[] | undefined;
+/**
+ * Plans every catalog for ONE namespace, and fails if any cannot be spelled.
+ *
+ * FAILING IS THE DEFAULT ON PURPOSE, on the same asymmetry the source-pattern
+ * guard is built on: a false failure costs one build and one line of config, a
+ * missed one ships a whole language that silently renders in English — which is
+ * what `zh_Hans` did, undetected, for as long as the catalog existed. A build
+ * that cannot say where a catalog goes must not quietly put it somewhere,
+ * because "somewhere" is indistinguishable from "correct" until a user of that
+ * language complains.
+ *
+ * Every unmappable name is named in ONE error rather than the first aborting, so
+ * a project adopting several Weblate languages fixes them in a single pass
+ * instead of a build-fix-build loop.
+ */
+export declare function planCatalogNames(catalogs: readonly string[], context: {
+    pluginName: string;
+    namespace: CatalogNamespace;
+    /** Per-catalog override, e.g. `{ az_Arab: ['az_IR'] }`. */
+    localeNames?: Readonly<Record<string, readonly string[]>>;
+}): CatalogNames[];

package/lib/catalog-names.js

@@ -0,0 +1,328 @@
+// One catalog, three namespaces — and the table that keeps them apart.
+//
+// A catalog is called ONE thing in the repository and has to be spelled three
+// different ways downstream. They disagree on the same catalog, so passing the
+// name through unchanged is wrong in two of the three places.
+//
+//   | target                       | namespace         | zh_Hans | pt_BR |
+//   |------------------------------|-------------------|---------|-------|
+//   | gettext `.mo` directory      | POSIX locale      | zh_CN   | pt_BR |
+//   | Android resources (via JSON) | Android qualifier | zh      | pt-BR |
+//   | Weblate / the `.po` in repo  | BCP-47-ish        | zh_Hans | pt_BR |
+//
+// THE INCIDENT, POSIX SIDE (JumpLink/Learn6502#182, measured 2026-09-11).
+// Catalogs are maintained on Weblate, which names simplified Chinese `zh_Hans`.
+// The compiler used the `.po` basename verbatim as the locale directory, so the
+// catalog landed in `locale/zh_Hans/LC_MESSAGES/`. `zh_Hans` is BCP-47, not a
+// POSIX locale name, and glibc never probes it. Measured against the real
+// shipped `.mo` with the glibc `gettext` CLI as the oracle:
+//
+//     LANGUAGE=zh_Hans -> 黄色      (a selector no real user has)
+//     LANGUAGE=zh_CN   -> Yellow    <- what an actual user in China gets
+//     LANGUAGE=zh_TW   -> Yellow
+//     LANGUAGE=de      -> Gelb      (control: ordinary names were always fine)
+//
+// A complete Chinese catalog shipped and every Chinese user saw English. The
+// build exited 0; 14 of the 15 catalogs were fine, which is why nobody looked.
+//
+// THE INCIDENT, ANDROID SIDE (JumpLink/Learn6502#179). `po2json` wrote the same
+// basename as the JSON filename, and `@nativescript/localize` turns that
+// filename straight into an Android resource directory (`hooks/converter.js`:
+// values-${language.replace(/^(.+?)-(.+?)$/, '$1-r$2')}). Running that
+// transformation over the names in play:
+//
+//     de       -> values-de        ok
+//     pt-BR    -> values-pt-rBR    ok      <- the name the repo tracks
+//     pt_BR    -> values-pt_BR     BROKEN  <- what po2json wrote
+//     zh       -> values-zh        ok      <- the name the repo tracks
+//     zh_Hans  -> values-zh_Hans   BROKEN  <- what po2json wrote
+//     zh-Hans  -> values-zh-rHans  BROKEN  (a script subtag needs values-b+zh+Hans)
+//
+// An underscore is not legal in an Android resource qualifier, so those are
+// directories Android never consults. Both generations sat in the tree at once:
+// the tracked, correct `pt-BR.json`/`zh.json` and the generated, dead
+// `pt_BR.json`/`zh_Hans.json` beside them.
+//
+// NOT MEASURED: that Android then loads the resulting directory. The qualifier
+// rule is derived from the hook's source and the transformation above was
+// executed, but no emulator or device ran. The POSIX side, by contrast, was
+// measured end to end against glibc.
+//
+// Why this cannot be fixed by renaming the `.po`: the name comes from Weblate,
+// it is correct there, and the two downstream namespaces would still disagree
+// with each other. The mapping has to happen where each artifact is written.
+//
+// The mapping is DATA in one table read by both plugins, rather than logic in
+// each — two copies of this reasoning would drift, and the drifted one wins
+// silently.
+//
+// The decisions live here, apart from the I/O that acts on them, so they can be
+// tested without gettext installed and without a filesystem.
+import { GettextGuardError } from './guards.js';
+/** A catalog name whose script subtag maps to no name we know. */
+export class UnmappableCatalogNameError extends GettextGuardError {
+    catalogs;
+    constructor(message, 
+    /** The catalog names that could not be mapped, verbatim as the `.po` is called. */
+    catalogs) {
+        super(message);
+        this.catalogs = catalogs;
+        this.name = 'UnmappableCatalogNameError';
+    }
+}
+/** Two catalogs claim one output name; one would overwrite the other. */
+export class CollidingCatalogNameError extends GettextGuardError {
+    claimed;
+    catalogs;
+    constructor(message, 
+    /** The name claimed twice, and the catalogs claiming it. */
+    claimed, catalogs) {
+        super(message);
+        this.claimed = claimed;
+        this.catalogs = catalogs;
+        this.name = 'CollidingCatalogNameError';
+    }
+}
+/**
+ * Script subtag → the names that serve it.
+ *
+ * The POSIX column was MEASURED on glibc 2.42 / gettext 0.26 by installing a
+ * catalog under the target alone and asking the `gettext` CLI which selectors
+ * reached it. Two rules came out of that and explain the shapes below:
+ *
+ *   - a bare `<lang>` directory is reached by `<lang>_<TERRITORY>` users
+ *     (`sr` answered `sr_RS`), so a script that is simply the language's normal
+ *     one needs no territory at all;
+ *   - `<lang>@<modifier>` is reached by `<lang>_<TERRITORY>@<modifier>` users,
+ *     while `<lang>_<TERRITORY>@<modifier>` is reached ONLY by itself, so the
+ *     modifier forms are deliberately written WITHOUT a territory. This is the
+ *     one place where the narrower spelling is the tempting one and is wrong.
+ *
+ * Chinese needs its territories spelled out: `zh_CN` is NOT reached by a
+ * `zh_SG` user (measured), and the broad `zh` IS reached by `zh_TW` — so a
+ * simplified catalog installed as `zh` would serve traditional users simplified
+ * text. The territories are explicit precisely to avoid that.
+ *
+ * A POSIX target absent from the building host is still written: the catalog is
+ * compiled once and installed on machines whose locale set this build cannot
+ * see (`zh_MO` is absent on Fedora 44 and present elsewhere). A directory
+ * nobody probes costs a few KB; a missing one costs the language.
+ *
+ * The table is deliberately NOT exhaustive. An unknown script is REPORTED
+ * rather than guessed — a guessed territory is the same silent-wrong-name
+ * failure this module exists to end.
+ */
+const SCRIPT_NAMES = {
+    // Chinese: the script IS the axis users select on, and both halves ship.
+    // `zh` for simplified is the name Learn6502 already tracks and yields
+    // `values-zh`; traditional takes the territory form, `values-zh-rTW`.
+    zh_Hans: { posix: ['zh_CN', 'zh_SG'], bcp47: 'zh' },
+    zh_Hant: { posix: ['zh_TW', 'zh_HK', 'zh_MO'], bcp47: 'zh-TW' },
+    // Scripts glibc expresses as an @modifier. None has a safe Android
+    // qualifier: the distinction they carry is exactly the one the hook drops.
+    sr_Latn: { posix: ['sr@latin'] },
+    uz_Cyrl: { posix: ['uz@cyrillic'] },
+    be_Latn: { posix: ['be@latin'] },
+    // Scripts that are the language's ordinary one: the bare language covers it
+    // in both namespaces, because there is no distinction left to express.
+    sr_Cyrl: { posix: ['sr'], bcp47: 'sr' },
+    uz_Latn: { posix: ['uz'], bcp47: 'uz' },
+    az_Latn: { posix: ['az'], bcp47: 'az' },
+    bs_Latn: { posix: ['bs'], bcp47: 'bs' },
+    mn_Cyrl: { posix: ['mn'], bcp47: 'mn' },
+    tg_Cyrl: { posix: ['tg'], bcp47: 'tg' },
+    kk_Cyrl: { posix: ['kk'], bcp47: 'kk' },
+    ky_Cyrl: { posix: ['ky'], bcp47: 'ky' },
+    // Scripts glibc separates by territory, which Android can qualify too.
+    pa_Guru: { posix: ['pa_IN'], bcp47: 'pa-IN' },
+    pa_Arab: { posix: ['pa_PK'], bcp47: 'pa-PK' },
+};
+/**
+ * `language`, optional `Script`, optional `TERRITORY` of a catalog name.
+ *
+ * Matched after hyphens are folded to underscores, so one pattern reads both the
+ * BCP-47 spelling Weblate writes (`pt-BR`, `zh-Hans`) and the POSIX one. A name
+ * already carrying an `@modifier` is handled before this: it is POSIX by
+ * construction and needs no mapping.
+ */
+const CATALOG_NAME = /^([a-z]{2,3})(?:_([A-Z][a-z]{3}))?(?:_([A-Z]{2}|\d{3}))?$/;
+/** The script mapping for a catalog name, if it carries a script subtag at all. */
+function scriptMappingFor(normalized) {
+    const parsed = CATALOG_NAME.exec(normalized);
+    if (!parsed?.[2] || parsed[3]) {
+        return undefined;
+    }
+    return SCRIPT_NAMES[`${parsed[1]}_${parsed[2]}`];
+}
+/**
+ * How one catalog is spelled everywhere, or `undefined` when its script subtag
+ * has no name in the namespace asked for.
+ *
+ * The ORIGINAL name is always kept among the POSIX directories. It is additive —
+ * no deployment that already found a catalog can stop finding it — and it keeps
+ * the compiled tree greppable against the catalogs it came from. It is never the
+ * only entry, because on its own it is precisely what nothing probes. The JSON
+ * side gets no such alias: a filename is one name, and a second copy under the
+ * dead spelling is what left two generations in the tree to begin with.
+ */
+export function catalogNames(catalog, overrides) {
+    // A configured override answers for the name as written AND as normalised,
+    // so a project need not know which spelling this module reasons about.
+    const normalized = catalog.replace(/-/g, '_');
+    const override = overrides?.[catalog] ?? overrides?.[normalized];
+    if (override && override.length > 0) {
+        return {
+            catalog,
+            posix: dedupe([...override, catalog]),
+            bcp47: override[0].split('@')[0].replace(/_/g, '-'),
+        };
+    }
+    // A name carrying an @modifier is POSIX by construction — the modifier is
+    // the thing BCP-47 has no spelling for, so nothing but a hand-written POSIX
+    // name can have produced it. Android cannot express it either; the bare
+    // language is the honest remainder.
+    if (normalized.includes('@')) {
+        return { catalog, posix: [normalized], bcp47: normalized.split('@')[0].replace(/_/g, '-') };
+    }
+    const parsed = CATALOG_NAME.exec(normalized);
+    if (!parsed) {
+        // Not a shape this module recognises. Passed through rather than
+        // reported: gettext's own fallback still reaches a plain `<lang>`
+        // prefix, and reporting every unusual name would make the guard noise
+        // instead of signal. Only a SCRIPT subtag is a measured silent failure.
+        return { catalog, posix: [normalized], bcp47: normalized.replace(/_/g, '-') };
+    }
+    const [, language, script, territory] = parsed;
+    if (!script) {
+        // `de`, `pt_BR`, `zh_CN` — already exactly what glibc probes. The only
+        // work a hyphenated `pt-BR` needed was the underscore; Android needs the
+        // hyphen back, which is why the two columns differ here for free.
+        return { catalog, posix: dedupe([normalized, catalog]), bcp47: normalized.replace(/_/g, '-') };
+    }
+    // An explicit territory beside the script settles it without the table:
+    // `zh_Hans_CN` is `zh_CN`, whatever the script says.
+    if (territory) {
+        return {
+            catalog,
+            posix: dedupe([`${language}_${territory}`, catalog]),
+            bcp47: `${language}-${territory}`,
+        };
+    }
+    const mapped = SCRIPT_NAMES[`${language}_${script}`];
+    if (!mapped?.bcp47) {
+        return undefined;
+    }
+    return { catalog, posix: dedupe([...mapped.posix, catalog]), bcp47: mapped.bcp47 };
+}
+/**
+ * The POSIX directories alone.
+ *
+ * A script with a POSIX mapping but no safe Android qualifier (`sr_Latn`) is
+ * answerable here and not by {@link catalogNames}: the `.mo` side knows exactly
+ * where it goes. Splitting the lookup this way is what lets the gettext plugin
+ * stay correct for catalogs the JSON plugin has to refuse.
+ */
+export function posixLocaleDirectories(catalog, overrides) {
+    const both = catalogNames(catalog, overrides);
+    if (both) {
+        return both.posix;
+    }
+    const mapped = scriptMappingFor(catalog.replace(/-/g, '_'));
+    return mapped ? dedupe([...mapped.posix, catalog]) : undefined;
+}
+/**
+ * Plans every catalog for ONE namespace, and fails if any cannot be spelled.
+ *
+ * FAILING IS THE DEFAULT ON PURPOSE, on the same asymmetry the source-pattern
+ * guard is built on: a false failure costs one build and one line of config, a
+ * missed one ships a whole language that silently renders in English — which is
+ * what `zh_Hans` did, undetected, for as long as the catalog existed. A build
+ * that cannot say where a catalog goes must not quietly put it somewhere,
+ * because "somewhere" is indistinguishable from "correct" until a user of that
+ * language complains.
+ *
+ * Every unmappable name is named in ONE error rather than the first aborting, so
+ * a project adopting several Weblate languages fixes them in a single pass
+ * instead of a build-fix-build loop.
+ */
+export function planCatalogNames(catalogs, context) {
+    const plans = [];
+    const unmappable = [];
+    for (const catalog of catalogs) {
+        if (context.namespace === 'posix') {
+            const posix = posixLocaleDirectories(catalog, context.localeNames);
+            if (!posix) {
+                unmappable.push(catalog);
+                continue;
+            }
+            plans.push({ catalog, posix, bcp47: '' });
+            continue;
+        }
+        const names = catalogNames(catalog, context.localeNames);
+        if (!names) {
+            unmappable.push(catalog);
+            continue;
+        }
+        plans.push(names);
+    }
+    if (unmappable.length > 0) {
+        throw new UnmappableCatalogNameError(unmappableMessage(unmappable, context), unmappable);
+    }
+    assertNoCollision(plans, context);
+    return plans;
+}
+function unmappableMessage(unmappable, context) {
+    const list = unmappable.map((name) => `  - ${name}.po`).join('\n');
+    const subject = unmappable.length === 1 ? 'a catalog carries' : `${unmappable.length} catalogs carry`;
+    if (context.namespace === 'posix') {
+        return (`[${context.pluginName}] ${subject} a script subtag with no known POSIX locale:\n` +
+            `${list}\n` +
+            'Compiling it under that name produces a directory glibc never probes, so the language ships ' +
+            'complete and renders in English — the build would exit 0 and nothing would look wrong.\n' +
+            "Map it explicitly in the plugin's `localeNames`, e.g. `{ 'az_Arab': ['az_IR'] }`, using the " +
+            'name `locale -a` lists on the target system.');
+    }
+    return (`[${context.pluginName}] ${subject} a script subtag that has no Android resource qualifier:\n` +
+        `${list}\n` +
+        'A qualifier is built as `values-<lang>[-r<REGION>]` and cannot express a script, so the generated ' +
+        'directory would be one Android never consults — and the build would exit 0.\n' +
+        "Map it explicitly in the plugin's `localeNames`, e.g. `{ 'sr_Latn': ['sr'] }`, choosing the " +
+        'language or region tag the app should serve it as.');
+}
+/**
+ * Fails when two catalogs claim the same output name.
+ *
+ * Reachable as soon as a project keeps both spellings of one language — a
+ * `zh_Hans.po` from Weblate beside a hand-made `zh_CN.po` both resolve to
+ * `zh_CN`. Without this, whichever is written last wins by iteration order, the
+ * other's translations are simply absent, and the build still exits 0. That is
+ * the same shape as the bug this module fixes, so it is guarded here rather than
+ * left to be discovered the same way.
+ */
+function assertNoCollision(plans, context) {
+    const claimedBy = new Map();
+    for (const plan of plans) {
+        const claims = context.namespace === 'posix' ? plan.posix : [plan.bcp47];
+        for (const claim of claims) {
+            const claimants = claimedBy.get(claim);
+            if (claimants) {
+                claimants.push(plan.catalog);
+            }
+            else {
+                claimedBy.set(claim, [plan.catalog]);
+            }
+        }
+    }
+    for (const [claimed, catalogs] of claimedBy) {
+        if (catalogs.length > 1) {
+            const where = context.namespace === 'posix' ? `locale/${claimed}/` : `${claimed}.json`;
+            throw new CollidingCatalogNameError(`[${context.pluginName}] ${catalogs.map((name) => `${name}.po`).join(' and ')} both compile to ` +
+                `${where}. One would overwrite the other and the build would still exit 0.\n` +
+                "Keep one catalog per language, or pin them apart with the plugin's `localeNames`.", claimed, catalogs);
+        }
+    }
+}
+/** First occurrence wins, so the mapped name stays ahead of the original. */
+function dedupe(values) {
+    return [...new Set(values)];
+}

package/lib/gettext.d.ts

@@ -4,6 +4,10 @@ import type { GettextPluginOptions } from './types.js';
  * Creates a Vite plugin that compiles PO translation files to binary MO format
  * The MO files are placed in the standard gettext directory structure:
  * {moDirectory}/locale/{lang}/LC_MESSAGES/messages.mo
+ *
+ * The directory is the catalog's POSIX locale name, which is NOT always the
+ * `.po` basename — a Weblate `zh_Hans.po` is installed as `zh_CN`, because
+ * `zh_Hans` is a name glibc never probes. See `catalog-names.ts`.
  * @param options Configuration options for the plugin
  * @returns A Vite plugin that handles PO compilation
  */

package/lib/gettext.js

@@ -1,15 +1,21 @@
 import { execa } from 'execa';
 import path from 'node:path';
+import { GettextGuardError } from './guards.js';
+import { planCatalogNames } from './catalog-names.js';
 import { checkDependencies, findAvailableLanguages, generateLinguasFile, ensureDirectory } from './utils.js';
 /**
  * Creates a Vite plugin that compiles PO translation files to binary MO format
  * The MO files are placed in the standard gettext directory structure:
  * {moDirectory}/locale/{lang}/LC_MESSAGES/messages.mo
+ *
+ * The directory is the catalog's POSIX locale name, which is NOT always the
+ * `.po` basename — a Weblate `zh_Hans.po` is installed as `zh_CN`, because
+ * `zh_Hans` is a name glibc never probes. See `catalog-names.ts`.
  * @param options Configuration options for the plugin
  * @returns A Vite plugin that handles PO compilation
  */
 export function gettextPlugin(options) {
-    const { poDirectory, moDirectory, filename = 'messages.mo', verbose = false } = options;
+    const { poDirectory, moDirectory, filename = 'messages.mo', verbose = false, localeNames } = options;
     const pluginName = 'vite-plugin-gettext';
     async function compileMoFiles() {
         try {
@@ -35,20 +41,31 @@ export function gettextPlugin(options) {
             }
             // Generate LINGUAS file
             await generateLinguasFile(languages, poDirectory, verbose);
+            // Resolve every catalog's locale directories BEFORE compiling any of
+            // them, so a name nobody can place stops the build instead of
+            // leaving a half-written tree that looks complete.
+            const plans = planCatalogNames(languages, { pluginName, namespace: 'posix', localeNames });
             // Create MO directory
             await ensureDirectory(path.join(moDirectory, 'locale'));
-            for (const lang of languages) {
-                const poFile = path.join(poDirectory, `${lang}.po`);
-                const moPath = path.join(moDirectory, 'locale', lang, 'LC_MESSAGES');
-                const moFile = path.join(moPath, filename);
-                await ensureDirectory(moPath);
-                if (verbose) {
-                    console.log(`[${pluginName}] Compiling ${poFile} to ${moFile}`);
+            for (const plan of plans) {
+                const poFile = path.join(poDirectory, `${plan.catalog}.po`);
+                for (const localeDir of plan.posix) {
+                    const moPath = path.join(moDirectory, 'locale', localeDir, 'LC_MESSAGES');
+                    const moFile = path.join(moPath, filename);
+                    await ensureDirectory(moPath);
+                    if (verbose) {
+                        console.log(`[${pluginName}] Compiling ${poFile} to ${moFile}`);
+                    }
+                    await execa('msgfmt', ['--output-file=' + moFile, poFile]);
                 }
-                await execa('msgfmt', ['--output-file=' + moFile, poFile]);
             }
         }
         catch (error) {
+            // A guard's message IS the guard — wrapping it in "Failed to compile
+            // MO files: Error: …" buries the instruction that makes it useful.
+            if (error instanceof GettextGuardError) {
+                throw error;
+            }
             throw new Error(`Failed to compile MO files: ${error}`);
         }
     }

package/lib/index.d.ts

@@ -1,7 +1,9 @@
 export { CatalogShrinkError, EmptySourcePatternError, GettextGuardError, InvalidEntryLossError } from './guards.js';
+export { catalogNames, CollidingCatalogNameError, planCatalogNames, posixLocaleDirectories, UnmappableCatalogNameError, } from './catalog-names.js';
+export type { CatalogNames, CatalogNamespace } from './catalog-names.js';
 export { gettextPlugin } from './gettext.js';
 export { msgfmtPlugin } from './msgfmt.js';
 export { xgettextPlugin } from './xgettext.js';
 export { po2jsonPlugin } from './po2json.js';
-export type { GettextPluginOptions, MsgfmtPluginOptions, MsgfmtFormat, XGettextPluginOptions } from './types.js';
+export type { GettextPluginOptions, GettextPo2JsonPluginOptions, MsgfmtPluginOptions, MsgfmtFormat, XGettextPluginOptions, } from './types.js';
 export * from './utils.js';

package/lib/index.js

@@ -1,4 +1,5 @@
 export { CatalogShrinkError, EmptySourcePatternError, GettextGuardError, InvalidEntryLossError } from './guards.js';
+export { catalogNames, CollidingCatalogNameError, planCatalogNames, posixLocaleDirectories, UnmappableCatalogNameError, } from './catalog-names.js';
 export { gettextPlugin } from './gettext.js';
 export { msgfmtPlugin } from './msgfmt.js';
 export { xgettextPlugin } from './xgettext.js';

package/lib/msgfmt.js

@@ -1,6 +1,8 @@
 import { execa } from 'execa';
 import path from 'node:path';
 import fs from 'node:fs/promises';
+import { GettextGuardError } from './guards.js';
+import { planCatalogNames } from './catalog-names.js';
 import { checkDependencies, findAvailableLanguages, ensureDirectory } from './utils.js';
 /**
  * Remove XML comments from a file content
@@ -61,7 +63,7 @@ function getOutputExtension(format) {
  * @returns A Vite plugin that handles PO compilation
  */
 export function msgfmtPlugin(options) {
-    const { poDirectory, outputDirectory, domain = 'messages', format = 'mo', templateFile, verbose = false, msgfmtOptions = [], useLocaleStructure = true, removeComments = true, } = options;
+    const { poDirectory, outputDirectory, domain = 'messages', format = 'mo', templateFile, verbose = false, msgfmtOptions = [], useLocaleStructure = true, removeComments = true, localeNames, } = options;
     const pluginName = 'vite-plugin-msgfmt';
     async function compilePoFiles() {
         try {
@@ -125,37 +127,44 @@ export function msgfmtPlugin(options) {
                     }
                     return;
                 }
+                // Only the gettext locale structure is looked up by glibc, so
+                // only it needs POSIX names. The flat `<outputDirectory>/<lang>`
+                // layout is read by whatever the project points at it, and
+                // renaming there would break a consumer to fix nobody.
+                const usesLocaleLookup = useLocaleStructure && format === 'mo';
+                const plans = usesLocaleLookup
+                    ? planCatalogNames(languages, { pluginName, namespace: 'posix', localeNames })
+                    : languages.map((catalog) => ({ catalog, posix: [catalog], bcp47: '' }));
                 // Process each language individually for other formats
-                for (const lang of languages) {
-                    const poFile = path.join(poDirectory, `${lang}.po`);
-                    let outputPath;
-                    let outputFile;
-                    if (useLocaleStructure && format === 'mo') {
-                        // Use standard gettext locale structure
-                        outputPath = path.join(outputDirectory, 'locale', lang, 'LC_MESSAGES');
-                        outputFile = path.join(outputPath, options.filename || `${domain}${getOutputExtension(format)}`);
-                    }
-                    else {
-                        // Use simple language-based structure
-                        outputPath = path.join(outputDirectory, lang);
-                        outputFile = path.join(outputPath, options.filename || `${domain}${getOutputExtension(format)}`);
-                    }
-                    // Create the directory structure
-                    await ensureDirectory(outputPath);
-                    if (verbose) {
-                        console.log(`[${pluginName}] Compiling ${poFile} to ${outputFile}`);
-                    }
-                    // Build arguments for individual processing
-                    const baseArgs = ['--output-file=' + outputFile, `--${format}`, poFile];
-                    const args = buildMsgfmtArgs(baseArgs, { msgfmtOptions });
-                    if (verbose) {
-                        console.log(`[${pluginName}] Running msgfmt with: ${args.join(' ')}`);
+                for (const plan of plans) {
+                    const poFile = path.join(poDirectory, `${plan.catalog}.po`);
+                    for (const name of plan.posix) {
+                        const outputPath = usesLocaleLookup
+                            ? path.join(outputDirectory, 'locale', name, 'LC_MESSAGES')
+                            : path.join(outputDirectory, name);
+                        const outputFile = path.join(outputPath, options.filename || `${domain}${getOutputExtension(format)}`);
+                        // Create the directory structure
+                        await ensureDirectory(outputPath);
+                        if (verbose) {
+                            console.log(`[${pluginName}] Compiling ${poFile} to ${outputFile}`);
+                        }
+                        // Build arguments for individual processing
+                        const baseArgs = ['--output-file=' + outputFile, `--${format}`, poFile];
+                        const args = buildMsgfmtArgs(baseArgs, { msgfmtOptions });
+                        if (verbose) {
+                            console.log(`[${pluginName}] Running msgfmt with: ${args.join(' ')}`);
+                        }
+                        await execa('msgfmt', args);
                     }
-                    await execa('msgfmt', args);
                 }
             }
         }
         catch (error) {
+            // A guard's message IS the guard — wrapping it buries the
+            // instruction that makes it useful.
+            if (error instanceof GettextGuardError) {
+                throw error;
+            }
             throw new Error(`Failed to compile files: ${error}`);
         }
     }

package/lib/po2json.js

@@ -1,6 +1,8 @@
 import path from 'node:path';
 import fs from 'node:fs/promises';
 import * as gettextParser from 'gettext-parser';
+import { GettextGuardError } from './guards.js';
+import { planCatalogNames } from './catalog-names.js';
 import { findAvailableLanguages, ensureDirectory } from './utils.js';
 /**
  * Simplifies the gettext-parser output to a clean key-value object
@@ -82,7 +84,7 @@ async function createDefaultLanguageJson(jsonDirectory, allTranslations, default
  * @returns A Vite plugin that handles PO to JSON conversion
  */
 export function po2jsonPlugin(options) {
-    const { poDirectory, jsonDirectory, defaultLanguage = 'en', verbose = false, additionalTranslations = {}, } = options;
+    const { poDirectory, jsonDirectory, defaultLanguage = 'en', verbose = false, additionalTranslations = {}, localeNames, } = options;
     const pluginName = 'vite-plugin-gettext-po2json';
     async function convertPoToJson() {
         try {
@@ -110,8 +112,12 @@ export function po2jsonPlugin(options) {
             await ensureDirectory(jsonDirectory);
             // Collection of all translations to create the default language file
             const allTranslations = {};
+            // The JSON filename is the ANDROID namespace, not the catalog name:
+            // `@nativescript/localize` turns it straight into a resource
+            // qualifier, where an underscore is illegal. See `catalog-names.ts`.
+            const plans = planCatalogNames(languages, { pluginName, namespace: 'bcp47', localeNames });
             // Skip the default language if it exists in the list
-            const nonDefaultLanguages = languages.filter((lang) => lang !== defaultLanguage);
+            const nonDefaultPlans = plans.filter((plan) => plan.catalog !== defaultLanguage);
             // Handle default language if it exists in the list
             if (languages.includes(defaultLanguage)) {
                 const poFile = path.join(poDirectory, `${defaultLanguage}.po`);
@@ -134,9 +140,10 @@ export function po2jsonPlugin(options) {
                 await fs.writeFile(jsonFile, JSON.stringify(finalTranslations, null, 2));
             }
             // Add additional translations for all languages
-            for (const lang of nonDefaultLanguages) {
+            for (const plan of nonDefaultPlans) {
+                const lang = plan.catalog;
                 const poFile = path.join(poDirectory, `${lang}.po`);
-                const jsonFile = path.join(jsonDirectory, `${lang}.json`);
+                const jsonFile = path.join(jsonDirectory, `${plan.bcp47}.json`);
                 if (verbose) {
                     console.log(`[${pluginName}] Converting ${poFile} to ${jsonFile}`);
                 }
@@ -167,6 +174,11 @@ export function po2jsonPlugin(options) {
             await createDefaultLanguageJson(jsonDirectory, allTranslations, defaultLanguage, verbose, pluginName, additionalTranslations);
         }
         catch (error) {
+            // A guard's message IS the guard — wrapping it buries the
+            // instruction that makes it useful.
+            if (error instanceof GettextGuardError) {
+                throw error;
+            }
             throw new Error(`Failed to convert PO files to JSON: ${error}`);
         }
     }

package/lib/types.d.ts

@@ -76,6 +76,14 @@ export interface GettextPluginOptions {
     filename?: string;
     /** Enable verbose logging */
     verbose?: boolean;
+    /**
+     * Output names for catalogs whose name carries a script subtag the built-in
+     * table does not know, e.g. `{ az_Arab: ['az_IR'] }`.
+     *
+     * Per catalog rather than one blanket switch, so mapping one language does
+     * not disarm the check for the rest.
+     */
+    localeNames?: Record<string, readonly string[]>;
 }
 /**
  * Output format types for msgfmt
@@ -106,6 +114,12 @@ export interface MsgfmtPluginOptions {
     useLocaleStructure?: boolean;
     /** Whether to remove XML comments from output files, defaults to true */
     removeComments?: boolean;
+    /**
+     * Locale directories for catalogs whose name carries a script subtag the
+     * built-in table does not know. Applies only to the gettext locale
+     * structure, which is the layout glibc looks up.
+     */
+    localeNames?: Record<string, readonly string[]>;
 }
 export interface PluginOptions {
     pluginName: string;
@@ -137,4 +151,12 @@ export interface GettextPo2JsonPluginOptions {
      * The English text will be translated for non-default languages if translations exist
      */
     additionalTranslations?: Record<string, string>;
+    /**
+     * JSON basenames for catalogs whose name carries a script subtag with no
+     * Android resource qualifier, e.g. `{ sr_Latn: ['sr'] }`.
+     *
+     * The first entry is used, with `_` folded to `-`: a qualifier is
+     * `values-<lang>[-r<REGION>]` and cannot carry a script.
+     */
+    localeNames?: Record<string, readonly string[]>;
 }

package/lib/utils.d.ts

@@ -3,7 +3,7 @@
  * @param command The command to check (msgfmt, xgettext, etc.)
  * @param pluginName Name of the plugin for logging
  * @param verbose Enable verbose logging
- * @throws Error if the command is not found
+ * @throws Error if the command is not found, or is there and refused to run
  */
 export declare function checkDependencies(command: string, pluginName: string, verbose: boolean): Promise<void>;
 /**

package/lib/utils.js

@@ -6,7 +6,7 @@ import fs from 'node:fs/promises';
  * @param command The command to check (msgfmt, xgettext, etc.)
  * @param pluginName Name of the plugin for logging
  * @param verbose Enable verbose logging
- * @throws Error if the command is not found
+ * @throws Error if the command is not found, or is there and refused to run
  */
 export async function checkDependencies(command, pluginName, verbose) {
     try {
@@ -15,7 +15,21 @@ export async function checkDependencies(command, pluginName, verbose) {
             console.log(`[${pluginName}] Found ${command}`);
         }
     }
-    catch (_error) {
+    catch (error) {
+        // ABSENT and BROKEN are different answers, and this used to give the
+        // first one to both — `catch (_error)`, install hint, every time. A
+        // gettext that is installed but cannot run (a missing libintl after a
+        // partial upgrade, a noexec mount, the wrong arch under emulation) then
+        // tells the reader to install what they have already got, and its own
+        // stderr — the part that says which library is missing — is dropped.
+        //
+        // The same distinction `@gjsify/vite-plugin-blueprint`'s
+        // `resolve-compiler.ts` was written for, after a "not found" for a
+        // compiler that WAS there cost a day.
+        if (error.code !== 'ENOENT') {
+            const detail = error.stderr || error.message;
+            throw new Error(`${command} is installed but failed to run:\n${detail}`);
+        }
         throw new Error(`${command} not found. Please install gettext:\n` +
             '  Ubuntu/Debian: sudo apt-get install gettext\n' +
             '  Fedora: sudo dnf install gettext\n' +
@@ -33,7 +47,23 @@ export async function checkDependencies(command, pluginName, verbose) {
 export async function findAvailableLanguages(poDirectory, pluginName, verbose) {
     try {
         const files = await fs.readdir(poDirectory);
-        const languages = files.filter((file) => file.endsWith('.po')).map((file) => path.basename(file, '.po'));
+        const languages = files
+            .filter((file) => file.endsWith('.po'))
+            .map((file) => path.basename(file, '.po'))
+            // SORTED AT THE SOURCE, so every consumer is deterministic at once —
+            // the LINGUAS file, the compile order, and the locale-directory plan.
+            // `fs.readdir` returns filesystem order, which Node explicitly does
+            // not specify: on ext4 a small directory reads back in CREATION
+            // order, so a language that was removed and re-added moves to the end
+            // and LINGUAS is rewritten on a tree nobody touched
+            // (JumpLink/Learn6502#179).
+            //
+            // No comparator ON PURPOSE. The default is UTF-16 code-unit order —
+            // total, and identical on every host. `localeCompare` would order by
+            // the BUILDER's locale, which makes committed output depend on who
+            // built it: the same host-dependent-artifact bug in a new place.
+            // Locale names are ASCII, so code-unit order is also byte order.
+            .sort();
         if (verbose) {
             console.log(`[${pluginName}] Found languages: ${languages.join(', ')}`);
         }
@@ -54,7 +84,12 @@ export async function findAvailableLanguages(poDirectory, pluginName, verbose) {
  */
 export async function generateLinguasFile(languages, poDirectory, verbose = false) {
     const linguasPath = path.join(poDirectory, 'LINGUAS');
-    const content = languages.join('\n');
+    // Trailing newline: a POSIX text file ends with one. Without it git reports
+    // "" on every regeneration, and any tool that
+    // appends to the list silently joins its first entry onto the last language.
+    // Sorted here as well as in `findAvailableLanguages` so a caller that
+    // assembles the list itself still gets a stable file.
+    const content = `${[...languages].sort().join('\n')}\n`;
     try {
         await fs.writeFile(linguasPath, content);
         if (verbose) {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/vite-plugin-gettext",
-    "version": "0.48.0",
+    "version": "0.50.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",
@@ -59,8 +59,8 @@
         }
     },
     "devDependencies": {
-        "@gjsify/cli": "^0.48.0",
-        "@gjsify/unit": "^0.48.0",
+        "@gjsify/cli": "^0.50.0",
+        "@gjsify/unit": "^0.50.0",
         "@types/gettext-parser": "^9.0.0",
         "@types/node": "^25.9.2",
         "typescript": "^6.0.3",