@saykit/config 0.1.0 → 0.3.0

package/README.md

@@ -2,6 +2,8 @@
 
 > Configuration schema and CLI for [SayKit](https://saykit.js.org).
 
+[![Coverage](https://codecov.io/gh/k0d13/saykit/graph/badge.svg?flag=config)](https://codecov.io/gh/k0d13/saykit?flags%5B0%5D=config)
+
 Provides the `defineConfig` helper, the Zod-validated schema for `saykit.config.ts`, and the `saykit` CLI used to extract messages from your source.
 
 ## Install
@@ -19,6 +21,12 @@ import js from '@saykit/transform-js';
 
 export default defineConfig({
   locales: ['en', 'fr'],
+  // Optional per-locale fallback chains, most specific first. The source locale
+  // (the first entry in `locales`) is always the final fallback.
+  fallbackLocales: {
+    'en-NZ': ['en-GB'],
+    'es-MX': 'es',
+  },
   buckets: [
     {
       include: ['src/**/*.ts'],
@@ -35,8 +43,22 @@ export default defineConfig({
 ```sh
 saykit extract           # extract messages once
 saykit extract --watch   # extract and watch for changes
+saykit clean             # reconcile other locales against the source
 ```
 
+Extraction only writes the **source** locale (the first entry in `locales`). Locales that don't
+have a file yet are bootstrapped with an empty, header-only catalogue so a TMS can register them;
+existing translation files are left untouched. Translated content is owned by your TMS.
+
+At load time (via the unplugin or Babel plugin), each locale module is filled from its fallback
+chain, so an untranslated key resolves to a fallback locale and ultimately the source string — the
+runtime still loads a single locale.
+
+`saykit clean` reconciles every non-source locale against the current source catalogue: it adds
+missing keys (untranslated), drops entries that no longer exist in the source, and preserves any
+existing translations. Use it when you want to propagate source changes into locale files yourself
+rather than leaving it to your TMS.
+
 ## Documentation
 
 Full configuration guide and CLI reference at [saykit.js.org](https://saykit.js.org).

package/dist/commands/index.cjs

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 require("../index.cjs");
-const require_loader = require("../loader-DnWt_9U2.cjs");
-const require_hash = require("../hash-CDfMT76E.cjs");
+const require_storage = require("../storage-3BTY8yws.cjs");
+const require_loader = require("../loader-B25O-vF6.cjs");
 let _commander_js_extra_typings = require("@commander-js/extra-typings");
+let node_fs_promises = require("node:fs/promises");
 let node_path = require("node:path");
 let node_async_hooks = require("node:async_hooks");
-let node_fs_promises = require("node:fs/promises");
 //#region src/features/logger.ts
 const RESET = "\x1B[0m";
 const DIM = "\x1B[2m";
@@ -45,6 +45,23 @@ var Logger = class {
 };
 new node_async_hooks.AsyncLocalStorage({ defaultValue: new Logger() });
 //#endregion
+//#region src/commands/clean.ts
+var clean_default = new _commander_js_extra_typings.Command("clean").description("Reconcile non-source locale files against the source locale").option("-v, --verbose", "enable verbose logging", false).option("-q, --quiet", "suppress all logging", false).action(async (options) => {
+	const config = require_loader.resolveConfig();
+	const logger = new Logger(options);
+	logger.header("🧹 Cleaning Locales");
+	const [sourceLocale, ...otherLocales] = config.locales;
+	for (const bucket of config.buckets) {
+		const sourceMessages = await require_storage.readCatalogueMessages(bucket, sourceLocale);
+		logger.info(`Reconciling ${otherLocales.length} locale(s) against ${sourceLocale}`);
+		for (const locale of otherLocales) {
+			logger.step(`Reconciling ${locale}`);
+			await require_storage.writeCatalogueMessages(bucket, locale, require_storage.reconcileLocaleMessages(await require_storage.readCatalogueMessages(bucket, locale), sourceMessages));
+		}
+	}
+	logger.success("Locales cleaned");
+});
+//#endregion
 //#region src/features/catalogue/extractor.ts
 async function extractMessagesFromFile(path, bucket) {
 	const content = await (0, node_fs_promises.readFile)(path, "utf8").catch(() => "");
@@ -56,86 +73,6 @@ async function extractMessagesFromFile(path, bucket) {
 	}));
 }
 //#endregion
-//#region src/features/catalogue/merge.ts
-function mergeUnique(...items) {
-	return Array.from(new Set(items.flat()));
-}
-function getMessageKey(message) {
-	return message.id ?? require_hash.generateHash(message.message, message.context);
-}
-function mergeExtractedMessages(messages) {
-	const mergedMessages = messages.reduce((map, message) => {
-		const key = getMessageKey(message);
-		const existing = map.get(key) ?? message;
-		map.set(key, {
-			...existing,
-			comments: mergeUnique(...existing.comments, ...message.comments),
-			references: mergeUnique(...existing.references, ...message.references)
-		});
-		return map;
-	}, /* @__PURE__ */ new Map());
-	return Array.from(mergedMessages.values());
-}
-function reconcileLocaleMessages(existingMessages, nextMessages) {
-	const existingMessagesByKey = existingMessages.reduce((map, message) => {
-		map.set(getMessageKey(message), message);
-		return map;
-	}, /* @__PURE__ */ new Map());
-	const reconciledMessages = nextMessages.reduce((map, message) => {
-		const key = getMessageKey(message);
-		const existingMessage = existingMessagesByKey.get(key);
-		map.set(key, {
-			message: message.message,
-			translation: void 0,
-			...existingMessage,
-			id: message.id,
-			context: message.context,
-			comments: message.comments,
-			references: message.references
-		});
-		return map;
-	}, /* @__PURE__ */ new Map());
-	return Array.from(reconciledMessages.values());
-}
-//#endregion
-//#region src/features/catalogue/path.ts
-function expandBucketOutputPath(bucket, locale, extension = bucket.formatter.extension) {
-	return (0, node_path.resolve)(bucket.output.replaceAll("{locale}", locale).replaceAll("{extension}", extension.slice(1)));
-}
-function expandBucketOutputIgnoreDirectory(bucket) {
-	const [prefix] = bucket.output.split("{locale}");
-	return (0, node_path.resolve)(prefix || ".");
-}
-//#endregion
-//#region src/features/catalogue/storage.ts
-const DECLARATION_CONTENT = `
-declare const translations: Record<string, string>;
-export default translations;
-`.trim();
-async function readCatalogueMessages(bucket, locale, path = expandBucketOutputPath(bucket, locale)) {
-	const content = await (0, node_fs_promises.readFile)(path, "utf8").catch(() => "");
-	if (!content) return [];
-	return bucket.formatter.parse(content);
-}
-async function writeCatalogueMessages(bucket, locale, messages, path = expandBucketOutputPath(bucket, locale)) {
-	const existingContent = await (0, node_fs_promises.readFile)(path, "utf8").catch(() => void 0);
-	const catalogueContent = bucket.formatter.stringify(messages, {
-		locale,
-		existingContent
-	});
-	const declarationPath = `${path}.d.ts`;
-	const ignoreDirectory = expandBucketOutputIgnoreDirectory(bucket);
-	const ignorePath = (0, node_path.join)(ignoreDirectory, ".gitignore");
-	const ignoreContent = `.gitignore\n*.${bucket.formatter.extension.slice(1)}.d.ts`;
-	await (0, node_fs_promises.mkdir)((0, node_path.dirname)(path), { recursive: true });
-	await (0, node_fs_promises.mkdir)(ignoreDirectory, { recursive: true });
-	await Promise.all([
-		(0, node_fs_promises.writeFile)(path, catalogueContent),
-		(0, node_fs_promises.writeFile)(declarationPath, DECLARATION_CONTENT),
-		(0, node_fs_promises.writeFile)(ignorePath, ignoreContent)
-	]);
-}
-//#endregion
 //#region src/features/watch.ts
 /**
 * Expand a buckets include and exclude patterns into a flat list of file paths.
@@ -195,6 +132,9 @@ var BucketWorker = class {
 };
 //#endregion
 //#region src/features/workers/extract-worker.ts
+function exists(path) {
+	return (0, node_fs_promises.access)(path).then(() => true, () => false);
+}
 var BucketExtractWorker = class extends BucketWorker {
 	#indexedMessagesByPath = /* @__PURE__ */ new Map();
 	get #indexedMessages() {
@@ -224,13 +164,18 @@ var BucketExtractWorker = class extends BucketWorker {
 		this.logger.info(`Total extracted messages: ${this.#indexedMessages.length}`);
 	}
 	async write() {
-		const mergedMessages = mergeExtractedMessages(this.#indexedMessages);
-		this.logger.info(`Writing ${mergedMessages.length} messages to locales`);
-		for (const locale of this.config.locales) {
-			this.logger.step(`Writing locale file for ${locale} to disk`);
-			const existingMessages = await readCatalogueMessages(this.bucket, locale);
-			const nextMessages = locale === this.config.locales[0] ? mergedMessages : reconcileLocaleMessages(existingMessages, mergedMessages);
-			await writeCatalogueMessages(this.bucket, locale, nextMessages);
+		const mergedMessages = require_storage.mergeExtractedMessages(this.#indexedMessages);
+		const [sourceLocale, ...otherLocales] = this.config.locales;
+		this.logger.info(`Writing ${mergedMessages.length} messages to ${sourceLocale}`);
+		this.logger.step(`Writing locale file for ${sourceLocale} to disk`);
+		await require_storage.writeCatalogueMessages(this.bucket, sourceLocale, mergedMessages);
+		for (const locale of otherLocales) {
+			if (await exists(require_storage.expandBucketOutputPath(this.bucket, locale))) {
+				this.logger.step(`Skipping existing locale file for ${locale}`);
+				continue;
+			}
+			this.logger.step(`Creating empty locale file for ${locale}`);
+			await require_storage.writeCatalogueMessages(this.bucket, locale, []);
 		}
 		this.logger.success(`Extraction complete for bucket: ${this.bucket.include}`);
 	}
@@ -260,5 +205,5 @@ var extract_default = new _commander_js_extra_typings.Command("extract").descrip
 });
 //#endregion
 //#region src/commands/index.ts
-_commander_js_extra_typings.program.name("saykit").helpOption("-h, --help", "Display help for command").helpCommand("help [command]", "Display help for command").addCommand(extract_default).parse();
+_commander_js_extra_typings.program.name("saykit").helpOption("-h, --help", "Display help for command").helpCommand("help [command]", "Display help for command").addCommand(extract_default).addCommand(clean_default).parse();
 //#endregion

package/dist/commands/index.mjs

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
-import { t as resolveConfig } from "../loader-CGuahnrc.mjs";
-import { t as generateHash } from "../hash-Cs0dRdGf.mjs";
+import { a as reconcileLocaleMessages, i as mergeExtractedMessages, n as writeCatalogueMessages, r as expandBucketOutputPath, t as readCatalogueMessages } from "../storage-C9nzxPtZ.mjs";
+import { t as resolveConfig } from "../loader-C2eolE_1.mjs";
 import { Command, program } from "@commander-js/extra-typings";
-import { dirname, join, relative, resolve } from "node:path";
+import { access, glob, readFile, watch } from "node:fs/promises";
+import { join, relative } from "node:path";
 import { AsyncLocalStorage } from "node:async_hooks";
-import { glob, mkdir, readFile, watch, writeFile } from "node:fs/promises";
 //#region src/features/logger.ts
 const RESET = "\x1B[0m";
 const DIM = "\x1B[2m";
@@ -44,6 +44,23 @@ var Logger = class {
 };
 new AsyncLocalStorage({ defaultValue: new Logger() });
 //#endregion
+//#region src/commands/clean.ts
+var clean_default = new Command("clean").description("Reconcile non-source locale files against the source locale").option("-v, --verbose", "enable verbose logging", false).option("-q, --quiet", "suppress all logging", false).action(async (options) => {
+	const config = resolveConfig();
+	const logger = new Logger(options);
+	logger.header("🧹 Cleaning Locales");
+	const [sourceLocale, ...otherLocales] = config.locales;
+	for (const bucket of config.buckets) {
+		const sourceMessages = await readCatalogueMessages(bucket, sourceLocale);
+		logger.info(`Reconciling ${otherLocales.length} locale(s) against ${sourceLocale}`);
+		for (const locale of otherLocales) {
+			logger.step(`Reconciling ${locale}`);
+			await writeCatalogueMessages(bucket, locale, reconcileLocaleMessages(await readCatalogueMessages(bucket, locale), sourceMessages));
+		}
+	}
+	logger.success("Locales cleaned");
+});
+//#endregion
 //#region src/features/catalogue/extractor.ts
 async function extractMessagesFromFile(path, bucket) {
 	const content = await readFile(path, "utf8").catch(() => "");
@@ -55,86 +72,6 @@ async function extractMessagesFromFile(path, bucket) {
 	}));
 }
 //#endregion
-//#region src/features/catalogue/merge.ts
-function mergeUnique(...items) {
-	return Array.from(new Set(items.flat()));
-}
-function getMessageKey(message) {
-	return message.id ?? generateHash(message.message, message.context);
-}
-function mergeExtractedMessages(messages) {
-	const mergedMessages = messages.reduce((map, message) => {
-		const key = getMessageKey(message);
-		const existing = map.get(key) ?? message;
-		map.set(key, {
-			...existing,
-			comments: mergeUnique(...existing.comments, ...message.comments),
-			references: mergeUnique(...existing.references, ...message.references)
-		});
-		return map;
-	}, /* @__PURE__ */ new Map());
-	return Array.from(mergedMessages.values());
-}
-function reconcileLocaleMessages(existingMessages, nextMessages) {
-	const existingMessagesByKey = existingMessages.reduce((map, message) => {
-		map.set(getMessageKey(message), message);
-		return map;
-	}, /* @__PURE__ */ new Map());
-	const reconciledMessages = nextMessages.reduce((map, message) => {
-		const key = getMessageKey(message);
-		const existingMessage = existingMessagesByKey.get(key);
-		map.set(key, {
-			message: message.message,
-			translation: void 0,
-			...existingMessage,
-			id: message.id,
-			context: message.context,
-			comments: message.comments,
-			references: message.references
-		});
-		return map;
-	}, /* @__PURE__ */ new Map());
-	return Array.from(reconciledMessages.values());
-}
-//#endregion
-//#region src/features/catalogue/path.ts
-function expandBucketOutputPath(bucket, locale, extension = bucket.formatter.extension) {
-	return resolve(bucket.output.replaceAll("{locale}", locale).replaceAll("{extension}", extension.slice(1)));
-}
-function expandBucketOutputIgnoreDirectory(bucket) {
-	const [prefix] = bucket.output.split("{locale}");
-	return resolve(prefix || ".");
-}
-//#endregion
-//#region src/features/catalogue/storage.ts
-const DECLARATION_CONTENT = `
-declare const translations: Record<string, string>;
-export default translations;
-`.trim();
-async function readCatalogueMessages(bucket, locale, path = expandBucketOutputPath(bucket, locale)) {
-	const content = await readFile(path, "utf8").catch(() => "");
-	if (!content) return [];
-	return bucket.formatter.parse(content);
-}
-async function writeCatalogueMessages(bucket, locale, messages, path = expandBucketOutputPath(bucket, locale)) {
-	const existingContent = await readFile(path, "utf8").catch(() => void 0);
-	const catalogueContent = bucket.formatter.stringify(messages, {
-		locale,
-		existingContent
-	});
-	const declarationPath = `${path}.d.ts`;
-	const ignoreDirectory = expandBucketOutputIgnoreDirectory(bucket);
-	const ignorePath = join(ignoreDirectory, ".gitignore");
-	const ignoreContent = `.gitignore\n*.${bucket.formatter.extension.slice(1)}.d.ts`;
-	await mkdir(dirname(path), { recursive: true });
-	await mkdir(ignoreDirectory, { recursive: true });
-	await Promise.all([
-		writeFile(path, catalogueContent),
-		writeFile(declarationPath, DECLARATION_CONTENT),
-		writeFile(ignorePath, ignoreContent)
-	]);
-}
-//#endregion
 //#region src/features/watch.ts
 /**
 * Expand a buckets include and exclude patterns into a flat list of file paths.
@@ -194,6 +131,9 @@ var BucketWorker = class {
 };
 //#endregion
 //#region src/features/workers/extract-worker.ts
+function exists(path) {
+	return access(path).then(() => true, () => false);
+}
 var BucketExtractWorker = class extends BucketWorker {
 	#indexedMessagesByPath = /* @__PURE__ */ new Map();
 	get #indexedMessages() {
@@ -224,12 +164,17 @@ var BucketExtractWorker = class extends BucketWorker {
 	}
 	async write() {
 		const mergedMessages = mergeExtractedMessages(this.#indexedMessages);
-		this.logger.info(`Writing ${mergedMessages.length} messages to locales`);
-		for (const locale of this.config.locales) {
-			this.logger.step(`Writing locale file for ${locale} to disk`);
-			const existingMessages = await readCatalogueMessages(this.bucket, locale);
-			const nextMessages = locale === this.config.locales[0] ? mergedMessages : reconcileLocaleMessages(existingMessages, mergedMessages);
-			await writeCatalogueMessages(this.bucket, locale, nextMessages);
+		const [sourceLocale, ...otherLocales] = this.config.locales;
+		this.logger.info(`Writing ${mergedMessages.length} messages to ${sourceLocale}`);
+		this.logger.step(`Writing locale file for ${sourceLocale} to disk`);
+		await writeCatalogueMessages(this.bucket, sourceLocale, mergedMessages);
+		for (const locale of otherLocales) {
+			if (await exists(expandBucketOutputPath(this.bucket, locale))) {
+				this.logger.step(`Skipping existing locale file for ${locale}`);
+				continue;
+			}
+			this.logger.step(`Creating empty locale file for ${locale}`);
+			await writeCatalogueMessages(this.bucket, locale, []);
 		}
 		this.logger.success(`Extraction complete for bucket: ${this.bucket.include}`);
 	}
@@ -259,6 +204,6 @@ var extract_default = new Command("extract").description("Extract messages from
 });
 //#endregion
 //#region src/commands/index.ts
-program.name("saykit").helpOption("-h, --help", "Display help for command").helpCommand("help [command]", "Display help for command").addCommand(extract_default).parse();
+program.name("saykit").helpOption("-h, --help", "Display help for command").helpCommand("help [command]", "Display help for command").addCommand(extract_default).addCommand(clean_default).parse();
 //#endregion
 export {};

package/dist/features/catalogue/index.cjs

@@ -0,0 +1,60 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+require("../../index.cjs");
+const require_hash = require("../../hash-8It7TJpB.cjs");
+const require_storage = require("../../storage-3BTY8yws.cjs");
+let node_path = require("node:path");
+//#region src/features/catalogue/record.ts
+/**
+* Resolve the fallback chain for a locale, most specific first. The source
+* locale (the first configured locale) is always the final fallback, so an
+* untranslated key ultimately resolves to the source string.
+*/
+function resolveFallbackChain(config, locale) {
+	const source = config.locales[0];
+	const configured = config.fallbackLocales?.[locale];
+	const fallbacks = configured ? Array.isArray(configured) ? configured : [configured] : [];
+	return Array.from(new Set([
+		locale,
+		...fallbacks,
+		source
+	]));
+}
+/**
+* Resolve the catalogue files that contribute to a locale module, most specific
+* first. When the path does not map to a configured locale it is loaded on its
+* own.
+*/
+function resolveCatalogueSources(config, bucket, path) {
+	const resolved = (0, node_path.resolve)(path);
+	const locale = config.locales.find((l) => require_storage.expandBucketOutputPath(bucket, l) === resolved);
+	return {
+		locale,
+		sources: locale ? resolveFallbackChain(config, locale).map((l) => require_storage.expandBucketOutputPath(bucket, l)) : [resolved]
+	};
+}
+/**
+* Assemble a `{ id: string }` record from catalogue file contents. `contents`
+* must be aligned with the `sources` returned by {@link resolveCatalogueSources}
+* (most specific first): more specific locales override their fallbacks, and any
+* key still untranslated falls back to its source message.
+*/
+function assembleCatalogueRecord(bucket, contents) {
+	const record = {};
+	for (const content of [...contents].reverse()) {
+		if (!content) continue;
+		for (const message of bucket.formatter.parse(content)) {
+			const key = message.id || require_hash.generateHash(message.message, message.context);
+			record[key] = message.translation || message.message;
+		}
+	}
+	return record;
+}
+//#endregion
+exports.assembleCatalogueRecord = assembleCatalogueRecord;
+exports.expandBucketOutputPath = require_storage.expandBucketOutputPath;
+exports.mergeExtractedMessages = require_storage.mergeExtractedMessages;
+exports.readCatalogueMessages = require_storage.readCatalogueMessages;
+exports.reconcileLocaleMessages = require_storage.reconcileLocaleMessages;
+exports.resolveCatalogueSources = resolveCatalogueSources;
+exports.resolveFallbackChain = resolveFallbackChain;
+exports.writeCatalogueMessages = require_storage.writeCatalogueMessages;

package/dist/features/catalogue/index.d.cts

@@ -0,0 +1,59 @@
+import { i as Message, n as Config, t as Bucket } from "../../shapes-Ba3xS10n.cjs";
+
+//#region src/features/catalogue/merge.d.ts
+declare function mergeExtractedMessages(messages: Message[]): {
+  message: string;
+  comments: string[];
+  references: string[];
+  translation?: string | undefined;
+  id?: string | undefined;
+  context?: string | undefined;
+}[];
+declare function reconcileLocaleMessages(existingMessages: Message[], nextMessages: Message[]): {
+  message: string;
+  comments: string[];
+  references: string[];
+  translation?: string | undefined;
+  id?: string | undefined;
+  context?: string | undefined;
+}[];
+//#endregion
+//#region src/features/catalogue/path.d.ts
+declare function expandBucketOutputPath(bucket: Bucket, locale: string, extension?: `.${string}`): string;
+//#endregion
+//#region src/features/catalogue/record.d.ts
+/**
+ * Resolve the fallback chain for a locale, most specific first. The source
+ * locale (the first configured locale) is always the final fallback, so an
+ * untranslated key ultimately resolves to the source string.
+ */
+declare function resolveFallbackChain(config: Config, locale: string): string[];
+/**
+ * Resolve the catalogue files that contribute to a locale module, most specific
+ * first. When the path does not map to a configured locale it is loaded on its
+ * own.
+ */
+declare function resolveCatalogueSources(config: Config, bucket: Bucket, path: string): {
+  locale: string | undefined;
+  sources: string[];
+};
+/**
+ * Assemble a `{ id: string }` record from catalogue file contents. `contents`
+ * must be aligned with the `sources` returned by {@link resolveCatalogueSources}
+ * (most specific first): more specific locales override their fallbacks, and any
+ * key still untranslated falls back to its source message.
+ */
+declare function assembleCatalogueRecord(bucket: Bucket, contents: string[]): Record<string, string>;
+//#endregion
+//#region src/features/catalogue/storage.d.ts
+declare function readCatalogueMessages(bucket: Bucket, locale: string, path?: string): Promise<{
+  message: string;
+  comments: string[];
+  references: string[];
+  translation?: string | undefined;
+  id?: string | undefined;
+  context?: string | undefined;
+}[]>;
+declare function writeCatalogueMessages(bucket: Bucket, locale: string, messages: Message[], path?: string): Promise<void>;
+//#endregion
+export { assembleCatalogueRecord, expandBucketOutputPath, mergeExtractedMessages, readCatalogueMessages, reconcileLocaleMessages, resolveCatalogueSources, resolveFallbackChain, writeCatalogueMessages };

package/dist/features/catalogue/index.d.mts

@@ -0,0 +1,59 @@
+import { i as Message, n as Config, t as Bucket } from "../../shapes-NPfwlInG.mjs";
+
+//#region src/features/catalogue/merge.d.ts
+declare function mergeExtractedMessages(messages: Message[]): {
+  message: string;
+  comments: string[];
+  references: string[];
+  translation?: string | undefined;
+  id?: string | undefined;
+  context?: string | undefined;
+}[];
+declare function reconcileLocaleMessages(existingMessages: Message[], nextMessages: Message[]): {
+  message: string;
+  comments: string[];
+  references: string[];
+  translation?: string | undefined;
+  id?: string | undefined;
+  context?: string | undefined;
+}[];
+//#endregion
+//#region src/features/catalogue/path.d.ts
+declare function expandBucketOutputPath(bucket: Bucket, locale: string, extension?: `.${string}`): string;
+//#endregion
+//#region src/features/catalogue/record.d.ts
+/**
+ * Resolve the fallback chain for a locale, most specific first. The source
+ * locale (the first configured locale) is always the final fallback, so an
+ * untranslated key ultimately resolves to the source string.
+ */
+declare function resolveFallbackChain(config: Config, locale: string): string[];
+/**
+ * Resolve the catalogue files that contribute to a locale module, most specific
+ * first. When the path does not map to a configured locale it is loaded on its
+ * own.
+ */
+declare function resolveCatalogueSources(config: Config, bucket: Bucket, path: string): {
+  locale: string | undefined;
+  sources: string[];
+};
+/**
+ * Assemble a `{ id: string }` record from catalogue file contents. `contents`
+ * must be aligned with the `sources` returned by {@link resolveCatalogueSources}
+ * (most specific first): more specific locales override their fallbacks, and any
+ * key still untranslated falls back to its source message.
+ */
+declare function assembleCatalogueRecord(bucket: Bucket, contents: string[]): Record<string, string>;
+//#endregion
+//#region src/features/catalogue/storage.d.ts
+declare function readCatalogueMessages(bucket: Bucket, locale: string, path?: string): Promise<{
+  message: string;
+  comments: string[];
+  references: string[];
+  translation?: string | undefined;
+  id?: string | undefined;
+  context?: string | undefined;
+}[]>;
+declare function writeCatalogueMessages(bucket: Bucket, locale: string, messages: Message[], path?: string): Promise<void>;
+//#endregion
+export { assembleCatalogueRecord, expandBucketOutputPath, mergeExtractedMessages, readCatalogueMessages, reconcileLocaleMessages, resolveCatalogueSources, resolveFallbackChain, writeCatalogueMessages };

package/dist/features/catalogue/index.mjs

@@ -0,0 +1,51 @@
+import { t as generateHash } from "../../hash-DyC8GzMa.mjs";
+import { a as reconcileLocaleMessages, i as mergeExtractedMessages, n as writeCatalogueMessages, r as expandBucketOutputPath, t as readCatalogueMessages } from "../../storage-C9nzxPtZ.mjs";
+import { resolve } from "node:path";
+//#region src/features/catalogue/record.ts
+/**
+* Resolve the fallback chain for a locale, most specific first. The source
+* locale (the first configured locale) is always the final fallback, so an
+* untranslated key ultimately resolves to the source string.
+*/
+function resolveFallbackChain(config, locale) {
+	const source = config.locales[0];
+	const configured = config.fallbackLocales?.[locale];
+	const fallbacks = configured ? Array.isArray(configured) ? configured : [configured] : [];
+	return Array.from(new Set([
+		locale,
+		...fallbacks,
+		source
+	]));
+}
+/**
+* Resolve the catalogue files that contribute to a locale module, most specific
+* first. When the path does not map to a configured locale it is loaded on its
+* own.
+*/
+function resolveCatalogueSources(config, bucket, path) {
+	const resolved = resolve(path);
+	const locale = config.locales.find((l) => expandBucketOutputPath(bucket, l) === resolved);
+	return {
+		locale,
+		sources: locale ? resolveFallbackChain(config, locale).map((l) => expandBucketOutputPath(bucket, l)) : [resolved]
+	};
+}
+/**
+* Assemble a `{ id: string }` record from catalogue file contents. `contents`
+* must be aligned with the `sources` returned by {@link resolveCatalogueSources}
+* (most specific first): more specific locales override their fallbacks, and any
+* key still untranslated falls back to its source message.
+*/
+function assembleCatalogueRecord(bucket, contents) {
+	const record = {};
+	for (const content of [...contents].reverse()) {
+		if (!content) continue;
+		for (const message of bucket.formatter.parse(content)) {
+			const key = message.id || generateHash(message.message, message.context);
+			record[key] = message.translation || message.message;
+		}
+	}
+	return record;
+}
+//#endregion
+export { assembleCatalogueRecord, expandBucketOutputPath, mergeExtractedMessages, readCatalogueMessages, reconcileLocaleMessages, resolveCatalogueSources, resolveFallbackChain, writeCatalogueMessages };

package/dist/features/loader/index.cjs

@@ -1,3 +1,3 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_loader = require("../../loader-DnWt_9U2.cjs");
+const require_loader = require("../../loader-B25O-vF6.cjs");
 exports.resolveConfig = require_loader.resolveConfig;

package/dist/features/loader/index.d.cts

@@ -1,4 +1,4 @@
-import { n as Config } from "../../shapes-CJyTfZXd.cjs";
+import { n as Config } from "../../shapes-Ba3xS10n.cjs";
 
 //#region src/features/loader/resolve.d.ts
 declare function resolveConfig(name?: string): Config;

package/dist/features/loader/index.d.mts

@@ -1,4 +1,4 @@
-import { n as Config } from "../../shapes-DETrtvZf.mjs";
+import { n as Config } from "../../shapes-NPfwlInG.mjs";
 
 //#region src/features/loader/resolve.d.ts
 declare function resolveConfig(name?: string): Config;

package/dist/features/loader/index.mjs

@@ -1,2 +1,2 @@
-import { t as resolveConfig } from "../../loader-CGuahnrc.mjs";
+import { t as resolveConfig } from "../../loader-C2eolE_1.mjs";
 export { resolveConfig };

package/dist/features/messages/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_hash = require("../../hash-CDfMT76E.cjs");
+const require_hash = require("../../hash-8It7TJpB.cjs");
 //#region src/features/messages/identifier.ts
 const AUTO_INCREMENT_IDENTIFIER = Symbol("auto-increment");
 function assignSequenceIdentifiers(message, sequence = { current: 0 }) {
@@ -54,13 +54,14 @@ var ChoiceMessage = class extends Base {
 	}
 };
 var CompositeMessage = class extends Base {
-	constructor(descriptor, comments, references, children, accessor) {
+	constructor(descriptor, comments, references, children, accessor, whitespace) {
 		super();
 		this.descriptor = descriptor;
 		this.comments = comments;
 		this.references = references;
 		this.children = children;
 		this.accessor = accessor;
+		this.whitespace = whitespace;
 	}
 };
 //#endregion

package/dist/features/messages/index.d.cts

@@ -46,10 +46,11 @@ declare class CompositeMessage extends Base {
   readonly references: string[];
   readonly children: Message[];
   readonly accessor: any;
+  readonly whitespace?: boolean | undefined;
   constructor(descriptor: {
     id?: string;
     context?: string;
-  }, comments: string[], references: string[], children: Message[], accessor: any);
+  }, comments: string[], references: string[], children: Message[], accessor: any, whitespace?: boolean | undefined);
 }
 type Message = LiteralMessage | ArgumentMessage | ElementMessage | ChoiceMessage | CompositeMessage;
 //#endregion

package/dist/features/messages/index.d.mts

@@ -46,10 +46,11 @@ declare class CompositeMessage extends Base {
   readonly references: string[];
   readonly children: Message[];
   readonly accessor: any;
+  readonly whitespace?: boolean | undefined;
   constructor(descriptor: {
     id?: string;
     context?: string;
-  }, comments: string[], references: string[], children: Message[], accessor: any);
+  }, comments: string[], references: string[], children: Message[], accessor: any, whitespace?: boolean | undefined);
 }
 type Message = LiteralMessage | ArgumentMessage | ElementMessage | ChoiceMessage | CompositeMessage;
 //#endregion

package/dist/features/messages/index.mjs

@@ -1,4 +1,4 @@
-import { t as generateHash } from "../../hash-Cs0dRdGf.mjs";
+import { t as generateHash } from "../../hash-DyC8GzMa.mjs";
 //#region src/features/messages/identifier.ts
 const AUTO_INCREMENT_IDENTIFIER = Symbol("auto-increment");
 function assignSequenceIdentifiers(message, sequence = { current: 0 }) {
@@ -53,13 +53,14 @@ var ChoiceMessage = class extends Base {
 	}
 };
 var CompositeMessage = class extends Base {
-	constructor(descriptor, comments, references, children, accessor) {
+	constructor(descriptor, comments, references, children, accessor, whitespace) {
 		super();
 		this.descriptor = descriptor;
 		this.comments = comments;
 		this.references = references;
 		this.children = children;
 		this.accessor = accessor;
+		this.whitespace = whitespace;
 	}
 };
 //#endregion

package/dist/index.cjs

@@ -65,6 +65,13 @@ const Bucket = zod.object({
 }));
 const Config = zod.object({
 	locales: zod.tuple([zod.string()], zod.string()),
+	/**
+	* Per-locale fallback chains, most specific first, e.g.
+	* `{ 'en-NZ': ['en-GB'], 'es-MX': 'es' }`. The source locale (the first entry
+	* in {@link Config.locales}) is always appended as the final fallback, so an
+	* untranslated key ultimately resolves to the source string.
+	*/
+	fallbackLocales: zod.record(zod.string(), zod.string().or(zod.string().array())).optional(),
 	buckets: Bucket.array()
 });
 //#endregion

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { a as Transformer, i as Message, n as Config, r as Formatter, t as Bucket } from "./shapes-CJyTfZXd.cjs";
+import { a as Transformer, i as Message, n as Config, r as Formatter, t as Bucket } from "./shapes-Ba3xS10n.cjs";
 import { input } from "zod";
 import * as _$picomatch_lib_picomatch_js0 from "picomatch/lib/picomatch.js";
 
@@ -33,6 +33,7 @@ declare function defineConfig<C extends input<typeof Config>>(config: C): {
     };
     exclude?: string[] | undefined;
   }[];
+  fallbackLocales?: Record<string, string | string[]> | undefined;
 };
 //#endregion
 export { Bucket, Config, Formatter, Message, Transformer, defineConfig };

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { a as Transformer, i as Message, n as Config, r as Formatter, t as Bucket } from "./shapes-DETrtvZf.mjs";
+import { a as Transformer, i as Message, n as Config, r as Formatter, t as Bucket } from "./shapes-NPfwlInG.mjs";
 import { input } from "zod";
 import * as _$picomatch_lib_picomatch_js0 from "picomatch/lib/picomatch.js";
 
@@ -33,6 +33,7 @@ declare function defineConfig<C extends input<typeof Config>>(config: C): {
     };
     exclude?: string[] | undefined;
   }[];
+  fallbackLocales?: Record<string, string | string[]> | undefined;
 };
 //#endregion
 export { Bucket, Config, Formatter, Message, Transformer, defineConfig };

package/dist/index.mjs

@@ -40,6 +40,13 @@ const Bucket = z.object({
 }));
 const Config = z.object({
 	locales: z.tuple([z.string()], z.string()),
+	/**
+	* Per-locale fallback chains, most specific first, e.g.
+	* `{ 'en-NZ': ['en-GB'], 'es-MX': 'es' }`. The source locale (the first entry
+	* in {@link Config.locales}) is always appended as the final fallback, so an
+	* untranslated key ultimately resolves to the source string.
+	*/
+	fallbackLocales: z.record(z.string(), z.string().or(z.string().array())).optional(),
 	buckets: Bucket.array()
 });
 //#endregion

