@saykit/config 0.2.0 → 0.4.0

package/README.md

@@ -21,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'],
@@ -37,8 +43,21 @@ export default defineConfig({
 ```sh
 saykit extract           # extract messages once
 saykit extract --watch   # extract and watch for changes
+saykit clean             # prune dead entries from other locales
 ```
 
+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` only ever subtracts from non-source locales: it drops entries that no longer exist in
+the source catalogue and entries with an empty translation, and leaves everything else exactly as it
+is. It never adds source keys to a locale file, that stays your TMS's job.
+
 ## 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-C4rOvLGi.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,26 @@ 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("Remove orphaned and untranslated entries from non-source locale files").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(`Cleaning ${otherLocales.length} locale(s) against ${sourceLocale}`);
+		for (const locale of otherLocales) {
+			logger.step(`Cleaning ${locale}`);
+			const existingMessages = await require_storage.readCatalogueMessages(bucket, locale);
+			const prunedMessages = require_storage.pruneLocaleMessages(existingMessages, sourceMessages);
+			logger.step(`Removed ${existingMessages.length - prunedMessages.length} entries from ${locale}`);
+			await require_storage.writeCatalogueMessages(bucket, locale, prunedMessages);
+		}
+	}
+	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,74 +76,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)));
-}
-//#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
 //#region src/features/watch.ts
 /**
 * Expand a buckets include and exclude patterns into a flat list of file paths.
@@ -183,6 +135,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() {
@@ -212,13 +167,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}`);
 	}
@@ -248,5 +208,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 mergeExtractedMessages, i as expandBucketOutputPath, n as writeCatalogueMessages, o as pruneLocaleMessages, t as readCatalogueMessages } from "../storage-CqKPYfCR.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,26 @@ var Logger = class {
 };
 new AsyncLocalStorage({ defaultValue: new Logger() });
 //#endregion
+//#region src/commands/clean.ts
+var clean_default = new Command("clean").description("Remove orphaned and untranslated entries from non-source locale files").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(`Cleaning ${otherLocales.length} locale(s) against ${sourceLocale}`);
+		for (const locale of otherLocales) {
+			logger.step(`Cleaning ${locale}`);
+			const existingMessages = await readCatalogueMessages(bucket, locale);
+			const prunedMessages = pruneLocaleMessages(existingMessages, sourceMessages);
+			logger.step(`Removed ${existingMessages.length - prunedMessages.length} entries from ${locale}`);
+			await writeCatalogueMessages(bucket, locale, prunedMessages);
+		}
+	}
+	logger.success("Locales cleaned");
+});
+//#endregion
 //#region src/features/catalogue/extractor.ts
 async function extractMessagesFromFile(path, bucket) {
 	const content = await readFile(path, "utf8").catch(() => "");
@@ -55,74 +75,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)));
-}
-//#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
 //#region src/features/watch.ts
 /**
 * Expand a buckets include and exclude patterns into a flat list of file paths.
@@ -182,6 +134,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() {
@@ -212,12 +167,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}`);
 	}
@@ -247,6 +207,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,65 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+require("../../index.cjs");
+const require_hash = require("../../hash-8It7TJpB.cjs");
+const require_storage = require("../../storage-C4rOvLGi.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);
+			if (message.translation) {
+				record[key] = message.translation;
+				continue;
+			}
+			if (!record[key] && message.message) record[key] = message.message;
+		}
+	}
+	return record;
+}
+//#endregion
+exports.assembleCatalogueRecord = assembleCatalogueRecord;
+exports.declarationPathFor = require_storage.declarationPathFor;
+exports.expandBucketOutputPath = require_storage.expandBucketOutputPath;
+exports.mergeExtractedMessages = require_storage.mergeExtractedMessages;
+exports.pruneLocaleMessages = require_storage.pruneLocaleMessages;
+exports.readCatalogueMessages = require_storage.readCatalogueMessages;
+exports.resolveCatalogueSources = resolveCatalogueSources;
+exports.resolveFallbackChain = resolveFallbackChain;
+exports.writeCatalogueMessages = require_storage.writeCatalogueMessages;

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

@@ -0,0 +1,68 @@
+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 pruneLocaleMessages(existingMessages: Message[], sourceMessages: 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;
+/**
+ * The declaration file that types a catalogue, e.g. `en.json` -> `en.d.json.ts`.
+ *
+ * TypeScript resolves `./en.json` by stripping the extension and looking for
+ * `en.d.json.ts`; the `en.json.d.ts` form is only consulted for extensions the
+ * resolver does not recognise. Non-JS extensions additionally require
+ * `allowArbitraryExtensions` in the consumer's tsconfig.
+ */
+declare function declarationPathFor(cataloguePath: 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, declarationPathFor, expandBucketOutputPath, mergeExtractedMessages, pruneLocaleMessages, readCatalogueMessages, resolveCatalogueSources, resolveFallbackChain, writeCatalogueMessages };

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

