@menapo/vi18n 0.0.0-stage → 0.1.0

package/dist/library-D5CWvTQs.js

@@ -0,0 +1,1882 @@
+import { a as diagnosticError, o as isDiagnosticError } from "./types-D3QGM8XO.js";
+import { r as validateTranslation } from "./validate-BxpupdAf.js";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { hash, randomBytes } from "node:crypto";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { mkdir, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
+//#region src/core/extract/dependencies.ts
+/**
+* `extraction.dependencies` (PLAN §4.5, §5.24; INTERNALS §2.5.7): published
+* packages the app opts in. Each name resolves from the config root the way
+* Node resolves a package directory (`node_modules/<name>` in the root or a
+* directory above it), by realpath, which is what Vite hands the plugin under
+* pnpm's links. Their files are extracted and rewritten like the app's,
+* except the package's own `node_modules`, tests and declarations, and their
+* catalog references read `<name>/<path in the package>`, the same on every
+* machine and package manager and across the package's versions.
+*/
+/** As `files.ts` has it (which imports this module). */
+const toPosix = (path) => sep === "/" ? path : path.replaceAll("\\", "/");
+const resolved = /* @__PURE__ */ new WeakMap();
+/** Directories and names never extracted inside a package. */
+const SKIPPED_DIRS = /* @__PURE__ */ new Set([
+	"node_modules",
+	"__tests__",
+	".git"
+]);
+const TEST_FILE = /\.(?:test|spec)\.[^/]*$/;
+const DECLARATION = /\.d\.[cm]?ts$/;
+/**
+* Every `extraction.dependencies` package, resolved once per config. A
+* name that does not resolve is a `config-invalid` error: its strings would
+* otherwise ship untranslated and unreported.
+*/
+function dependenciesOf(config) {
+	let list = resolved.get(config.extraction);
+	if (list !== void 0) return list;
+	list = [];
+	for (const name of config.extraction.dependencies) {
+		const dir = packageDir(config.root, name);
+		if (dir === null) throw diagnosticError({
+			code: "config-invalid",
+			severity: "error",
+			message: `extraction.dependencies: ${name} is not installed (no node_modules/${name} from ${toPosix(config.root)} up); add it to the app's dependencies`
+		});
+		list.push({
+			name,
+			dir,
+			messages: messagesFile(dir)
+		});
+	}
+	resolved.set(config.extraction, list);
+	return list;
+}
+/** The package directory as Node finds it from `root`, by realpath; null when not installed. */
+function packageDir(root, name) {
+	let dir = resolve(root);
+	for (;;) {
+		const candidate = join(dir, "node_modules", name);
+		if (existsSync(join(candidate, "package.json"))) return toPosix(realpathSync(candidate)).replace(/\/+$/, "");
+		const parent = dirname(dir);
+		if (parent === dir) return null;
+		dir = parent;
+	}
+}
+/** `package.json#vi18n.messages`, absolute; null without one (or an unreadable manifest). */
+function messagesFile(dir) {
+	try {
+		const path = JSON.parse(readFileSync(join(dir, "package.json"), "utf8")).vi18n?.messages;
+		return typeof path === "string" && path !== "" ? toPosix(resolve(dir, path)) : null;
+	} catch {
+		return null;
+	}
+}
+/**
+* The opted-in package `file` belongs to, when vi18n extracts it: under the
+* package directory (a `?query` or `\0` prefix ignored), with a scanned
+* extension, outside the package's `node_modules` and tests, not a
+* declaration file.
+*/
+function dependencyOf(file, config) {
+	if (config.extraction.dependencies.length === 0) return null;
+	let path = file.startsWith("\0") ? file.slice(1) : file;
+	const query = path.indexOf("?");
+	if (query !== -1) path = path.slice(0, query);
+	path = toPosix(path);
+	for (const dependency of dependenciesOf(config)) {
+		if (!path.startsWith(dependency.dir + "/")) continue;
+		return extracted(path.slice(dependency.dir.length + 1), config) ? dependency : null;
+	}
+	return null;
+}
+function extracted(rel, config) {
+	const segments = rel.split("/");
+	const name = segments[segments.length - 1];
+	if (DECLARATION.test(name) || TEST_FILE.test(name)) return false;
+	if (!config.project.extensions.some((ext) => name.endsWith(ext) && name.length > ext.length)) return false;
+	for (let i = 0; i < segments.length - 1; i++) if (SKIPPED_DIRS.has(segments[i])) return false;
+	return true;
+}
+/** `<name>/<path in the package>` for a file of an opted-in package, else null. */
+function dependencyRef(file, config) {
+	if (config.extraction.dependencies.length === 0) return null;
+	const path = toPosix(file);
+	for (const dependency of dependenciesOf(config)) if (path.startsWith(dependency.dir + "/")) return dependency.name + path.slice(dependency.dir.length);
+	return null;
+}
+/** Every extracted file of the opted-in packages, by realpath, sorted by code unit. */
+async function listDependencyFiles(config) {
+	const out = [];
+	for (const dependency of dependenciesOf(config)) {
+		const walk = async (dir, rel) => {
+			for (const entry of await readdir(dir, { withFileTypes: true })) {
+				const path = rel === "" ? entry.name : rel + "/" + entry.name;
+				if (entry.isDirectory()) {
+					if (!SKIPPED_DIRS.has(entry.name)) await walk(join(dir, entry.name), path);
+				} else if (entry.isFile() && extracted(path, config)) out.push(dependency.dir + "/" + path);
+			}
+		};
+		await walk(dependency.dir, "");
+	}
+	return [...new Set(out)].sort();
+}
+//#endregion
+//#region src/core/catalog/validity.ts
+function sourceMatches(entry, layout, message, codec) {
+	if (layout === "id") return entry.label !== null && entry.label === message.label;
+	const source = entry.source;
+	if (source === null) return false;
+	if (source === message.canonical) return true;
+	return entryCanonical(entry, codec) === message.canonical;
+}
+//#endregion
+//#region src/core/catalog/model.ts
+/**
+* The catalog model shared by every reader, writer and consumer (INTERNALS
+* §2.6.2, §2.6.5, §2.6.7): how an entry is keyed, how entries sort, and when
+* a translation may ship. Formats (`po.ts`, `json.ts`) and files (`io.ts`)
+* build on these; nothing here touches the file system.
+*/
+function emptyCatalog(locale, layout, header) {
+	return {
+		locale,
+		layout,
+		header: {
+			language: locale,
+			idScheme: header.idScheme,
+			sourceLocale: header.sourceLocale,
+			aiModel: null,
+			extra: []
+		},
+		entries: [],
+		obsolete: [],
+		droppedObsolete: 0
+	};
+}
+/**
+* A blank entry with every field present, so sync and tests spell out only
+* what differs and new fields of `CatalogEntry` get a default in one place.
+*/
+function createEntry(fields = {}) {
+	return {
+		manualId: null,
+		foreignContext: null,
+		label: null,
+		source: null,
+		translation: "",
+		state: "untranslated",
+		fuzzy: false,
+		contexts: [],
+		comments: [],
+		refs: [],
+		maxLength: null,
+		flags: [],
+		line: 0,
+		wrapped: false,
+		...fields
+	};
+}
+const canonicals = /* @__PURE__ */ new WeakMap();
+/**
+* `codec.canonicalize(entry.source)`, memoised on the entry (catalog load,
+* the store's index, duplicate resolution and compilation each need it for
+* every entry); null for an entry without a source or whose source is not
+* valid ICU. Canonical forms do not depend on the codec's id length.
+*/
+function entryCanonical(entry, codec) {
+	const source = entry.source;
+	if (source === null) return null;
+	const memo = canonicals.get(entry);
+	if (memo !== void 0 && memo.source === source) return memo.canonical;
+	let canonical;
+	try {
+		canonical = codec.canonicalize(source);
+	} catch (error) {
+		if (!isDiagnosticError(error)) throw error;
+		canonical = null;
+	}
+	canonicals.set(entry, {
+		source,
+		canonical
+	});
+	return canonical;
+}
+/**
+* The key that joins an entry to code. Null for foreign contexts (never
+* matched) and for `"source"`-layout entries whose source does not parse,
+* which consumers report on the source instead.
+*/
+function entryKey(entry, layout, codec) {
+	if (entry.foreignContext !== null) return null;
+	if (entry.manualId !== null) return entry.manualId;
+	if (layout !== "source") return entry.label;
+	const canonical = entryCanonical(entry, codec);
+	return canonical === null ? null : codec.label(canonical);
+}
+/**
+* The `msgctxt` sort field. JSON has no `msgctxt`: its key already holds the
+* manual id, so every JSON entry sorts as if the context were absent.
+*/
+function contextOf(entry, layout) {
+	if (layout === "json") return "";
+	return entry.manualId ?? entry.foreignContext ?? "";
+}
+function msgidOf(entry, layout) {
+	switch (layout) {
+		case "source": return entry.source ?? "";
+		case "id": return entry.label ?? "";
+		case "json": return entry.manualId ?? entry.label ?? "";
+	}
+}
+/** UTF-16 code-unit order: `localeCompare` would differ between machines and ICU versions. */
+function compareText(a, b) {
+	return a < b ? -1 : a > b ? 1 : 0;
+}
+/**
+* Catalog order (INTERNALS §2.6.5): first reference (entries without one
+* last), then `msgctxt` (absent as `""`), then `msgid` or the JSON key, so a
+* route's strings cluster for translators.
+*/
+function compareEntries(a, b, layout) {
+	const refA = a.refs[0];
+	const refB = b.refs[0];
+	if (refA !== refB) {
+		if (refA === void 0) return 1;
+		if (refB === void 0) return -1;
+		const byRef = compareText(refA, refB);
+		if (byRef !== 0) return byRef;
+	}
+	return compareText(contextOf(a, layout), contextOf(b, layout)) || compareText(msgidOf(a, layout), msgidOf(b, layout));
+}
+/** Splits a JSON `context` (notes joined with `"\n"`) back into single-line notes. */
+function splitContexts(context) {
+	if (context === "") return [];
+	return context.split("\n");
+}
+/** Joins single-line notes for a JSON `context`; null when there are none. */
+function joinContexts(contexts) {
+	return contexts.length === 0 ? null : contexts.join("\n");
+}
+/**
+* The one definition of "this entry's translation may ship" (INTERNALS
+* §2.6.7), shared by compilation, AI planning, `check` and `status`. Steps
+* run in contract order and the first failure names the reason.
+* `scheme-mismatch` and `no-entry` are decided by callers.
+*/
+function usableTranslation(entry, layout, message, codec, locale) {
+	if (!sourceMatches(entry, layout, message, codec)) return {
+		ok: false,
+		reason: "source-mismatch",
+		diagnostics: []
+	};
+	if (entry.translation === "") return {
+		ok: false,
+		reason: "untranslated",
+		diagnostics: []
+	};
+	if (entry.fuzzy) return {
+		ok: false,
+		reason: "fuzzy",
+		diagnostics: []
+	};
+	let parsed;
+	try {
+		parsed = codec.parse(entry.translation);
+	} catch (error) {
+		if (!isDiagnosticError(error)) throw error;
+		return {
+			ok: false,
+			reason: "invalid",
+			diagnostics: [withSubject(error.diagnostic, locale, message.id, entry.line)]
+		};
+	}
+	const found = validateTranslation(parsed, codec.parse(message.canonical), {
+		locale,
+		text: entry.translation
+	});
+	let errors = null;
+	for (const diagnostic of found) if (diagnostic.severity === "error") (errors ??= []).push(withSubject(diagnostic, locale, message.id, entry.line));
+	return errors === null ? {
+		ok: true,
+		parsed
+	} : {
+		ok: false,
+		reason: "invalid",
+		diagnostics: errors
+	};
+}
+/**
+* ICU diagnostics locate problems inside the message text; for a catalog the
+* useful position is the entry's line, and the locale and id say which entry.
+*/
+function withSubject(diagnostic, locale, id, line) {
+	const located = {
+		...diagnostic,
+		locale: diagnostic.locale ?? locale,
+		id: diagnostic.id ?? id
+	};
+	delete located.line;
+	delete located.column;
+	if (line > 0) located.line = line;
+	return located;
+}
+//#endregion
+//#region src/core/catalog/json.ts
+const CATALOG_SCHEMA_URL = "https://unpkg.com/@menapo/vi18n/schemas/catalog.json";
+/** Top-level keys the reader maps onto the header; anything else is preserved in `extra`. */
+const OWNED_KEYS = /* @__PURE__ */ new Set([
+	"$schema",
+	"locale",
+	"sourceLocale",
+	"idScheme",
+	"aiModel",
+	"messages"
+]);
+/** Per-message fields with a model field; anything else is preserved in `extra`. */
+const MESSAGE_FIELDS = /* @__PURE__ */ new Set([
+	"context",
+	"fuzzy",
+	"maxLength",
+	"flags",
+	"refs",
+	"state",
+	"source",
+	"translation"
+]);
+const STATES = /* @__PURE__ */ new Set([
+	"untranslated",
+	"ai",
+	"translated"
+]);
+function skipBlank(text, i) {
+	while (i < text.length) {
+		const code = text.charCodeAt(i);
+		if (code !== 32 && code !== 10 && code !== 13 && code !== 9) break;
+		i++;
+	}
+	return i;
+}
+/** Index just past the string starting at `i` (which is `"`). */
+function skipString(text, i) {
+	i++;
+	while (i < text.length) {
+		const code = text.charCodeAt(i);
+		if (code === 92) i += 2;
+		else if (code === 34) return i + 1;
+		else i++;
+	}
+	return i;
+}
+/** Index just past the value starting at `i`. The text is known to be valid JSON. */
+function skipValue(text, i) {
+	const code = text.charCodeAt(i);
+	if (code === 34) return skipString(text, i);
+	if (code === 123 || code === 91) {
+		let depth = 0;
+		while (i < text.length) {
+			const c = text.charCodeAt(i);
+			if (c === 34) {
+				i = skipString(text, i);
+				continue;
+			}
+			if (c === 123 || c === 91) depth++;
+			else if (c === 125 || c === 93) {
+				depth--;
+				if (depth === 0) return i + 1;
+			}
+			i++;
+		}
+		return i;
+	}
+	while (i < text.length) {
+		const c = text.charCodeAt(i);
+		if (c === 44 || c === 125 || c === 93 || c === 32 || c === 10 || c === 13 || c === 9) break;
+		i++;
+	}
+	return i;
+}
+/**
+* The members of the top-level `messages` object in text order, duplicates
+* included. Null when there is no `messages` object.
+*/
+function scanMessages(text) {
+	let line = 1;
+	let counted = 0;
+	const lineAt = (offset) => {
+		for (let i = counted; i < offset; i++) if (text.charCodeAt(i) === 10) line++;
+		counted = offset;
+		return line;
+	};
+	let i = skipBlank(text, text.charCodeAt(0) === 65279 ? 1 : 0);
+	if (text.charCodeAt(i) !== 123) return null;
+	i = skipBlank(text, i + 1);
+	while (i < text.length && text.charCodeAt(i) === 34) {
+		const keyEnd = skipString(text, i);
+		const key = JSON.parse(text.slice(i, keyEnd));
+		i = skipBlank(text, keyEnd);
+		i = skipBlank(text, i + 1);
+		const valueEnd = skipValue(text, i);
+		if (key === "messages" && text.charCodeAt(i) === 123) {
+			const members = [];
+			let j = skipBlank(text, i + 1);
+			while (j < valueEnd && text.charCodeAt(j) === 34) {
+				const memberKeyEnd = skipString(text, j);
+				const memberLine = lineAt(j);
+				const memberKey = JSON.parse(text.slice(j, memberKeyEnd));
+				j = skipBlank(text, memberKeyEnd);
+				j = skipBlank(text, j + 1);
+				const end = skipValue(text, j);
+				members.push({
+					key: memberKey,
+					line: memberLine,
+					start: j,
+					end
+				});
+				j = skipBlank(text, end);
+				if (text.charCodeAt(j) === 44) j = skipBlank(text, j + 1);
+			}
+			return members;
+		}
+		i = skipBlank(text, valueEnd);
+		if (text.charCodeAt(i) === 44) i = skipBlank(text, i + 1);
+	}
+	return null;
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isStringArray(value) {
+	return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+function sortedUnique$1(values) {
+	return [...new Set(values)].sort((a, b) => a < b ? -1 : a > b ? 1 : 0);
+}
+/** Line and column of a `JSON.parse` error, when V8 names a position. */
+function errorPosition(text, error) {
+	const match = /position (\d+)/.exec(error instanceof Error ? error.message : "");
+	if (match === null) return {};
+	const offset = Number(match[1]);
+	let line = 1;
+	let lineStart = 0;
+	for (let i = 0; i < offset && i < text.length; i++) if (text.charCodeAt(i) === 10) {
+		line++;
+		lineStart = i + 1;
+	}
+	return {
+		line,
+		column: offset - lineStart + 1
+	};
+}
+function readEntry(key, value, line, isSourceLocale) {
+	if (!isRecord(value)) return { error: `message ${JSON.stringify(key)} must be an object` };
+	const { context, fuzzy, maxLength, flags, refs, state, source, translation } = value;
+	if (context !== void 0 && typeof context !== "string") return { error: `${key}: context must be a string` };
+	if (fuzzy !== void 0 && typeof fuzzy !== "boolean") return { error: `${key}: fuzzy must be true or absent` };
+	if (maxLength !== void 0 && !(Number.isInteger(maxLength) && maxLength > 0)) return { error: `${key}: maxLength must be a positive integer` };
+	if (flags !== void 0 && !isStringArray(flags)) return { error: `${key}: flags must be an array of strings` };
+	if (refs !== void 0 && !isStringArray(refs)) return { error: `${key}: refs must be an array of strings` };
+	if (state !== void 0 && (typeof state !== "string" || !STATES.has(state))) return { error: `${key}: state must be "untranslated", "ai" or "translated"` };
+	if (source !== void 0 && source !== null && typeof source !== "string") return { error: `${key}: source must be a string` };
+	if (translation !== void 0 && typeof translation !== "string") return { error: `${key}: translation must be a string` };
+	const text = isSourceLocale ? "" : translation ?? "";
+	const entryState = text === "" ? "untranslated" : state === "ai" ? "ai" : "translated";
+	let extra;
+	for (const field of Object.keys(value)) if (!MESSAGE_FIELDS.has(field)) Object.defineProperty(extra ??= {}, field, {
+		value: value[field],
+		enumerable: true,
+		writable: true,
+		configurable: true
+	});
+	const manual = key.includes(".");
+	const entry = {
+		manualId: manual ? key : null,
+		foreignContext: null,
+		label: manual ? null : key,
+		source: typeof source === "string" ? source : null,
+		translation: text,
+		state: entryState,
+		fuzzy: fuzzy === true,
+		contexts: typeof context === "string" ? splitContexts(context) : [],
+		comments: [],
+		refs: refs === void 0 ? [] : sortedUnique$1(refs),
+		maxLength: maxLength === void 0 ? null : maxLength,
+		flags: flags === void 0 ? [] : [...new Set(flags)].map((name) => ({
+			name,
+			line: "#,"
+		})),
+		line,
+		wrapped: false
+	};
+	if (extra !== void 0) entry.extra = extra;
+	return { entry };
+}
+function parseJsonCatalog(text, options) {
+	const { locale, isSourceLocale } = options;
+	const diagnostics = [];
+	const header = {
+		language: locale,
+		idScheme: null,
+		sourceLocale: null,
+		aiModel: null,
+		extra: []
+	};
+	const catalog = {
+		locale,
+		layout: "json",
+		header,
+		entries: [],
+		obsolete: [],
+		droppedObsolete: 0
+	};
+	const fail = (message, line) => {
+		const diagnostic = {
+			code: "catalog-parse",
+			severity: "error",
+			message
+		};
+		if (line !== void 0) diagnostic.line = line;
+		diagnostics.push(diagnostic);
+	};
+	let root;
+	try {
+		root = JSON.parse(text.charCodeAt(0) === 65279 ? text.slice(1) : text);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		diagnostics.push({
+			code: "catalog-parse",
+			severity: "error",
+			message,
+			...errorPosition(text, error)
+		});
+		return {
+			catalog,
+			diagnostics
+		};
+	}
+	if (!isRecord(root)) {
+		fail("a JSON catalog must be an object", 1);
+		return {
+			catalog,
+			diagnostics
+		};
+	}
+	for (const [key, value] of Object.entries(root)) switch (key) {
+		case "$schema":
+		case "messages": break;
+		case "locale":
+			if (typeof value === "string" && value !== "") header.language = value;
+			else fail("locale must be a string");
+			break;
+		case "sourceLocale":
+		case "idScheme":
+		case "aiModel":
+			if (typeof value === "string") header[key] = value;
+			else if (value !== null) fail(`${key} must be a string`);
+			break;
+		default: if (!OWNED_KEYS.has(key)) header.extra.push([key, value]);
+	}
+	const messages = root.messages;
+	if (messages === void 0) return {
+		catalog,
+		diagnostics
+	};
+	if (!isRecord(messages)) {
+		fail("messages must be an object");
+		return {
+			catalog,
+			diagnostics
+		};
+	}
+	const members = scanMessages(text) ?? [];
+	const seen = /* @__PURE__ */ new Set();
+	let duplicates = null;
+	for (const member of members) if (seen.has(member.key)) (duplicates ??= /* @__PURE__ */ new Set()).add(member.key);
+	else seen.add(member.key);
+	for (const member of members) {
+		const value = duplicates !== null && duplicates.has(member.key) ? JSON.parse(text.slice(member.start, member.end)) : messages[member.key];
+		const read = readEntry(member.key, value, member.line, isSourceLocale);
+		if ("error" in read) fail(read.error, member.line);
+		else catalog.entries.push(read.entry);
+	}
+	return {
+		catalog,
+		diagnostics
+	};
+}
+function isPrimitive(value) {
+	return value === null || typeof value !== "object";
+}
+/**
+* `JSON.stringify(value, null, 2)` except that arrays of primitives stay on
+* one line (`"refs": ["a", "b"]`), as in the documented catalog shape.
+*/
+function stringify(value, indent) {
+	if (Array.isArray(value)) {
+		if (value.length === 0) return "[]";
+		if (value.every(isPrimitive)) return `[${value.map((item) => JSON.stringify(item) ?? "null").join(", ")}]`;
+		const inner = `${indent}  `;
+		return `[\n${value.map((item) => inner + stringify(item, inner)).join(",\n")}\n${indent}]`;
+	}
+	if (isRecord(value)) {
+		const keys = Object.keys(value).filter((key) => value[key] !== void 0);
+		if (keys.length === 0) return "{}";
+		const inner = `${indent}  `;
+		return `{\n${keys.map((key) => `${inner}${JSON.stringify(key)}: ${stringify(value[key], inner)}`).join(",\n")}\n${indent}}`;
+	}
+	return JSON.stringify(value) ?? "null";
+}
+function pushMember(lines, indent, key, value) {
+	lines.push(`${indent}${JSON.stringify(key)}: ${stringify(value, indent)}`);
+}
+function entryLines(entry, isSourceLocale) {
+	const indent = "      ";
+	const lines = [];
+	const context = joinContexts(entry.contexts);
+	if (context !== null) pushMember(lines, indent, "context", context);
+	if (entry.fuzzy) pushMember(lines, indent, "fuzzy", true);
+	if (entry.maxLength !== null) pushMember(lines, indent, "maxLength", entry.maxLength);
+	if (entry.flags.length > 0) pushMember(lines, indent, "flags", [...new Set(entry.flags.map((flag) => flag.name))]);
+	if (entry.extra !== void 0) {
+		for (const field of Object.keys(entry.extra).sort()) if (!MESSAGE_FIELDS.has(field) && entry.extra[field] !== void 0) pushMember(lines, indent, field, entry.extra[field]);
+	}
+	if (entry.refs.length > 0) pushMember(lines, indent, "refs", entry.refs);
+	const translation = isSourceLocale ? "" : entry.translation;
+	pushMember(lines, indent, "state", translation === "" ? "untranslated" : entry.state);
+	if (entry.source !== null) pushMember(lines, indent, "source", entry.source);
+	pushMember(lines, indent, "translation", translation);
+	return lines;
+}
+function serializeJsonCatalog(catalog, options) {
+	const { header } = catalog;
+	const top = [];
+	pushMember(top, "  ", "$schema", CATALOG_SCHEMA_URL);
+	pushMember(top, "  ", "locale", header.language);
+	if (header.sourceLocale !== null) pushMember(top, "  ", "sourceLocale", header.sourceLocale);
+	if (header.idScheme !== null) pushMember(top, "  ", "idScheme", header.idScheme);
+	if (header.aiModel !== null) pushMember(top, "  ", "aiModel", header.aiModel);
+	for (const [key, value] of header.extra) if (!OWNED_KEYS.has(key) && value !== void 0) pushMember(top, "  ", key, value);
+	const entries = catalog.entries.slice().sort((a, b) => compareEntries(a, b, "json"));
+	if (entries.length === 0) top.push("  \"messages\": {}");
+	else {
+		const members = entries.map((entry) => {
+			const key = entry.manualId ?? entry.label ?? "";
+			return `    ${JSON.stringify(key)}: {\n${entryLines(entry, options.isSourceLocale).join(",\n")}\n    }`;
+		});
+		top.push(`  "messages": {\n${members.join(",\n")}\n  }`);
+	}
+	return `{\n${top.join(",\n")}\n}\n`;
+}
+//#endregion
+//#region src/core/catalog/plural-forms.ts
+/**
+* The PO `Plural-Forms` header (PLAN §4.4 P1, INTERNALS §2.6.3). vi18n never
+* evaluates it: an ICU message carries its own plural cases, and vi18n never
+* writes gettext plurals. PO editors and `msgfmt -c` expect a real one, so the
+* writer emits the GNU gettext manual's formula for the file's language (the
+* "Plural forms" table of gettext.texi, plus Chinese), and keeps a formula a
+* tool already wrote, so vi18n and Poedit or Weblate never rewrite each
+* other's spelling of the same rule.
+*/
+const ONE = "nplurals=1; plural=0;";
+const NOT_ONE = "nplurals=2; plural=n != 1;";
+const OVER_ONE = "nplurals=2; plural=n>1;";
+const EAST_SLAVIC = "nplurals=3; plural=n%10==1 && n%100!=11 ? 0 : n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2;";
+/** Lower-case BCP 47 tags; a region-specific row wins over its language's. */
+const FORMULAS = {
+	ja: ONE,
+	ko: ONE,
+	th: ONE,
+	vi: ONE,
+	zh: ONE,
+	bg: NOT_ONE,
+	da: NOT_ONE,
+	de: NOT_ONE,
+	el: NOT_ONE,
+	en: NOT_ONE,
+	eo: NOT_ONE,
+	es: NOT_ONE,
+	et: NOT_ONE,
+	fi: NOT_ONE,
+	fo: NOT_ONE,
+	he: NOT_ONE,
+	hu: NOT_ONE,
+	id: NOT_ONE,
+	it: NOT_ONE,
+	nb: NOT_ONE,
+	nl: NOT_ONE,
+	nn: NOT_ONE,
+	no: NOT_ONE,
+	pt: NOT_ONE,
+	sv: NOT_ONE,
+	tr: NOT_ONE,
+	fr: OVER_ONE,
+	"pt-br": OVER_ONE,
+	lv: "nplurals=3; plural=n%10==1 && n%100!=11 ? 0 : n != 0 ? 1 : 2;",
+	ga: "nplurals=3; plural=n==1 ? 0 : n==2 ? 1 : 2;",
+	ro: "nplurals=3; plural=n==1 ? 0 : (n==0 || (n%100 > 0 && n%100 < 20)) ? 1 : 2;",
+	lt: "nplurals=3; plural=n%10==1 && n%100!=11 ? 0 : n%10>=2 && (n%100<10 || n%100>=20) ? 1 : 2;",
+	be: EAST_SLAVIC,
+	hr: EAST_SLAVIC,
+	ru: EAST_SLAVIC,
+	sr: EAST_SLAVIC,
+	uk: EAST_SLAVIC,
+	cs: "nplurals=3; plural=(n==1) ? 0 : (n>=2 && n<=4) ? 1 : 2;",
+	sk: "nplurals=3; plural=(n==1) ? 0 : (n>=2 && n<=4) ? 1 : 2;",
+	pl: "nplurals=3; plural=n==1 ? 0 : n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2;",
+	sl: "nplurals=4; plural=n%100==1 ? 0 : n%100==2 ? 1 : n%100==3 || n%100==4 ? 2 : 3;",
+	ar: "nplurals=6; plural=n==0 ? 0 : n==1 ? 1 : n==2 ? 2 : n%100>=3 && n%100<=10 ? 3 : n%100>=11 ? 4 : 5;"
+};
+/** The formula for a language tag (`pt-BR`, `pt_BR`, `de`), or null when the table has none. */
+function pluralFormsFor(language) {
+	const subtags = language.trim().toLowerCase().replaceAll("_", "-").split("-");
+	for (let length = subtags.length; length > 0; length--) {
+		const formula = FORMULAS[subtags.slice(0, length).join("-")];
+		if (formula !== void 0) return formula;
+	}
+	return null;
+}
+/** `msginit` leaves this placeholder of a POT header until someone fills it in. */
+function isPluralFormsPlaceholder(value) {
+	return /\bINTEGER\b|\bEXPRESSION\b/.test(value) || !/\bnplurals\s*=\s*\d/.test(value);
+}
+//#endregion
+//#region src/core/catalog/po.ts
+/**
+* Header fields the writer always emits itself; keeping them in `extra` would
+* write them twice.
+*/
+const OWNED_HEADER_FIELDS = /* @__PURE__ */ new Set([
+	"language",
+	"content-type",
+	"x-generator",
+	"x-vi18n-id",
+	"x-vi18n-ai-model"
+]);
+const FSI = "⁨";
+const PDI = "⁩";
+/**
+* In the `"id"` layout `#. source:` is the source note, so a context line that
+* would read as one is written with one more leading backslash, which the
+* reader removes. Escaping every backslash run before `source:` keeps the
+* encoding reversible while leaving all other contexts verbatim.
+*/
+const SOURCE_LIKE = /^\\*source:/;
+const ESCAPED_SOURCE_LIKE = /^\\+source:/;
+/** `#:` is line-based; no isolation can carry a line break inside a file name. */
+const LINE_BREAK = /[\n\r]/;
+const NEEDS_ESCAPE = /[\\"\n\t\r]/;
+/** The body of a PO string: only what would break the line or the quotes is escaped. */
+function escapePo(value) {
+	if (!NEEDS_ESCAPE.test(value)) return value;
+	let out = "";
+	for (let i = 0; i < value.length; i++) {
+		const ch = value[i];
+		switch (ch) {
+			case "\\":
+				out += "\\\\";
+				break;
+			case "\"":
+				out += "\\\"";
+				break;
+			case "\n":
+				out += "\\n";
+				break;
+			case "	":
+				out += "\\t";
+				break;
+			case "\r":
+				out += "\\r";
+				break;
+			default: out += ch;
+		}
+	}
+	return out;
+}
+const SIMPLE_ESCAPES = {
+	"\\": "\\",
+	"\"": "\"",
+	n: "\n",
+	t: "	",
+	r: "\r",
+	a: "\x07",
+	b: "\b",
+	f: "\f",
+	v: "\v",
+	"'": "'",
+	"?": "?"
+};
+function isOctal(code) {
+	return code >= 48 && code <= 55;
+}
+function hexValue(code) {
+	if (code >= 48 && code <= 57) return code - 48;
+	if (code >= 97 && code <= 102) return code - 87;
+	if (code >= 65 && code <= 70) return code - 55;
+	return -1;
+}
+/**
+* Decodes a PO string body (C escapes). Octal and hex escapes are bytes, so
+* runs of them are decoded together as UTF-8 (`\303\251` is `é`). Returns
+* null on an invalid escape.
+*/
+function unescapePo(body) {
+	if (!body.includes("\\")) return body;
+	let out = "";
+	let bytes = null;
+	const flush = () => {
+		if (bytes !== null) {
+			out += Buffer.from(bytes).toString("utf8");
+			bytes = null;
+		}
+	};
+	let i = 0;
+	while (i < body.length) {
+		if (body[i] !== "\\") {
+			flush();
+			const next = body.indexOf("\\", i);
+			const end = next === -1 ? body.length : next;
+			out += body.slice(i, end);
+			i = end;
+			continue;
+		}
+		const escape = body[i + 1];
+		if (escape === void 0) return null;
+		if (Object.hasOwn(SIMPLE_ESCAPES, escape)) {
+			flush();
+			out += SIMPLE_ESCAPES[escape];
+			i += 2;
+			continue;
+		}
+		if (isOctal(escape.charCodeAt(0))) {
+			let value = 0;
+			let j = i + 1;
+			while (j < body.length && j < i + 4 && isOctal(body.charCodeAt(j))) value = value * 8 + body.charCodeAt(j++) - 48;
+			(bytes ??= []).push(value & 255);
+			i = j;
+			continue;
+		}
+		if (escape === "x") {
+			let value = 0;
+			let j = i + 2;
+			while (j < body.length && j < i + 4 && hexValue(body.charCodeAt(j)) !== -1) value = value * 16 + hexValue(body.charCodeAt(j++));
+			if (j === i + 2) return null;
+			(bytes ??= []).push(value);
+			i = j;
+			continue;
+		}
+		return null;
+	}
+	flush();
+	return out;
+}
+/** Parses `"…"` (trailing blanks allowed); null when the token is not exactly one string. */
+function readString(text, from) {
+	let start = from;
+	while (start < text.length && (text[start] === " " || text[start] === "	")) start++;
+	if (text[start] !== "\"") return null;
+	let i = start + 1;
+	while (i < text.length) {
+		const ch = text[i];
+		if (ch === "\\") i += 2;
+		else if (ch === "\"") break;
+		else i++;
+	}
+	if (i >= text.length) return null;
+	for (let j = i + 1; j < text.length; j++) if (text[j] !== " " && text[j] !== "	") return null;
+	return unescapePo(text.slice(start + 1, i));
+}
+function newDraft() {
+	return {
+		raw: [],
+		comments: [],
+		contexts: [],
+		sourceNote: null,
+		refs: [],
+		flags: [],
+		flagKeys: null,
+		fuzzy: false,
+		ai: false,
+		maxLength: null,
+		msgctxt: null,
+		msgid: null,
+		plural: false,
+		msgstr: null,
+		field: null,
+		wrapped: false,
+		line: 0,
+		firstLine: 0,
+		error: null
+	};
+}
+function hasKeywords(draft) {
+	return draft.field !== null;
+}
+function parseError(line, message) {
+	return {
+		code: "catalog-parse",
+		severity: "error",
+		message,
+		line
+	};
+}
+/**
+* `#:` references: whitespace-separated, GNU's FSI…PDI isolation for names
+* with spaces, and `:line` suffixes dropped (vi18n references files only).
+*/
+function readRefs(text, into) {
+	let i = 0;
+	while (i < text.length) {
+		const ch = text[i];
+		if (ch === " " || ch === "	") {
+			i++;
+			continue;
+		}
+		let token;
+		if (ch === FSI) {
+			const end = text.indexOf(PDI, i + 1);
+			const stop = end === -1 ? text.length : end;
+			token = text.slice(i + 1, stop);
+			i = stop + 1;
+			while (i < text.length && text[i] !== " " && text[i] !== "	") i++;
+		} else {
+			let end = i;
+			while (end < text.length && text[end] !== " " && text[end] !== "	") end++;
+			token = text.slice(i, end).replace(/:\d+$/, "");
+			i = end;
+		}
+		if (token !== "") into.push(token);
+	}
+}
+function readFlags(text, line, draft) {
+	for (const part of text.split(",")) {
+		const name = part.trim();
+		if (name === "") continue;
+		if (name === "fuzzy") draft.fuzzy = true;
+		else if (name === "ai") draft.ai = true;
+		else if (name.startsWith("max-length:") && /^max-length:[1-9]\d*$/.test(name)) {
+			const value = Number(name.slice(11));
+			draft.maxLength = draft.maxLength === null ? value : Math.min(draft.maxLength, value);
+		} else {
+			const key = line + name;
+			const keys = draft.flagKeys ??= /* @__PURE__ */ new Set();
+			if (!keys.has(key)) {
+				keys.add(key);
+				draft.flags.push({
+					name,
+					line
+				});
+			}
+		}
+	}
+}
+function sortedUnique(values) {
+	if (values.length < 2) return values;
+	const sorted = values.slice().sort((a, b) => a < b ? -1 : a > b ? 1 : 0);
+	let w = 1;
+	for (let r = 1; r < sorted.length; r++) if (sorted[r] !== sorted[w - 1]) sorted[w++] = sorted[r];
+	sorted.length = w;
+	return sorted;
+}
+function readHeader(msgstr, locale) {
+	const header = {
+		language: locale,
+		idScheme: null,
+		sourceLocale: null,
+		aiModel: null,
+		extra: []
+	};
+	for (const field of msgstr.split("\n")) {
+		const colon = field.indexOf(":");
+		if (colon <= 0) continue;
+		const name = field.slice(0, colon).trim();
+		const value = field.slice(colon + 1).trim();
+		const lower = name.toLowerCase();
+		if (lower === "language") {
+			if (value !== "") header.language = value;
+		} else if (lower === "x-vi18n-id") header.idScheme = value === "" ? null : value;
+		else if (lower === "x-vi18n-ai-model") header.aiModel = value === "" ? null : value;
+		else if (!OWNED_HEADER_FIELDS.has(lower)) header.extra.push([name, value]);
+	}
+	const derived = pluralFormsFor(header.language);
+	if (derived !== null) header.extra = header.extra.filter(([name, value]) => name.toLowerCase() !== "plural-forms" || value !== derived);
+	return header;
+}
+function parsePo(text, options) {
+	const { locale, layout, isSourceLocale } = options;
+	const diagnostics = [];
+	const entries = [];
+	const obsolete = [];
+	let header = null;
+	let draft = newDraft();
+	let block = null;
+	let blockHasMsgstr = false;
+	const closeBlock = () => {
+		if (block !== null) {
+			obsolete.push(block.join("\n"));
+			block = null;
+			blockHasMsgstr = false;
+		}
+	};
+	const finish = () => {
+		const done = draft;
+		if (!hasKeywords(done)) return;
+		draft = newDraft();
+		if (done.error !== null) {
+			diagnostics.push(done.error);
+			return;
+		}
+		if (done.msgid === null) {
+			diagnostics.push(parseError(done.firstLine, "entry without msgid"));
+			return;
+		}
+		if (done.plural) {
+			diagnostics.push(parseError(done.line, "gettext plural entries (msgid_plural) are not supported: write the plural as ICU in the source text"));
+			return;
+		}
+		if (done.msgstr === null) {
+			diagnostics.push(parseError(done.line, "msgid without msgstr"));
+			return;
+		}
+		if (done.msgid === "" && done.msgctxt === null && header === null && entries.length === 0) {
+			header = readHeader(done.msgstr, locale);
+			return;
+		}
+		const manual = done.msgctxt !== null && done.msgctxt.includes(".");
+		const translation = isSourceLocale ? "" : done.msgstr;
+		let source;
+		let label = null;
+		if (layout === "source") source = done.msgid;
+		else {
+			label = done.msgid;
+			source = isSourceLocale ? done.msgstr : done.sourceNote;
+		}
+		const state = translation === "" ? "untranslated" : done.ai ? "ai" : "translated";
+		entries.push({
+			manualId: manual ? done.msgctxt : null,
+			foreignContext: manual ? null : done.msgctxt,
+			label,
+			source,
+			translation,
+			state,
+			fuzzy: done.fuzzy,
+			contexts: done.contexts,
+			comments: done.comments,
+			refs: sortedUnique(done.refs),
+			maxLength: done.maxLength,
+			flags: done.flags,
+			line: done.line,
+			wrapped: done.wrapped
+		});
+	};
+	const fail = (line, message) => {
+		draft.error ??= parseError(line, message);
+	};
+	const start = text.charCodeAt(0) === 65279 ? 1 : 0;
+	const lines = (start === 0 ? text : text.slice(start)).split("\n");
+	for (let index = 0; index < lines.length; index++) {
+		const lineNo = index + 1;
+		let raw = lines[index];
+		if (raw.endsWith("\r")) raw = raw.slice(0, -1);
+		let s = 0;
+		while (s < raw.length && (raw[s] === " " || raw[s] === "	")) s++;
+		if (s === raw.length) {
+			finish();
+			closeBlock();
+			continue;
+		}
+		const line = s === 0 ? raw : raw.slice(s);
+		if (line.startsWith("#~")) {
+			finish();
+			const body = line.slice(2).trimStart();
+			const startsEntry = body.startsWith("msgid") || body.startsWith("msgctxt");
+			if (block !== null && blockHasMsgstr && startsEntry) closeBlock();
+			if (block === null) {
+				block = draft.raw;
+				draft = newDraft();
+			}
+			block.push(raw);
+			if (body.startsWith("msgstr")) blockHasMsgstr = true;
+			continue;
+		}
+		closeBlock();
+		if (line.charCodeAt(0) === 35) {
+			if (hasKeywords(draft)) finish();
+			if (draft.firstLine === 0) draft.firstLine = lineNo;
+			draft.raw.push(raw);
+			const kind = line[1];
+			const rest = line.slice(2);
+			const content = rest.startsWith(" ") ? rest.slice(1) : rest;
+			if (kind === ".") {
+				if (layout === "id" && content.startsWith("source:")) {
+					if (!isSourceLocale) {
+						const body = content.slice(content.startsWith("source: ") ? 8 : 7);
+						const note = unescapePo(body);
+						if (note === null) diagnostics.push({
+							code: "catalog-parse",
+							severity: "warning",
+							message: "invalid escape in #. source:; the note is kept as written",
+							line: lineNo
+						});
+						draft.sourceNote = note ?? body;
+					}
+				} else draft.contexts.push(layout === "id" && ESCAPED_SOURCE_LIKE.test(content) ? content.slice(1) : content);
+			} else if (kind === ":") readRefs(content, draft.refs);
+			else if (kind === ",") readFlags(content, "#,", draft);
+			else if (kind === "=") readFlags(content, "#=", draft);
+			else if (kind === "|") {} else {
+				const body = line.slice(1);
+				draft.comments.push(body.startsWith(" ") ? body.slice(1) : body);
+			}
+			continue;
+		}
+		if (line.charCodeAt(0) === 34) {
+			const value = readString(line, 0);
+			if (draft.field === null) {
+				fail(lineNo, "string continuation without a keyword");
+				draft.firstLine ||= lineNo;
+				draft.field = "msgstr";
+				continue;
+			}
+			if (value === null) {
+				fail(lineNo, "malformed string");
+				continue;
+			}
+			switch (draft.field) {
+				case "msgctxt":
+					draft.msgctxt = (draft.msgctxt ?? "") + value;
+					break;
+				case "msgid":
+					draft.msgid = (draft.msgid ?? "") + value;
+					draft.wrapped = true;
+					break;
+				case "msgstr":
+					draft.msgstr = (draft.msgstr ?? "") + value;
+					draft.wrapped = true;
+			}
+			continue;
+		}
+		const keyword = /^(msgctxt|msgid_plural|msgid|msgstr\[\d+\]|msgstr)(?=[\s"])/.exec(line);
+		if (keyword === null) {
+			if (!hasKeywords(draft)) draft.firstLine ||= lineNo;
+			draft.field ??= "msgstr";
+			fail(lineNo, `unexpected line: ${line.length > 40 ? `${line.slice(0, 40)}…` : line}`);
+			continue;
+		}
+		const word = keyword[1];
+		const field = word.startsWith("msgstr[") ? "msgstr[]" : word;
+		if ((field === "msgctxt" || field === "msgid") && (draft.msgstr !== null || draft.plural)) finish();
+		if (draft.firstLine === 0) draft.firstLine = lineNo;
+		const value = readString(line, word.length);
+		draft.field = field;
+		if (value === null) {
+			fail(lineNo, `malformed ${word} string`);
+			continue;
+		}
+		switch (field) {
+			case "msgctxt":
+				if (draft.msgctxt !== null || draft.msgid !== null) fail(lineNo, "msgctxt must come first, once");
+				draft.msgctxt = value;
+				break;
+			case "msgid":
+				if (draft.msgid !== null) fail(lineNo, "duplicate msgid");
+				draft.msgid = value;
+				draft.line = lineNo;
+				break;
+			case "msgid_plural":
+				draft.plural = true;
+				break;
+			case "msgstr":
+				if (draft.msgid === null) fail(lineNo, "msgstr without msgid");
+				if (draft.msgstr !== null) fail(lineNo, "duplicate msgstr");
+				draft.msgstr = value;
+				break;
+			case "msgstr[]": if (!draft.plural) fail(lineNo, `${word} without msgid_plural`);
+		}
+	}
+	finish();
+	closeBlock();
+	return {
+		catalog: {
+			locale,
+			layout,
+			header: header ?? {
+				language: locale,
+				idScheme: null,
+				sourceLocale: null,
+				aiModel: null,
+				extra: []
+			},
+			entries,
+			obsolete,
+			droppedObsolete: obsolete.length
+		},
+		diagnostics
+	};
+}
+function quoted(value) {
+	return `"${escapePo(value)}"`;
+}
+function headerLine(name, value) {
+	return quoted(`${name}: ${value}\n`);
+}
+/** Notes are single lines in the model; a stray newline must not break the file. */
+function pushNoteLines(out, prefix, value, idContext = false) {
+	for (const part of value.split("\n")) {
+		const line = idContext && SOURCE_LIKE.test(part) ? `\\${part}` : part;
+		out.push(line === "" ? prefix : `${prefix} ${line}`);
+	}
+}
+function refLine(ref) {
+	return /\s/.test(ref) ? `#: ${FSI}${ref}${PDI}` : `#: ${ref}`;
+}
+function pushEntry(out, entry, layout, isSourceLocale) {
+	for (const comment of entry.comments) pushNoteLines(out, "#", comment);
+	for (const context of entry.contexts) pushNoteLines(out, "#.", context, layout === "id");
+	if (layout === "id" && !isSourceLocale && entry.source !== null) out.push(`#. source: ${escapePo(entry.source)}`);
+	for (const ref of entry.refs) if (!LINE_BREAK.test(ref)) out.push(refLine(ref));
+	const comma = [];
+	if (entry.fuzzy) comma.push("fuzzy");
+	if (entry.state === "ai" && !isSourceLocale) comma.push("ai");
+	if (entry.maxLength !== null) comma.push(`max-length:${entry.maxLength}`);
+	let equals = null;
+	for (const flag of entry.flags) if (flag.line === "#,") comma.push(flag.name);
+	else (equals ??= []).push(flag.name);
+	if (comma.length > 0) out.push(`#, ${comma.join(", ")}`);
+	if (equals !== null) out.push(`#= ${equals.join(", ")}`);
+	const context = entry.manualId ?? entry.foreignContext;
+	if (context !== null) out.push(`msgctxt ${quoted(context)}`);
+	out.push(`msgid ${quoted((layout === "id" ? entry.label : entry.source) ?? "")}`);
+	const msgstr = isSourceLocale ? layout === "id" ? entry.source ?? "" : "" : entry.translation;
+	out.push(`msgstr ${quoted(msgstr)}`);
+}
+/**
+* The `Plural-Forms` value to write: one a tool wrote (kept, so vi18n and a
+* PO editor never rewrite each other's spelling of a rule), else the table's
+* formula for the language, else none. Read ones arrive in `extra`.
+*/
+function pluralForms(header) {
+	for (const [name, value] of header.extra) {
+		if (name.toLowerCase() !== "plural-forms") continue;
+		const text = String(value);
+		if (!isPluralFormsPlaceholder(text)) return text;
+		break;
+	}
+	return pluralFormsFor(header.language);
+}
+function serializePo(catalog, options) {
+	const { header, layout } = catalog;
+	const out = [
+		"msgid \"\"",
+		"msgstr \"\"",
+		headerLine("Language", header.language),
+		headerLine("Content-Type", "text/plain; charset=UTF-8")
+	];
+	const plural = pluralForms(header);
+	if (plural !== null) out.push(headerLine("Plural-Forms", plural));
+	out.push(headerLine("X-Generator", `@menapo/vi18n ${options.version}`));
+	if (header.idScheme !== null) out.push(headerLine("X-Vi18n-Id", header.idScheme));
+	if (header.aiModel !== null) out.push(headerLine("X-Vi18n-AI-Model", header.aiModel));
+	for (const [name, value] of header.extra) if (name.toLowerCase() !== "plural-forms") out.push(headerLine(name, String(value)));
+	const entries = catalog.entries.slice().sort((a, b) => compareEntries(a, b, layout));
+	for (const entry of entries) {
+		out.push("");
+		pushEntry(out, entry, layout, options.isSourceLocale);
+	}
+	for (const block of catalog.obsolete) out.push("", block);
+	return `${out.join("\n")}\n`;
+}
+//#endregion
+//#region src/core/catalog/io.ts
+/**
+* Catalog files (INTERNALS §2.6.1, §2.6.6, PLAN §5.6): one per locale,
+* source locale included. Every writer (dev, extract, translate, import,
+* restore) goes through `updateCatalogFile`, a compare-and-swap over an
+* atomic rename, so concurrent writers re-apply their change instead of
+* losing each other's.
+*/
+/** Attempts after the first before `catalog-write-conflict`. */
+const MAX_RETRIES = 5;
+function catalogPath(config, locale) {
+	return config.catalogs.path.replaceAll("{locale}", locale);
+}
+/** The layout a config's catalogs use. */
+function catalogLayout(config) {
+	return config.catalogs.format === "json" ? "json" : config.catalogs.msgid;
+}
+function parseCatalog(text, options) {
+	if (options.layout === "json") return parseJsonCatalog(text, options);
+	return parsePo(text, {
+		locale: options.locale,
+		layout: options.layout,
+		isSourceLocale: options.isSourceLocale
+	});
+}
+function serializeCatalog(catalog, options) {
+	if (catalog.layout === "json") return serializeJsonCatalog(catalog, options);
+	return serializePo(catalog, options);
+}
+/** sha256 hex of a file's bytes: the compare-and-swap token. */
+function contentHash(data) {
+	return hash("sha256", data, "hex");
+}
+const GENERATOR_LINE = /^"X-Generator: [^\n]*\n/m;
+/** Drops the `X-Generator` line, looking only inside the PO header block. */
+function withoutGenerator(text) {
+	if (!text.startsWith("msgid \"\"")) return text;
+	const headerEnd = text.indexOf("\n\n");
+	const header = headerEnd === -1 ? text : text.slice(0, headerEnd + 1);
+	const stripped = header.replace(GENERATOR_LINE, "");
+	return stripped === header ? text : stripped + text.slice(header.length);
+}
+/**
+* Whether two catalog texts are the same output. The `X-Generator` value is
+* ignored, so upgrading vi18n alone never reports drift or rewrites catalogs
+* (INTERNALS §2.6.3); `extract --check`, `compile` and the dev writer use
+* this for every "unchanged" decision.
+*/
+function sameCatalogText(a, b) {
+	return a === b || withoutGenerator(a) === withoutGenerator(b);
+}
+function displayPath$1(root, file) {
+	const rel = relative(root, file);
+	if (rel === "" || rel.startsWith("..") || isAbsolute(rel)) return file.split(sep).join("/");
+	return rel.split(sep).join("/");
+}
+function isMissing(error) {
+	return error?.code === "ENOENT";
+}
+async function readOptional(path) {
+	try {
+		return await readFile(path);
+	} catch (error) {
+		if (isMissing(error)) return null;
+		throw diagnosticError({
+			code: "catalog-parse",
+			severity: "error",
+			message: `cannot read ${path}: ${error instanceof Error ? error.message : String(error)}`,
+			file: path
+		});
+	}
+}
+const UTF8 = new TextDecoder("utf-8", { fatal: true });
+/** Labels that mean UTF-8; `CHARSET` is the placeholder of an unfilled POT header. */
+const UTF8_LABELS = /* @__PURE__ */ new Set([
+	"utf-8",
+	"utf8",
+	"unicode-1-1-utf-8",
+	"charset"
+]);
+/**
+* The charset a PO header declares. GNU tools only write ASCII-compatible
+* charsets, so the header can be read as latin1 before the encoding is known.
+*/
+function poCharset(bytes) {
+	const head = Buffer.from(bytes.buffer, bytes.byteOffset, Math.min(bytes.length, 8192)).toString("latin1").split(/\r?\n[ \t]*\r?\n/, 1)[0];
+	if (!/^[ \t]*msgid[ \t]+""/m.test(head)) return null;
+	return /^[ \t]*"Content-Type:[^"\n]*?charset=([^"\s;\\]+)/im.exec(head)?.[1] ?? null;
+}
+/** 1-based line of the first byte sequence that is not UTF-8 (`\n` never occurs inside one). */
+function firstInvalidLine(bytes) {
+	let start = 0;
+	for (let line = 1;; line++) {
+		const end = bytes.indexOf(10, start);
+		const stop = end === -1 ? bytes.length : end;
+		try {
+			UTF8.decode(bytes.subarray(start, stop));
+		} catch {
+			return line;
+		}
+		if (end === -1) return line;
+		start = end + 1;
+	}
+}
+/**
+* Catalog bytes as text. A PO file in another charset that GNU tools wrote
+* is transcoded, and the next write saves it as UTF-8. Bytes that do not
+* decode come back as a `catalog-parse` error with lossily decoded text: the
+* text keeps the rest of the file readable, the error stops any write that
+* would persist the replacement characters.
+*/
+function decodeCatalog(bytes, layout) {
+	const charset = layout === "json" ? null : poCharset(bytes);
+	const lossy = () => Buffer.from(bytes.buffer, bytes.byteOffset, bytes.length).toString("utf8");
+	if (charset === null || UTF8_LABELS.has(charset.toLowerCase())) try {
+		return {
+			text: UTF8.decode(bytes),
+			diagnostic: null
+		};
+	} catch {
+		return {
+			text: lossy(),
+			diagnostic: {
+				code: "catalog-parse",
+				severity: "error",
+				message: "the file is not valid UTF-8; re-save it as UTF-8",
+				line: firstInvalidLine(bytes)
+			}
+		};
+	}
+	let decoder;
+	try {
+		decoder = new TextDecoder(charset, { fatal: true });
+	} catch {
+		return {
+			text: lossy(),
+			diagnostic: {
+				code: "catalog-parse",
+				severity: "error",
+				message: `unsupported charset ${charset} in Content-Type; convert the file to UTF-8`
+			}
+		};
+	}
+	try {
+		return {
+			text: decoder.decode(bytes),
+			diagnostic: null
+		};
+	} catch {
+		return {
+			text: lossy(),
+			diagnostic: {
+				code: "catalog-parse",
+				severity: "error",
+				message: `the file is not valid ${charset} as its Content-Type declares; fix its encoding`
+			}
+		};
+	}
+}
+function severityOf(level) {
+	return level === "off" ? null : level === "warn" ? "warning" : "error";
+}
+/**
+* Sources that do not parse leave their entry without a key (INTERNALS
+* §2.6.2); they are reported here, once per load, on the entry's line. The
+* advice is what clears the report in every case: `vi18n extract` keeps a
+* generated entry it cannot match to code, and an `extraction.keep` id's.
+*/
+function invalidSources(catalog, codec, isSourceLocale, severity) {
+	if (catalog.layout === "id" && !isSourceLocale) return [];
+	const found = [];
+	for (const entry of catalog.entries) {
+		if (entry.source === null || entry.foreignContext !== null) continue;
+		if (entryCanonical(entry, codec) !== null) continue;
+		try {
+			codec.canonicalize(entry.source);
+		} catch (error) {
+			const reason = error instanceof Error ? error.message : String(error);
+			const diagnostic = {
+				code: "catalog-invalid-translation",
+				severity,
+				message: `the source ${JSON.stringify(entry.source)} is not valid ICU (${reason}); fix its source or delete the entry`,
+				locale: catalog.locale
+			};
+			if (entry.manualId !== null) diagnostic.id = entry.manualId;
+			if (entry.line > 0) diagnostic.line = entry.line;
+			found.push(diagnostic);
+		}
+	}
+	return found;
+}
+/**
+* Reads every locale's catalog (default: `config.locales`). Missing files
+* load as `catalog: null`. Entries are returned as read, duplicates
+* included: `resolveDuplicates` is the read-side pick.
+*/
+async function loadCatalogSet(config, codec, locales) {
+	const layout = catalogLayout(config);
+	const wanted = locales ?? config.locales;
+	const invalid = severityOf(config.strict.invalid);
+	const loaded = await Promise.all(wanted.map(async (locale) => {
+		const path = catalogPath(config, locale);
+		const bytes = await readOptional(path);
+		if (bytes === null) return {
+			catalog: {
+				locale,
+				path,
+				catalog: null,
+				hash: null
+			},
+			diagnostics: []
+		};
+		const isSourceLocale = locale === config.sourceLocale;
+		const decoded = decodeCatalog(bytes, layout);
+		const read = parseCatalog(decoded.text, {
+			locale,
+			layout,
+			isSourceLocale
+		});
+		const diagnostics = read.diagnostics;
+		if (decoded.diagnostic !== null) diagnostics.unshift(decoded.diagnostic);
+		if (invalid !== null) diagnostics.push(...invalidSources(read.catalog, codec, isSourceLocale, invalid));
+		const file = displayPath$1(config.root, path);
+		for (const diagnostic of diagnostics) {
+			diagnostic.file ??= file;
+			diagnostic.locale ??= locale;
+		}
+		return {
+			catalog: {
+				locale,
+				path,
+				catalog: read.catalog,
+				hash: contentHash(bytes)
+			},
+			diagnostics
+		};
+	}));
+	const set = /* @__PURE__ */ new Map();
+	const diagnostics = [];
+	for (const item of loaded) {
+		set.set(item.catalog.locale, item.catalog);
+		diagnostics.push(...item.diagnostics);
+	}
+	if (config.extraction.dependencies.length > 0) diagnostics.push(...await attachLibraryCatalogs(set, config, codec, wanted));
+	return {
+		set,
+		diagnostics
+	};
+}
+/**
+* A catalog from bytes that did not come from its file (`git show` for
+* `vi18n restore`, the merge driver's temporary files), decoded as the file
+* readers decode them.
+*/
+function parseCatalogBytes(bytes, options) {
+	const decoded = decodeCatalog(bytes, options.layout);
+	const read = parseCatalog(decoded.text, options);
+	if (decoded.diagnostic !== null) read.diagnostics.unshift(decoded.diagnostic);
+	return read;
+}
+function parseForUpdate(decoded, path, options) {
+	const read = parseCatalog(decoded.text, options);
+	const error = decoded.diagnostic ?? read.diagnostics.find((diagnostic) => diagnostic.severity === "error");
+	if (error !== void 0) throw diagnosticError({
+		...error,
+		file: error.file ?? path,
+		locale: error.locale ?? options.locale,
+		message: `${error.message}; fix ${basename(path)} before vi18n writes to it`
+	});
+	return read.catalog;
+}
+/** Tail of each file's write queue (in-process writers only). */
+const queues = /* @__PURE__ */ new Map();
+/**
+* Compare-and-swap write (INTERNALS §2.6.6). `update` receives the file as it
+* is now (null when missing) and returns the new catalog, or null to leave
+* the file alone; it may run several times, so it must derive its result
+* from its argument. The new content goes to a temp file in the same
+* directory, the target is re-read, and the temp file is renamed over it
+* only if the target still has the hash `update` saw; otherwise `update`
+* re-runs on the new content. Unchanged output (ignoring `X-Generator`) is
+* never written. `retried` counts re-runs, including one for a file that
+* already differed from `expectedHash` on entry.
+*/
+function updateCatalogFile(path, expectedHash, update, options) {
+	const key = resolve(path);
+	const run = (queues.get(key) ?? Promise.resolve()).then(() => writeCatalogFile(path, expectedHash, update, options), () => writeCatalogFile(path, expectedHash, update, options));
+	const settled = run.then(() => void 0, () => void 0);
+	queues.set(key, settled);
+	settled.then(() => {
+		if (queues.get(key) === settled) queues.delete(key);
+	});
+	return run;
+}
+async function writeCatalogFile(path, expectedHash, update, options) {
+	const readOptions = {
+		locale: options.locale,
+		layout: options.layout,
+		isSourceLocale: options.isSourceLocale
+	};
+	const writeOptions = {
+		isSourceLocale: options.isSourceLocale,
+		version: options.version
+	};
+	let bytes = await readOptional(path);
+	let currentHash = bytes === null ? null : contentHash(bytes);
+	let retried = currentHash === expectedHash ? 0 : 1;
+	const directory = dirname(path);
+	for (;;) {
+		const decoded = bytes === null ? null : decodeCatalog(bytes, options.layout);
+		const text = decoded === null ? null : decoded.text;
+		const next = update(decoded === null ? null : parseForUpdate(decoded, path, readOptions));
+		if (next === null) return {
+			written: false,
+			hash: currentHash,
+			retried
+		};
+		const output = serializeCatalog(next, writeOptions);
+		if (text !== null && sameCatalogText(output, text)) return {
+			written: false,
+			hash: currentHash,
+			retried
+		};
+		if (bytes === null) await mkdir(directory, { recursive: true });
+		const temp = join(directory, `.${basename(path)}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`);
+		await writeFile(temp, output);
+		let renamed = false;
+		try {
+			const now = await readOptional(path);
+			const nowHash = now === null ? null : contentHash(now);
+			if (nowHash === currentHash) {
+				await rename(temp, path);
+				renamed = true;
+				return {
+					written: true,
+					hash: contentHash(output),
+					retried
+				};
+			}
+			bytes = now;
+			currentHash = nowHash;
+		} finally {
+			if (!renamed) await rm(temp, { force: true });
+		}
+		if (++retried > MAX_RETRIES) throw diagnosticError({
+			code: "catalog-write-conflict",
+			severity: "error",
+			message: `${basename(path)} kept changing while vi18n wrote it (${MAX_RETRIES} retries); run the command again`,
+			file: path,
+			locale: options.locale
+		});
+	}
+}
+//#endregion
+//#region src/core/catalog/library.ts
+/**
+* Library mode, the app's side (PLAN §4.7, §5.24; INTERNALS §2.6.11): what an
+* opted-in package ships next to its code. Its `vi18n.messages.json` (written
+* by its own `build.lib` build) lists its messages and its catalogs, and
+* `package.json#vi18n.messages` points at it. Each catalog loads under the
+* app's catalog for the same locale (`LoadedCatalog.libraries`), its entries
+* joined to the app's ids by canonical source or manual id, never by label:
+* a library built with another `ids.length`, or another msgid layout, still
+* matches. Precedence is app catalog, then library catalogs in
+* `extraction.dependencies` order, then the source, at each step of a
+* fallback chain.
+*/
+/** The file a library build writes beside its code (`build.lib`). */
+const MESSAGES_FILE = "vi18n.messages.json";
+const manifests = /* @__PURE__ */ new WeakMap();
+/** Every opted-in package's manifest (those with `package.json#vi18n.messages`), read once per config. */
+function libraryManifests(config) {
+	let list = manifests.get(config.extraction);
+	if (list !== void 0) return list;
+	list = [];
+	for (const dependency of dependenciesOf(config)) {
+		if (dependency.messages === null) continue;
+		list.push({
+			name: dependency.name,
+			file: dependency.messages,
+			...readManifest(dependency.messages, config.root)
+		});
+	}
+	manifests.set(config.extraction, list);
+	return list;
+}
+function readManifest(file, root) {
+	const shown = displayPath(root, file);
+	let data;
+	try {
+		data = JSON.parse(readFileSync(file, "utf8"));
+	} catch (error) {
+		return {
+			manifest: null,
+			diagnostic: {
+				code: "catalog-parse",
+				severity: "warning",
+				message: `${shown} cannot be read (${error.message}); the package's translations are left out`,
+				file: shown
+			}
+		};
+	}
+	const manifest = data;
+	if (manifest === null || typeof manifest !== "object" || manifest.vi18n !== 1 || !Array.isArray(manifest.messages)) return {
+		manifest: null,
+		diagnostic: {
+			code: "catalog-parse",
+			severity: "warning",
+			message: `${shown} is not a vi18n.messages.json of version 1; the package's translations are left out`,
+			file: shown
+		}
+	};
+	return {
+		manifest,
+		diagnostic: null
+	};
+}
+/**
+* The manual-id messages of every opted-in package, first package first:
+* what `msg({ id })` may name without a message (`vi18n.gen.ts` types them).
+*/
+function libraryIds(config) {
+	const out = /* @__PURE__ */ new Map();
+	for (const { manifest } of libraryManifests(config)) for (const message of manifest?.messages ?? []) if (typeof message.id === "string" && typeof message.message === "string" && !out.has(message.id)) out.set(message.id, message.message);
+	return out;
+}
+/**
+* Loads the opted-in packages' catalogs for `locales` under the app's
+* (`LoadedCatalog.libraries`), normalised for joining (below). The source
+* locale compiles from the code, so its library catalogs are read only for a
+* package written in another language: its texts are not the app's source
+* language, and its catalog for that language is what those pages show.
+*/
+async function attachLibraryCatalogs(set, config, codec, locales) {
+	const diagnostics = [];
+	if (config.extraction.dependencies.length === 0) return diagnostics;
+	const layout = catalogLayout(config);
+	for (const loaded of libraryManifests(config)) {
+		if (loaded.diagnostic !== null) diagnostics.push(loaded.diagnostic);
+		const catalogs = loaded.manifest?.catalogs;
+		if (catalogs == null || typeof catalogs.files !== "object") continue;
+		const from = catalogs.format === "json" ? "json" : catalogs.msgid === "id" ? "id" : "source";
+		const foreign = typeof loaded.manifest?.sourceLocale === "string" && loaded.manifest.sourceLocale !== config.sourceLocale;
+		for (const locale of locales) {
+			if (locale === config.sourceLocale && !foreign) continue;
+			const own = set.get(locale);
+			const relativePath = Object.hasOwn(catalogs.files, locale) ? catalogs.files[locale] : void 0;
+			if (locale === config.sourceLocale && typeof relativePath !== "string") {
+				diagnostics.push({
+					code: "catalog-parse",
+					severity: "warning",
+					message: `${loaded.name} is written in ${loaded.manifest?.sourceLocale} and ships no ${locale} catalog; its messages show in ${loaded.manifest?.sourceLocale} on ${locale} pages`,
+					file: displayPath(config.root, loaded.file),
+					locale
+				});
+				continue;
+			}
+			if (own === void 0 || typeof relativePath !== "string") continue;
+			const path = resolve(dirname(loaded.file), relativePath);
+			let text;
+			try {
+				text = await readFile(path, "utf8");
+			} catch {
+				diagnostics.push({
+					code: "catalog-parse",
+					severity: "warning",
+					message: `${loaded.name} lists a ${locale} catalog it does not ship (${relativePath}); its ${locale} translations are left out`,
+					file: displayPath(config.root, loaded.file),
+					locale
+				});
+				continue;
+			}
+			const read = parseCatalog(text, {
+				locale,
+				layout: from,
+				isSourceLocale: false
+			});
+			for (const diagnostic of read.diagnostics) diagnostics.push({
+				...diagnostic,
+				severity: diagnostic.severity === "error" ? "warning" : diagnostic.severity,
+				file: diagnostic.file ?? displayPath(config.root, path),
+				locale
+			});
+			const library = {
+				locale,
+				path,
+				catalog: joined(read.catalog, layout, codec),
+				hash: contentHash(text),
+				library: true,
+				...foreign ? { librarySource: loaded.manifest?.sourceLocale } : {}
+			};
+			set.set(locale, {
+				...own,
+				libraries: [...own.libraries ?? [], library]
+			});
+		}
+	}
+	return diagnostics;
+}
+/**
+* A library catalog in the app's terms: the app's layout, no recorded
+* scheme, and every entry's `label` computed from its source by the app's
+* codec, so `entryKey`, `sourceMatches` and duplicates join by canonical
+* source (generated ids) or manual id whatever the library's `ids.length`
+* and layout. Entries without a source that parses cannot join and are
+* left out.
+*/
+function joined(catalog, layout, codec) {
+	const entries = [];
+	for (const entry of catalog.entries) {
+		if (entry.foreignContext !== null) continue;
+		const canonical = entryCanonical(entry, codec);
+		if (canonical === null) continue;
+		entries.push({
+			...entry,
+			source: canonical,
+			label: codec.label(canonical)
+		});
+	}
+	return {
+		...catalog,
+		layout,
+		header: {
+			...catalog.header,
+			idScheme: null
+		},
+		entries,
+		obsolete: [],
+		droppedObsolete: 0
+	};
+}
+function displayPath(root, file) {
+	const rel = relative(root, file);
+	if (rel === "" || rel.startsWith("..") || isAbsolute(rel)) return file.split(sep).join("/");
+	return rel.split(sep).join("/");
+}
+function libraryCoverage(set, messages, config, codec) {
+	const layout = catalogLayout(config);
+	const locales = /* @__PURE__ */ new Map();
+	let any = false;
+	for (const locale of config.locales) {
+		if (locale === config.sourceLocale) continue;
+		const covered = /* @__PURE__ */ new Set();
+		locales.set(locale, covered);
+		for (const library of set.get(locale)?.libraries ?? []) {
+			any = true;
+			if (library.catalog === null) continue;
+			for (const entry of library.catalog.entries) {
+				const key = entryKey(entry, layout, codec);
+				const message = key === null ? void 0 : messages.get(key);
+				if (message === void 0 || covered.has(message.id)) continue;
+				if (usableTranslation(entry, layout, message, codec, locale).ok) covered.add(message.id);
+			}
+		}
+	}
+	if (!any) return null;
+	const targets = [...locales.values()];
+	const everywhere = /* @__PURE__ */ new Set();
+	for (const id of targets[0] ?? []) if (targets.every((covered) => covered.has(id))) everywhere.add(id);
+	return {
+		locales,
+		everywhere
+	};
+}
+/**
+* The messages a locale's own catalog lists (§2.6.11): an opted-in package
+* translating a message in that locale makes the app's entry unnecessary,
+* unless the app translated it itself (an override, kept). The source
+* locale's catalog leaves out what the packages translate everywhere.
+*/
+function ownedMessages(messages, locale, catalog, coverage, context) {
+	if (coverage == null) return messages;
+	const covered = locale === context.sourceLocale ? coverage.everywhere : coverage.locales.get(locale);
+	if (covered === void 0 || covered.size === 0) return messages;
+	const overridden = /* @__PURE__ */ new Set();
+	if (locale !== context.sourceLocale) for (const entry of catalog?.entries ?? []) {
+		if (entry.translation === "") continue;
+		const key = entryKey(entry, context.layout, context.codec);
+		if (key !== null && covered.has(key)) overridden.add(key);
+	}
+	const out = /* @__PURE__ */ new Map();
+	for (const [id, message] of messages) if (!covered.has(id) || overridden.has(id)) out.set(id, message);
+	return out;
+}
+/** The first library entry of `loaded` that translates `message` usably, for `status` and `check`. */
+function libraryTranslation(loaded, message, layout, codec) {
+	for (const library of loaded?.libraries ?? []) for (const entry of library.catalog?.entries ?? []) {
+		if (entryKey(entry, layout, codec) !== message.id) continue;
+		if (usableTranslation(entry, layout, message, codec, library.locale).ok) return entry;
+	}
+	return null;
+}
+//#endregion
+export { usableTranslation as C, dependencyRef as D, dependencyOf as E, listDependencyFiles as O, entryKey as S, dependenciesOf as T, parseJsonCatalog as _, ownedMessages as a, emptyCatalog as b, contentHash as c, parseCatalogBytes as d, sameCatalogText as f, serializePo as g, parsePo as h, libraryTranslation as i, loadCatalogSet as l, updateCatalogFile as m, libraryCoverage as n, catalogLayout as o, serializeCatalog as p, libraryIds as r, catalogPath as s, MESSAGES_FILE as t, parseCatalog as u, serializeJsonCatalog as v, sourceMatches as w, entryCanonical as x, createEntry as y };