package/dist/{shapes-CJyTfZXd.d.cts → shapes-Ba3xS10n.d.cts}

@@ -131,6 +131,7 @@ declare const Bucket: z.ZodPipe<z.ZodObject<{
 type Bucket = z.infer<typeof Bucket>;
 declare const Config: z.ZodObject<{
   locales: z.ZodTuple<[z.ZodString], z.ZodString>;
+  fallbackLocales: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString>]>>>;
   buckets: z.ZodArray<z.ZodPipe<z.ZodObject<{
     include: z.ZodArray<z.ZodString>;
     exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;

package/dist/{shapes-DETrtvZf.d.mts → shapes-NPfwlInG.d.mts}

@@ -131,6 +131,7 @@ declare const Bucket: z.ZodPipe<z.ZodObject<{
 type Bucket = z.infer<typeof Bucket>;
 declare const Config: z.ZodObject<{
   locales: z.ZodTuple<[z.ZodString], z.ZodString>;
+  fallbackLocales: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString>]>>>;
   buckets: z.ZodArray<z.ZodPipe<z.ZodObject<{
     include: z.ZodArray<z.ZodString>;
     exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;

package/dist/storage-3BTY8yws.cjs

@@ -0,0 +1,97 @@
+require("./index.cjs");
+const require_hash = require("./hash-8It7TJpB.cjs");
+let node_fs_promises = require("node:fs/promises");
+let node_path = require("node:path");
+//#region src/features/catalogue/merge.ts
+function mergeUnique(...items) {
+	return Array.from(new Set(items.flat()));
+}
+function getMessageKey(message) {
+	return message.id ?? require_hash.generateHash(message.message, message.context);
+}
+function mergeExtractedMessages(messages) {
+	const mergedMessages = messages.reduce((map, message) => {
+		const key = getMessageKey(message);
+		const existing = map.get(key) ?? message;
+		map.set(key, {
+			...existing,
+			comments: mergeUnique(...existing.comments, ...message.comments),
+			references: mergeUnique(...existing.references, ...message.references)
+		});
+		return map;
+	}, /* @__PURE__ */ new Map());
+	return Array.from(mergedMessages.values());
+}
+function reconcileLocaleMessages(existingMessages, nextMessages) {
+	const existingMessagesByKey = existingMessages.reduce((map, message) => {
+		map.set(getMessageKey(message), message);
+		return map;
+	}, /* @__PURE__ */ new Map());
+	const reconciledMessages = nextMessages.reduce((map, message) => {
+		const key = getMessageKey(message);
+		const existingMessage = existingMessagesByKey.get(key);
+		map.set(key, {
+			...message,
+			translation: existingMessage?.translation
+		});
+		return map;
+	}, /* @__PURE__ */ new Map());
+	return Array.from(reconciledMessages.values());
+}
+//#endregion
+//#region src/features/catalogue/path.ts
+function expandBucketOutputPath(bucket, locale, extension = bucket.formatter.extension) {
+	return (0, node_path.resolve)(bucket.output.replaceAll("{locale}", locale).replaceAll("{extension}", extension.slice(1)));
+}
+//#endregion
+//#region src/features/catalogue/storage.ts
+const DECLARATION_CONTENT = `
+declare const messages: Record<string, string>;
+export default messages;
+`.trim();
+async function readCatalogueMessages(bucket, locale, path = expandBucketOutputPath(bucket, locale)) {
+	const content = await (0, node_fs_promises.readFile)(path, "utf8").catch(() => "");
+	if (!content) return [];
+	return bucket.formatter.parse(content);
+}
+async function writeCatalogueMessages(bucket, locale, messages, path = expandBucketOutputPath(bucket, locale)) {
+	const existingContent = await (0, node_fs_promises.readFile)(path, "utf8").catch(() => void 0);
+	const catalogueContent = bucket.formatter.stringify(messages, {
+		locale,
+		existingContent
+	});
+	const declarationPath = `${path}.d.ts`;
+	await (0, node_fs_promises.mkdir)((0, node_path.dirname)(path), { recursive: true });
+	await Promise.all([(0, node_fs_promises.writeFile)(path, catalogueContent), (0, node_fs_promises.writeFile)(declarationPath, DECLARATION_CONTENT)]);
+}
+//#endregion
+Object.defineProperty(exports, "expandBucketOutputPath", {
+	enumerable: true,
+	get: function() {
+		return expandBucketOutputPath;
+	}
+});
+Object.defineProperty(exports, "mergeExtractedMessages", {
+	enumerable: true,
+	get: function() {
+		return mergeExtractedMessages;
+	}
+});
+Object.defineProperty(exports, "readCatalogueMessages", {
+	enumerable: true,
+	get: function() {
+		return readCatalogueMessages;
+	}
+});
+Object.defineProperty(exports, "reconcileLocaleMessages", {
+	enumerable: true,
+	get: function() {
+		return reconcileLocaleMessages;
+	}
+});
+Object.defineProperty(exports, "writeCatalogueMessages", {
+	enumerable: true,
+	get: function() {
+		return writeCatalogueMessages;
+	}
+});

package/dist/storage-C9nzxPtZ.mjs

@@ -0,0 +1,67 @@
+import { t as generateHash } from "./hash-DyC8GzMa.mjs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+//#region src/features/catalogue/merge.ts
+function mergeUnique(...items) {
+	return Array.from(new Set(items.flat()));
+}
+function getMessageKey(message) {
+	return message.id ?? generateHash(message.message, message.context);
+}
+function mergeExtractedMessages(messages) {
+	const mergedMessages = messages.reduce((map, message) => {
+		const key = getMessageKey(message);
+		const existing = map.get(key) ?? message;
+		map.set(key, {
+			...existing,
+			comments: mergeUnique(...existing.comments, ...message.comments),
+			references: mergeUnique(...existing.references, ...message.references)
+		});
+		return map;
+	}, /* @__PURE__ */ new Map());
+	return Array.from(mergedMessages.values());
+}
+function reconcileLocaleMessages(existingMessages, nextMessages) {
+	const existingMessagesByKey = existingMessages.reduce((map, message) => {
+		map.set(getMessageKey(message), message);
+		return map;
+	}, /* @__PURE__ */ new Map());
+	const reconciledMessages = nextMessages.reduce((map, message) => {
+		const key = getMessageKey(message);
+		const existingMessage = existingMessagesByKey.get(key);
+		map.set(key, {
+			...message,
+			translation: existingMessage?.translation
+		});
+		return map;
+	}, /* @__PURE__ */ new Map());
+	return Array.from(reconciledMessages.values());
+}
+//#endregion
+//#region src/features/catalogue/path.ts
+function expandBucketOutputPath(bucket, locale, extension = bucket.formatter.extension) {
+	return resolve(bucket.output.replaceAll("{locale}", locale).replaceAll("{extension}", extension.slice(1)));
+}
+//#endregion
+//#region src/features/catalogue/storage.ts
+const DECLARATION_CONTENT = `
+declare const messages: Record<string, string>;
+export default messages;
+`.trim();
+async function readCatalogueMessages(bucket, locale, path = expandBucketOutputPath(bucket, locale)) {
+	const content = await readFile(path, "utf8").catch(() => "");
+	if (!content) return [];
+	return bucket.formatter.parse(content);
+}
+async function writeCatalogueMessages(bucket, locale, messages, path = expandBucketOutputPath(bucket, locale)) {
+	const existingContent = await readFile(path, "utf8").catch(() => void 0);
+	const catalogueContent = bucket.formatter.stringify(messages, {
+		locale,
+		existingContent
+	});
+	const declarationPath = `${path}.d.ts`;
+	await mkdir(dirname(path), { recursive: true });
+	await Promise.all([writeFile(path, catalogueContent), writeFile(declarationPath, DECLARATION_CONTENT)]);
+}
+//#endregion
+export { reconcileLocaleMessages as a, mergeExtractedMessages as i, writeCatalogueMessages as n, expandBucketOutputPath as r, readCatalogueMessages as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saykit/config",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "CLI and configuration tooling for saykit",
   "keywords": [
     "cli",
@@ -37,6 +37,16 @@
         "default": "./dist/index.mjs"
       }
     },
+    "./features/catalogue": {
+      "require": {
+        "types": "./dist/features/catalogue/index.d.cts",
+        "default": "./dist/features/catalogue/index.cjs"
+      },
+      "import": {
+        "types": "./dist/features/catalogue/index.d.mts",
+        "default": "./dist/features/catalogue/index.mjs"
+      }
+    },
     "./features/loader": {
       "require": {
         "types": "./dist/features/loader/index.d.cts",
@@ -66,7 +76,7 @@
     "@commander-js/extra-typings": "^14.0.0",
     "commander": "^14.0.3",
     "js-sha256": "^0.11.1",
-    "picomatch": "^4.0.4",
+    "picomatch": "^4.0.5",
     "zod": "^4.4.3"
   },
   "devDependencies": {
@@ -82,8 +92,6 @@
   },
   "scripts": {
     "check": "tsc --noEmit",
-    "test": "vitest",
-    "coverage": "vitest run --coverage",
     "build": "tsdown"
   }
 }