@@ -0,0 +1,68 @@
+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 pruneLocaleMessages(existingMessages: Message[], sourceMessages: 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;
+/**
+ * The declaration file that types a catalogue, e.g. `en.json` -> `en.d.json.ts`.
+ *
+ * TypeScript resolves `./en.json` by stripping the extension and looking for
+ * `en.d.json.ts`; the `en.json.d.ts` form is only consulted for extensions the
+ * resolver does not recognise. Non-JS extensions additionally require
+ * `allowArbitraryExtensions` in the consumer's tsconfig.
+ */
+declare function declarationPathFor(cataloguePath: 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, declarationPathFor, expandBucketOutputPath, mergeExtractedMessages, pruneLocaleMessages, readCatalogueMessages, resolveCatalogueSources, resolveFallbackChain, writeCatalogueMessages };

package/dist/features/catalogue/index.mjs

@@ -0,0 +1,55 @@
+import { t as generateHash } from "../../hash-DyC8GzMa.mjs";
+import { a as mergeExtractedMessages, i as expandBucketOutputPath, n as writeCatalogueMessages, o as pruneLocaleMessages, r as declarationPathFor, t as readCatalogueMessages } from "../../storage-CqKPYfCR.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);
+			if (message.translation) {
+				record[key] = message.translation;
+				continue;
+			}
+			if (!record[key] && message.message) record[key] = message.message;
+		}
+	}
+	return record;
+}
+//#endregion
+export { assembleCatalogueRecord, declarationPathFor, expandBucketOutputPath, mergeExtractedMessages, pruneLocaleMessages, readCatalogueMessages, 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 }) {

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 }) {

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-C4rOvLGi.cjs

@@ -0,0 +1,103 @@
+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 pruneLocaleMessages(existingMessages, sourceMessages) {
+	const sourceKeys = new Set(sourceMessages.map(getMessageKey));
+	return existingMessages.filter((message) => sourceKeys.has(getMessageKey(message)) && Boolean(message.translation));
+}
+//#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)));
+}
+/**
+* The declaration file that types a catalogue, e.g. `en.json` -> `en.d.json.ts`.
+*
+* TypeScript resolves `./en.json` by stripping the extension and looking for
+* `en.d.json.ts`; the `en.json.d.ts` form is only consulted for extensions the
+* resolver does not recognise. Non-JS extensions additionally require
+* `allowArbitraryExtensions` in the consumer's tsconfig.
+*/
+function declarationPathFor(cataloguePath) {
+	const { dir, name, ext } = (0, node_path.parse)(cataloguePath);
+	return (0, node_path.resolve)(dir, `${name}.d${ext}.ts`);
+}
+//#endregion
+//#region src/features/catalogue/storage.ts
+const DECLARATION_CONTENT = `
+declare const messages: Record<string, string>;
+export default messages;
+`.trimStart();
+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 = declarationPathFor(path);
+	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, "declarationPathFor", {
+	enumerable: true,
+	get: function() {
+		return declarationPathFor;
+	}
+});
+Object.defineProperty(exports, "expandBucketOutputPath", {
+	enumerable: true,
+	get: function() {
+		return expandBucketOutputPath;
+	}
+});
+Object.defineProperty(exports, "mergeExtractedMessages", {
+	enumerable: true,
+	get: function() {
+		return mergeExtractedMessages;
+	}
+});
+Object.defineProperty(exports, "pruneLocaleMessages", {
+	enumerable: true,
+	get: function() {
+		return pruneLocaleMessages;
+	}
+});
+Object.defineProperty(exports, "readCatalogueMessages", {
+	enumerable: true,
+	get: function() {
+		return readCatalogueMessages;
+	}
+});
+Object.defineProperty(exports, "writeCatalogueMessages", {
+	enumerable: true,
+	get: function() {
+		return writeCatalogueMessages;
+	}
+});

package/dist/storage-CqKPYfCR.mjs

@@ -0,0 +1,67 @@
+import { t as generateHash } from "./hash-DyC8GzMa.mjs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, parse, 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 pruneLocaleMessages(existingMessages, sourceMessages) {
+	const sourceKeys = new Set(sourceMessages.map(getMessageKey));
+	return existingMessages.filter((message) => sourceKeys.has(getMessageKey(message)) && Boolean(message.translation));
+}
+//#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)));
+}
+/**
+* The declaration file that types a catalogue, e.g. `en.json` -> `en.d.json.ts`.
+*
+* TypeScript resolves `./en.json` by stripping the extension and looking for
+* `en.d.json.ts`; the `en.json.d.ts` form is only consulted for extensions the
+* resolver does not recognise. Non-JS extensions additionally require
+* `allowArbitraryExtensions` in the consumer's tsconfig.
+*/
+function declarationPathFor(cataloguePath) {
+	const { dir, name, ext } = parse(cataloguePath);
+	return resolve(dir, `${name}.d${ext}.ts`);
+}
+//#endregion
+//#region src/features/catalogue/storage.ts
+const DECLARATION_CONTENT = `
+declare const messages: Record<string, string>;
+export default messages;
+`.trimStart();
+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 = declarationPathFor(path);
+	await mkdir(dirname(path), { recursive: true });
+	await Promise.all([writeFile(path, catalogueContent), writeFile(declarationPath, DECLARATION_CONTENT)]);
+}
+//#endregion
+export { mergeExtractedMessages as a, expandBucketOutputPath as i, writeCatalogueMessages as n, pruneLocaleMessages as o, declarationPathFor as r, readCatalogueMessages as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saykit/config",
-  "version": "0.2.0",
+  "version": "0.4.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",