@vouchington/localization-compiler 0.0.2 → 0.1.0

package/README.md

@@ -1,15 +1,20 @@
 # @vouchington/localization-compiler
 
-Node-only compiler for `@vouchington/localization`. It validates namespace-sharded JSON catalogs,
-requires complete `en-US` with sparse partial locales, emits an immutable read-only SQLite
-artifact, and exposes the same consumer/locale/selector resolver used by application CLIs.
+Node-only compiler for `@vouchington/localization`. It validates row-based JSON catalogs, requires
+complete `en-US` with sparse partial locales, emits an immutable read-only SQLite artifact, and
+exposes the same consumer/locale/selector resolver used by application CLIs.
 
-Catalog shards must be a JSON array with one compact message per line (`id` first, sorted).
-`compile` rejects any other layout. Line tools never parse the shard as a JSON document:
+Catalog source has three canonical tables: `copies.json` (`{ id, descriptor }`), `aliases.json`
+(`{ consumer, alias, copyId }`), and `translations/<locale>.json` (`{ id, value }`). A generated
+`routes.json` table maps `{ consumer, selectorId, alias }`, allowing route selectors to return the
+existing alias-keyed v1 payload without tying copy ids to source locations. Full plural and
+select-plural translation values remain values in the locale table.
 
 ```bash
-vouchington-localization upsert --file localization/catalog/common.json --message '{"id":"common.ok","consumers":["web"],"descriptor":null,"translations":{"en-US":"OK"}}'
-vouchington-localization remove --file localization/catalog/common.json --id common.ok
+vouchington-localization upsert --file localization/catalog/copies.json --row '{"id":"copy.ok","descriptor":null}'
+vouchington-localization upsert --file localization/catalog/aliases.json --row '{"consumer":"web","alias":"web.common.ok","copyId":"copy.ok"}'
+vouchington-localization upsert --file localization/catalog/translations/en-US.json --row '{"id":"copy.ok","value":"OK"}'
+vouchington-localization remove --file localization/catalog/aliases.json --id web.common.ok --consumer web
 vouchington-localization format --source localization/catalog
 ```
 

package/dist/catalog-csv.d.mts

@@ -0,0 +1,3 @@
+import { type LocalizationCatalog } from '@vouchington/localization';
+export declare function exportCatalogCsv(catalog: LocalizationCatalog): string;
+export declare function importCatalogCsv(csv: string, expectedRevision?: string): LocalizationCatalog;

package/dist/catalog-csv.mjs

@@ -0,0 +1,55 @@
+import { parseCsvRows, stringifyCsvRows } from '@vouchington/csv';
+import { canonicalJson } from '@vouchington/localization';
+import { sortedCatalog } from './catalog.mjs';
+import { catalogRevision } from './revision.mjs';
+const columns = [
+    'id',
+    'locale',
+    'descriptor_json',
+    'aliases_json',
+    'value_json',
+    'catalog_revision',
+];
+export function exportCatalogCsv(catalog) {
+    const source = sortedCatalog(catalog);
+    const revision = catalogRevision(source);
+    return stringifyCsvRows(Object.entries(source.translations).flatMap(([locale, rows]) => rows.map((row) => ({
+        id: row.id,
+        locale,
+        descriptor_json: canonicalJson(source.copies.find((copy) => copy.id === row.id).descriptor),
+        aliases_json: canonicalJson(source.aliases
+            .filter((alias) => alias.copyId === row.id)
+            .map(({ consumer, alias }) => ({ consumer, alias }))),
+        value_json: canonicalJson(row.value),
+        catalog_revision: revision,
+    }))), columns);
+}
+export function importCatalogCsv(csv, expectedRevision) {
+    const [header, ...rows] = parseCsvRows(csv);
+    if (header?.join(',') !== columns.join(','))
+        throw new TypeError('CSV header must match the localization interchange contract');
+    const copies = new Map();
+    const aliases = new Map();
+    const translations = {};
+    let revision;
+    for (const row of rows) {
+        const [id, locale, descriptor, aliasJson, value, current] = row;
+        if (revision !== undefined && revision !== current)
+            throw new TypeError('CSV rows must share a single catalog_revision');
+        revision = current;
+        copies.set(id, { id, descriptor: JSON.parse(descriptor) });
+        for (const alias of JSON.parse(aliasJson))
+            aliases.set(`${alias.consumer}\t${alias.alias}`, { ...alias, copyId: id });
+        (translations[locale] ??= []).push({ id, value: JSON.parse(value) });
+    }
+    const catalog = sortedCatalog({
+        copies: [...copies.values()],
+        aliases: [...aliases.values()],
+        translations: translations,
+    });
+    if (expectedRevision !== undefined && revision !== expectedRevision)
+        throw new TypeError('CSV catalog_revision does not match the source contract hash');
+    if (revision !== catalogRevision(catalog))
+        throw new TypeError('CSV catalog_revision does not match reconstructed catalog');
+    return catalog;
+}

package/dist/catalog.d.mts

@@ -0,0 +1,3 @@
+import { type LocalizationCatalog } from '@vouchington/localization';
+export declare function validateLocalizationCatalog(catalog: LocalizationCatalog): void;
+export declare function sortedCatalog(catalog: LocalizationCatalog): LocalizationCatalog;

package/dist/catalog.mjs

@@ -0,0 +1,71 @@
+import { CANONICAL_SOURCE_LOCALE, ENGLISH_LOCALE_ALIAS, compareCodePoints, consumerAliasFromRecord, isMessageId, normalizeLocale, routeSelectorMembershipFromRecord, translationRowFromRecord, } from '@vouchington/localization';
+import { validateCatalogMessages } from './validate.mjs';
+export function validateLocalizationCatalog(catalog) {
+    const copies = new Map(catalog.copies.map((copy) => [copy.id, copy]));
+    if (copies.size !== catalog.copies.length)
+        throw new TypeError('Duplicate copy id');
+    const aliases = new Set();
+    for (const raw of catalog.aliases) {
+        const alias = consumerAliasFromRecord(raw);
+        if (!copies.has(alias.copyId))
+            throw new TypeError(`Alias "${alias.alias}" targets missing copy "${alias.copyId}"`);
+        const key = `${alias.consumer}\t${alias.alias}`;
+        if (aliases.has(key))
+            throw new TypeError(`Duplicate alias "${alias.alias}" for ${alias.consumer}`);
+        aliases.add(key);
+    }
+    const translated = new Map();
+    for (const [locale, rows] of Object.entries(catalog.translations)) {
+        const normalized = normalizeLocale(locale);
+        if (normalized === null || locale === ENGLISH_LOCALE_ALIAS || locale !== normalized) {
+            throw new TypeError(`Locale "${locale}" must be stored as ${normalized}`);
+        }
+        const values = new Map();
+        for (const raw of rows) {
+            const row = translationRowFromRecord(raw);
+            if (!copies.has(row.id))
+                throw new TypeError(`Translation targets missing copy "${row.id}"`);
+            if (values.has(row.id))
+                throw new TypeError(`Duplicate translation for "${row.id}" in ${locale}`);
+            values.set(row.id, row.value);
+        }
+        translated.set(locale, values);
+    }
+    const english = translated.get(CANONICAL_SOURCE_LOCALE);
+    for (const copy of copies.values()) {
+        if (!english?.has(copy.id))
+            throw new TypeError(`Copy "${copy.id}" is missing ${CANONICAL_SOURCE_LOCALE}`);
+    }
+    validateCatalogMessages([...copies.values()].map((copy) => ({
+        ...copy,
+        consumers: ['web'],
+        translations: Object.fromEntries([...translated.entries()].flatMap(([locale, rows]) => rows.has(copy.id) ? [[locale, rows.get(copy.id)]] : [])),
+    })));
+    const membership = new Set();
+    for (const raw of catalog.routeMembership ?? []) {
+        const row = routeSelectorMembershipFromRecord(raw);
+        if (!aliases.has(`${row.consumer}\t${row.alias}`)) {
+            throw new TypeError(`Route selector "${row.selectorId}" targets missing alias "${row.alias}"`);
+        }
+        const key = `${row.consumer}\t${row.selectorId}\t${row.alias}`;
+        if (membership.has(key))
+            throw new TypeError(`Duplicate route membership "${row.selectorId}" → "${row.alias}"`);
+        membership.add(key);
+    }
+    for (const id of Object.keys(catalog.tags ?? {}))
+        if (!copies.has(id) || !isMessageId(id))
+            throw new TypeError(`Editorial tag target "${id}" is not in the catalog`);
+}
+export function sortedCatalog(catalog) {
+    validateLocalizationCatalog(catalog);
+    return {
+        copies: [...catalog.copies].toSorted((a, b) => compareCodePoints(a.id, b.id)),
+        aliases: [...catalog.aliases].toSorted((a, b) => compareCodePoints(`${a.consumer}\t${a.alias}`, `${b.consumer}\t${b.alias}`)),
+        translations: Object.fromEntries(Object.entries(catalog.translations).map(([locale, rows]) => [
+            locale,
+            [...rows].toSorted((a, b) => compareCodePoints(a.id, b.id)),
+        ])),
+        routeMembership: [...(catalog.routeMembership ?? [])].toSorted((a, b) => compareCodePoints(`${a.consumer}\t${a.selectorId}\t${a.alias}`, `${b.consumer}\t${b.selectorId}\t${b.alias}`)),
+        tags: catalog.tags ?? {},
+    };
+}

package/dist/cli-shard.mjs

@@ -1,66 +1,87 @@
 import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
-import { CatalogMergeConflict, mergeCatalogShards, parseCatalogShardText, removeCatalogLine, serializeCatalogShard, upsertCatalogLine, } from '@vouchington/localization';
+import { CatalogMergeConflict, mergeCatalogShards, parseCatalogShardText, removeCatalogLine, serializeCatalogTable, serializeCatalogShard, upsertCatalogLine, } from '@vouchington/localization';
+import { isTablePath, mergeTableFiles, readTable, removeTable, upsertTable } from './table-cli.mjs';
 import { parseCatalogFile } from './validate.mjs';
 export function runShardCli(command, args) {
-    if (command === 'upsert') {
-        const path = requiredPath(args, '--file');
-        mkdirSync(dirname(path), { recursive: true });
-        writeFileSync(path, upsertCatalogLine(readShard(path), required(args, '--message')));
+    if (command === 'upsert')
+        return upsert(args);
+    if (command === 'remove')
+        return remove(args);
+    if (command === 'git-merge')
+        return merge(args);
+    if (command === 'format')
+        return formatCatalogDirectory(required(args, '--source'));
+    throw new TypeError(shardUsage());
+}
+function upsert(args) {
+    const path = requiredPath(args, '--file');
+    if (isTablePath(path))
+        return upsertTable(path, optional(args, '--row') ?? required(args, '--message'));
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, upsertCatalogLine(readShard(path), required(args, '--message')));
+}
+function remove(args) {
+    const path = requiredPath(args, '--file');
+    if (isTablePath(path))
+        return removeTable(path, required(args, '--id'), optional(args, '--consumer'));
+    writeFileSync(path, removeCatalogLine(readFileSync(path, 'utf8'), required(args, '--id')));
+}
+function merge(args) {
+    const [ancestor, ours, theirs] = args;
+    if (ancestor === undefined || ours === undefined || theirs === undefined)
+        throw new TypeError(shardUsage());
+    if (isTablePath(ours)) {
+        mergeTableFiles(ancestor, ours, theirs);
         return undefined;
     }
-    if (command === 'remove') {
-        const path = requiredPath(args, '--file');
-        writeFileSync(path, removeCatalogLine(readFileSync(path, 'utf8'), required(args, '--id')));
-        return undefined;
+    try {
+        writeFileSync(ours, mergeCatalogShards(readFileSync(ancestor, 'utf8'), readFileSync(ours, 'utf8'), readFileSync(theirs, 'utf8')));
     }
-    if (command === 'git-merge') {
-        const [ancestor, ours, theirs] = args;
-        if (ancestor === undefined || ours === undefined || theirs === undefined) {
-            throw new TypeError(shardUsage());
-        }
-        try {
-            writeFileSync(ours, mergeCatalogShards(readFileSync(ancestor, 'utf8'), readFileSync(ours, 'utf8'), readFileSync(theirs, 'utf8')));
-        }
-        catch (error) {
-            if (error instanceof CatalogMergeConflict)
-                writeFileSync(ours, error.text);
-            throw error;
-        }
-        return undefined;
+    catch (error) {
+        if (error instanceof CatalogMergeConflict)
+            writeFileSync(ours, error.text);
+        throw error;
     }
-    if (command === 'format')
-        return formatCatalogDirectory(required(args, '--source'));
-    throw new TypeError(shardUsage());
 }
 export function shardUsage() {
     return [
-        'Usage: vouchington-localization upsert --file <file> --message <json>',
-        'Usage: vouchington-localization remove --file <file> --id <id>',
+        'Usage: vouchington-localization upsert --file <file> --row <json>',
+        'Usage: vouchington-localization remove --file <file> --id <id> [--consumer <consumer>]',
         'Usage: vouchington-localization git-merge <ancestor> <ours> <theirs>',
         'Usage: vouchington-localization format --source <dir>',
     ].join('\n');
 }
 function formatCatalogDirectory(directory) {
     const names = readdirSync(directory).filter((name) => name.endsWith('.json') && name !== 'tags.json');
-    for (const name of names) {
-        const path = join(directory, name);
-        try {
-            writeFileSync(path, serializeCatalogShard(messagesFromUnknownText(readFileSync(path, 'utf8'))));
-        }
-        catch (error) {
-            throw new TypeError(`${path}: ${error.message}`);
-        }
-    }
+    for (const name of names)
+        formatFile(join(directory, name));
+    const translations = join(directory, 'translations');
+    if (existsSync(translations))
+        for (const name of readdirSync(translations).filter((name) => name.endsWith('.json')))
+            formatFile(join(translations, name));
     return `${names.length} files`;
 }
+function formatFile(path) {
+    try {
+        if (isTablePath(path))
+            return writeFileSync(path, serializeCatalogTable(readTable(path)));
+        writeFileSync(path, serializeCatalogShard(messagesFromUnknownText(readFileSync(path, 'utf8'))));
+    }
+    catch (error) {
+        throw new TypeError(`${path}: ${error.message}`);
+    }
+}
 function required(args, flag) {
-    const index = args.indexOf(flag);
-    const value = index === -1 ? undefined : args[index + 1];
-    if (value === undefined || value.startsWith('--'))
+    const value = optional(args, flag);
+    if (value === undefined)
         throw new TypeError(shardUsage());
     return value;
 }
+function optional(args, flag) {
+    const value = args[args.indexOf(flag) + 1];
+    return value === undefined || value.startsWith('--') ? undefined : value;
+}
 function requiredPath(args, flag) {
     return resolve(required(args, flag));
 }

package/dist/cli.mjs

@@ -2,8 +2,8 @@ import { mkdirSync, writeFileSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { serializeLocalizationBatch } from '@vouchington/localization';
-import { compileLocalizationSqlite, writeJsonCatalog } from './compile.mjs';
-import { exportLocalizationCsv, importLocalizationCsv } from './csv.mjs';
+import { compileLocalizationSqlite } from './compile.mjs';
+import { exportCatalogCsv, importCatalogCsv } from './catalog-csv.mjs';
 import { loadCatalogDirectory } from './load.mjs';
 import { openLocalizationDatabase } from './open.mjs';
 import { explainLocalizationPlan, resolveLocalizationBatch } from './resolve.mjs';
@@ -21,7 +21,7 @@ export async function runLocalizationCli(argv, write = console.log) {
     }
     if (command === 'compile') {
         const loaded = await loadCatalogDirectory(required(rest, '--source'));
-        write(compileLocalizationSqlite(loaded.messages, required(rest, '--output'), loaded.tags));
+        write(compileLocalizationSqlite(loaded.catalog, required(rest, '--output')));
         return;
     }
     if (command === 'resolve') {
@@ -42,7 +42,7 @@ export async function runLocalizationCli(argv, write = console.log) {
         return;
     }
     if (command === 'csv-export') {
-        const csv = exportLocalizationCsv((await loadCatalogDirectory(required(rest, '--source'))).messages);
+        const csv = exportCatalogCsv((await loadCatalogDirectory(required(rest, '--source'))).catalog);
         const output = optional(rest, '--output');
         if (output === undefined)
             write(csv);
@@ -53,11 +53,21 @@ export async function runLocalizationCli(argv, write = console.log) {
     if (command === 'csv-import') {
         const output = required(rest, '--output');
         mkdirSync(output, { recursive: true });
-        writeJsonCatalog(importLocalizationCsv(await readFile(required(rest, '--input'), 'utf8')), resolve(output, 'imported.json'));
+        const catalog = importCatalogCsv(await readFile(required(rest, '--input'), 'utf8'));
+        writeCatalogSource(output, catalog);
         return;
     }
     throw new TypeError(usage());
 }
+function writeCatalogSource(output, catalog) {
+    writeFileSync(resolve(output, 'imported.json'), JSON.stringify(catalog));
+    writeFileSync(resolve(output, 'copies.json'), JSON.stringify(catalog.copies));
+    writeFileSync(resolve(output, 'aliases.json'), JSON.stringify(catalog.aliases));
+    const translations = resolve(output, 'translations');
+    mkdirSync(translations, { recursive: true });
+    for (const [locale, rows] of Object.entries(catalog.translations))
+        writeFileSync(resolve(translations, `${locale}.json`), JSON.stringify(rows));
+}
 function withDatabase(path, run) {
     const database = openLocalizationDatabase(path);
     try {

package/dist/compile.d.mts

@@ -1,4 +1,3 @@
-import { type CatalogMessage } from '@vouchington/localization';
+import { type LocalizationCatalog, type CatalogMessage } from '@vouchington/localization';
 import type { EditorialTags } from './load.mts';
-export declare function compileLocalizationSqlite(messages: readonly CatalogMessage[], outputPath: string, tags?: EditorialTags): string;
-export declare function writeJsonCatalog(messages: readonly CatalogMessage[], path: string): void;
+export declare function compileLocalizationSqlite(source: LocalizationCatalog | readonly CatalogMessage[], outputPath: string, tags?: EditorialTags): string;

package/dist/compile.mjs

@@ -1,15 +1,19 @@
-import { mkdirSync, mkdtempSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { mkdirSync, mkdtempSync, renameSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { DatabaseSync } from 'node:sqlite';
-import { canonicalJson, compareCodePoints, LOCALIZATION_WIRE_CONTRACT, serializeCatalogShard, } from '@vouchington/localization';
+import { canonicalJson, catalogFromMessages, compareCodePoints, LOCALIZATION_WIRE_CONTRACT, } from '@vouchington/localization';
 import { assertSqliteIntegrity } from './integrity.mjs';
 import { catalogRevision } from './revision.mjs';
 import { SQLITE_SCHEMA } from './schema.mjs';
 import { validateCatalogMessages } from './validate.mjs';
-export function compileLocalizationSqlite(messages, outputPath, tags = {}) {
-    validateCatalogMessages(messages);
-    const revision = catalogRevision(messages);
+import { sortedCatalog } from './catalog.mjs';
+export function compileLocalizationSqlite(source, outputPath, tags = {}) {
+    const catalog = isCatalog(source) ? source : { ...catalogFromMessages(source), tags };
+    if (!isCatalog(source))
+        validateCatalogMessages(source);
+    const normalized = sortedCatalog(catalog);
+    const revision = catalogRevision(normalized);
     mkdirSync(dirname(outputPath), { recursive: true });
     const temporaryDirectory = mkdtempSync(join(tmpdir(), 'localization-'));
     const temporary = join(temporaryDirectory, 'catalog.sqlite');
@@ -18,8 +22,7 @@ export function compileLocalizationSqlite(messages, outputPath, tags = {}) {
         database.exec('PRAGMA journal_mode = OFF');
         database.exec(SQLITE_SCHEMA);
         insertMetadata(database, revision);
-        insertMessages(database, messages);
-        insertTags(database, tags);
+        insertCatalog(database, normalized);
         database.exec('PRAGMA foreign_keys = ON');
         assertSqliteIntegrity(database);
     }
@@ -30,31 +33,31 @@ export function compileLocalizationSqlite(messages, outputPath, tags = {}) {
     rmSync(temporaryDirectory, { recursive: true, force: true });
     return revision;
 }
-export function writeJsonCatalog(messages, path) {
-    writeFileSync(path, serializeCatalogShard(messages));
+function isCatalog(source) {
+    return !Array.isArray(source) || Object.hasOwn(source, 'copies');
 }
 function insertMetadata(database, revision) {
     const insert = database.prepare('INSERT INTO metadata (key, value) VALUES (?, ?)');
     insert.run('contract', LOCALIZATION_WIRE_CONTRACT);
     insert.run('revision', revision);
 }
-function insertMessages(database, messages) {
-    const insertMessage = database.prepare('INSERT INTO messages (id, descriptor_json) VALUES (?, ?)');
-    const insertTranslation = database.prepare('INSERT INTO translations (locale, message_id, value_json) VALUES (?, ?, ?)');
-    const insertConsumer = database.prepare('INSERT INTO consumer_membership (consumer, message_id) VALUES (?, ?)');
-    for (const message of [...messages].toSorted((left, right) => compareCodePoints(left.id, right.id))) {
-        insertMessage.run(message.id, canonicalJson(message.descriptor));
-        for (const consumer of message.consumers)
-            insertConsumer.run(consumer, message.id);
-        for (const locale of Object.keys(message.translations).toSorted(compareCodePoints)) {
-            insertTranslation.run(locale, message.id, canonicalJson(message.translations[locale]));
-        }
-    }
-}
-function insertTags(database, tags) {
-    const insert = database.prepare('INSERT INTO editorial_tags (message_id, tag) VALUES (?, ?)');
-    for (const id of Object.keys(tags).toSorted(compareCodePoints)) {
-        for (const tag of tags[id])
-            insert.run(id, tag);
+function insertCatalog(database, catalog) {
+    const insertCopy = database.prepare('INSERT INTO copies (id, descriptor_json) VALUES (?, ?)');
+    const insertTranslation = database.prepare('INSERT INTO translations (locale, copy_id, value_json) VALUES (?, ?, ?)');
+    const insertAlias = database.prepare('INSERT INTO consumer_aliases (consumer, alias, copy_id) VALUES (?, ?, ?)');
+    const insertRoute = database.prepare('INSERT INTO route_membership (consumer, selector_id, alias) VALUES (?, ?, ?)');
+    const insertTag = database.prepare('INSERT INTO editorial_tags (copy_id, tag) VALUES (?, ?)');
+    for (const copy of catalog.copies)
+        insertCopy.run(copy.id, canonicalJson(copy.descriptor));
+    for (const alias of catalog.aliases)
+        insertAlias.run(alias.consumer, alias.alias, alias.copyId);
+    for (const route of catalog.routeMembership)
+        insertRoute.run(route.consumer, route.selectorId, route.alias);
+    for (const [locale, rows] of Object.entries(catalog.translations)) {
+        for (const row of rows)
+            insertTranslation.run(locale, row.id, canonicalJson(row.value));
     }
+    for (const id of Object.keys(catalog.tags).toSorted(compareCodePoints))
+        for (const tag of catalog.tags[id])
+            insertTag.run(id, tag);
 }

package/dist/index.d.mts

@@ -5,5 +5,7 @@ export { openLocalizationDatabase, type LocalizationDatabase } from './open.mts'
 export { explainLocalizationPlan, resolveLocalizationBatch } from './resolve.mts';
 export { nativeLeafVariants, renderDotnetDescriptors, renderDotnetKeys, renderResx, renderSwiftDescriptors, renderSwiftKeys, renderSwiftStrings, } from './native.mts';
 export { catalogRevision } from './revision.mts';
+export { validateLocalizationCatalog, sortedCatalog } from './catalog.mts';
+export { exportCatalogCsv, importCatalogCsv } from './catalog-csv.mts';
 export { validateCatalogMessages, parseCatalogFile } from './validate.mts';
 export { runLocalizationCli } from './cli.mts';

package/dist/index.mjs

@@ -5,5 +5,7 @@ export { openLocalizationDatabase } from './open.mjs';
 export { explainLocalizationPlan, resolveLocalizationBatch } from './resolve.mjs';
 export { nativeLeafVariants, renderDotnetDescriptors, renderDotnetKeys, renderResx, renderSwiftDescriptors, renderSwiftKeys, renderSwiftStrings, } from './native.mjs';
 export { catalogRevision } from './revision.mjs';
+export { validateLocalizationCatalog, sortedCatalog } from './catalog.mjs';
+export { exportCatalogCsv, importCatalogCsv } from './catalog-csv.mjs';
 export { validateCatalogMessages, parseCatalogFile } from './validate.mjs';
 export { runLocalizationCli } from './cli.mjs';

package/dist/load.d.mts

@@ -1,6 +1,8 @@
-import { type CatalogMessage } from '@vouchington/localization';
+import { type LocalizationCatalog } from '@vouchington/localization';
 export type EditorialTags = Readonly<Record<string, readonly string[]>>;
 export declare function loadCatalogDirectory(directory: string): Promise<{
-    messages: CatalogMessage[];
+    catalog: LocalizationCatalog;
+    /** @deprecated use catalog; retained for the 0.x compiler adapter. */
+    messages: never[];
     tags: EditorialTags;
 }>;

package/dist/load.mjs

@@ -1,28 +1,82 @@
 import { readdir, readFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { compareCodePoints, parseCatalogShardText, } from '@vouchington/localization';
-import { validateCatalogMessages } from './validate.mjs';
+import { catalogFromMessages, compareCodePoints, parseCatalogShardText, } from '@vouchington/localization';
+import { sortedCatalog } from './catalog.mjs';
 export async function loadCatalogDirectory(directory) {
-    const names = (await readdir(directory))
-        .filter((name) => name.endsWith('.json'))
-        .toSorted(compareCodePoints);
+    const names = (await readdir(directory)).toSorted(compareCodePoints);
     if (names.length === 0)
         throw new TypeError(`No catalog JSON files in "${directory}"`);
-    const messages = [];
+    if (!names.some((name) => name.endsWith('.json')))
+        throw new TypeError(`No catalog JSON files in "${directory}"`);
+    const copies = await optionalRows(directory, 'copies.json');
+    const aliases = await optionalRows(directory, 'aliases.json');
+    const routeMembership = (await optionalRows(directory, 'routes.json')) ?? [];
+    const translations = copies !== undefined && aliases !== undefined ? await translationRows(directory) : {};
     let tags = {};
+    const legacy = [];
     for (const name of names) {
+        if (!name.endsWith('.json'))
+            continue;
+        if (name === 'copies.json' || name === 'aliases.json' || name === 'routes.json')
+            continue;
         const text = await readFile(join(directory, name), 'utf8');
         if (name === 'tags.json') {
             tags = parseTags(JSON.parse(text));
             continue;
         }
-        messages.push(...parseCatalogShardText(text));
+        if (copies === undefined || aliases === undefined)
+            legacy.push(...parseCatalogShardText(text));
+    }
+    if (copies === undefined || aliases === undefined) {
+        if (legacy.length === 0)
+            throw new TypeError(`No catalog messages in "${directory}"`);
+        return {
+            catalog: sortedCatalog({ ...catalogFromMessages(legacy), tags }),
+            messages: legacy,
+            tags,
+        };
+    }
+    const catalog = sortedCatalog({
+        copies: copies,
+        aliases: aliases,
+        translations: translations,
+        routeMembership: routeMembership,
+        tags,
+    });
+    return { catalog, messages: [], tags };
+}
+async function translationRows(directory) {
+    const path = join(directory, 'translations');
+    let names;
+    try {
+        names = await readdir(path);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            throw new TypeError('Catalog is missing translations/');
+        throw error;
+    }
+    const translations = {};
+    for (const name of names.filter((name) => name.endsWith('.json')).toSorted(compareCodePoints)) {
+        const value = JSON.parse(await readFile(join(path, name), 'utf8'));
+        if (!Array.isArray(value))
+            throw new TypeError(`translations/${name} must be a JSON array`);
+        translations[name.slice(0, -5)] = value;
+    }
+    return translations;
+}
+async function optionalRows(directory, name) {
+    try {
+        const value = JSON.parse(await readFile(join(directory, name), 'utf8'));
+        if (!Array.isArray(value))
+            throw new TypeError(`${name} must be a JSON array`);
+        return value;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
     }
-    if (messages.length === 0)
-        throw new TypeError(`No catalog messages in "${directory}"`);
-    validateCatalogMessages(messages);
-    validateTagTargets(messages, tags);
-    return { messages, tags };
 }
 function parseTags(value) {
     if (typeof value !== 'object' || value === null || Array.isArray(value)) {
@@ -35,10 +89,3 @@ function parseTags(value) {
         return [id, [...new Set(tags)].toSorted(compareCodePoints)];
     }));
 }
-function validateTagTargets(messages, tags) {
-    const ids = new Set(messages.map((message) => message.id));
-    for (const id of Object.keys(tags)) {
-        if (!ids.has(id))
-            throw new TypeError(`Editorial tag target "${id}" is not in the catalog`);
-    }
-}

package/dist/resolve.mjs

@@ -3,22 +3,22 @@ import { DEFAULT_TTL_SECONDS } from './schema.mjs';
 export function resolveLocalizationBatch(database, request, options = {}) {
     const normalized = normalizeLocalizationRequest(request, options.availableLocales, options.bounds);
     const rows = loadRows(database, normalized.consumer, normalized.selectors);
-    const byId = new Map();
+    const byAlias = new Map();
     for (const row of rows) {
-        const current = byId.get(row.id) ?? {
+        const current = byAlias.get(row.alias) ?? {
             descriptor: parseDescriptor(JSON.parse(row.descriptor_json)),
             translations: {},
         };
         current.translations[row.locale] = JSON.parse(row.value_json);
-        byId.set(row.id, current);
+        byAlias.set(row.alias, current);
     }
     const messages = {};
-    for (const id of [...byId.keys()].toSorted(compareCodePoints)) {
-        const entry = byId.get(id);
+    for (const alias of [...byAlias.keys()].toSorted(compareCodePoints)) {
+        const entry = byAlias.get(alias);
         const value = firstAvailableTranslation(normalized.locales, entry.translations);
         if (value === undefined)
             continue;
-        messages[id] = leafForTranslation(entry.descriptor, value);
+        messages[alias] = leafForTranslation(entry.descriptor, value);
     }
     assertMessageCount(Object.keys(messages).length, options.bounds ?? DEFAULT_LOCALIZATION_BOUNDS);
     const batch = createLocalizationBatch(database.revision, options.ttlSeconds ?? DEFAULT_TTL_SECONDS, messages);
@@ -27,8 +27,8 @@ export function resolveLocalizationBatch(database, request, options = {}) {
 }
 export function explainLocalizationPlan(database, selector) {
     const sql = selector.kind === 'exact'
-        ? `EXPLAIN QUERY PLAN SELECT m.id FROM consumer_membership c JOIN messages m ON m.id = c.message_id WHERE c.consumer = 'web' AND m.id = ?`
-        : `EXPLAIN QUERY PLAN SELECT m.id FROM consumer_membership c JOIN messages m ON m.id = c.message_id WHERE c.consumer = 'web' AND m.id >= ? AND m.id < ?`;
+        ? `EXPLAIN QUERY PLAN SELECT a.alias FROM consumer_aliases a WHERE a.consumer = 'web' AND a.alias = ?`
+        : `EXPLAIN QUERY PLAN SELECT r.alias FROM route_membership r WHERE r.consumer = 'web' AND r.selector_id >= ? AND r.selector_id < ?`;
     const statement = database.sqlite.prepare(sql);
     const rows = selector.kind === 'exact'
         ? statement.all(selector.id)
@@ -36,21 +36,28 @@ export function explainLocalizationPlan(database, selector) {
     return rows.map((row) => canonicalJson(row)).join('\n');
 }
 function loadRows(database, consumer, selectors) {
-    const exact = database.sqlite.prepare(`SELECT m.id, t.locale, m.descriptor_json, t.value_json
-     FROM consumer_membership c
-     JOIN messages m ON m.id = c.message_id
-     JOIN translations t ON t.message_id = m.id
-     WHERE c.consumer = ? AND m.id = ?`);
-    const prefix = database.sqlite.prepare(`SELECT m.id, t.locale, m.descriptor_json, t.value_json
-     FROM consumer_membership c
-     JOIN messages m ON m.id = c.message_id
-     JOIN translations t ON t.message_id = m.id
-     WHERE c.consumer = ? AND m.id >= ? AND m.id < ?`);
+    const exact = database.sqlite.prepare(`SELECT DISTINCT a.alias, t.locale, c.descriptor_json, t.value_json
+     FROM consumer_aliases a JOIN copies c ON c.id = a.copy_id
+     JOIN translations t ON t.copy_id = c.id
+     WHERE a.consumer = ? AND a.alias = ?
+     UNION
+     SELECT a.alias, t.locale, c.descriptor_json, t.value_json
+     FROM route_membership r JOIN consumer_aliases a ON a.consumer = r.consumer AND a.alias = r.alias
+     JOIN copies c ON c.id = a.copy_id JOIN translations t ON t.copy_id = c.id
+     WHERE r.consumer = ? AND r.selector_id = ?`);
+    const prefix = database.sqlite.prepare(`SELECT DISTINCT a.alias, t.locale, c.descriptor_json, t.value_json
+     FROM route_membership r JOIN consumer_aliases a ON a.consumer = r.consumer AND a.alias = r.alias
+     JOIN copies c ON c.id = a.copy_id JOIN translations t ON t.copy_id = c.id
+     WHERE r.consumer = ? AND r.selector_id >= ? AND r.selector_id < ?
+     UNION
+     SELECT a.alias, t.locale, c.descriptor_json, t.value_json
+     FROM consumer_aliases a JOIN copies c ON c.id = a.copy_id JOIN translations t ON t.copy_id = c.id
+     WHERE a.consumer = ? AND a.alias >= ? AND a.alias < ?`);
     const rows = [];
     for (const selector of selectors) {
         const found = selector.kind === 'exact'
-            ? exact.all(consumer, selector.id)
-            : prefix.all(consumer, ...prefixRange(selector.prefix));
+            ? exact.all(consumer, selector.id, consumer, selector.id)
+            : prefix.all(consumer, ...prefixRange(selector.prefix), consumer, ...prefixRange(selector.prefix));
         rows.push(...found);
     }
     return rows;

package/dist/revision.d.mts

@@ -1,2 +1,2 @@
-import { type CatalogMessage } from '@vouchington/localization';
-export declare function catalogRevision(messages: readonly CatalogMessage[]): string;
+import { type CatalogMessage, type LocalizationCatalog } from '@vouchington/localization';
+export declare function catalogRevision(source: LocalizationCatalog | readonly CatalogMessage[]): string;

package/dist/revision.mjs

@@ -1,5 +1,6 @@
 import { createHash } from 'node:crypto';
-import { serializeCatalogMessages } from '@vouchington/localization';
-export function catalogRevision(messages) {
-    return createHash('sha256').update(serializeCatalogMessages(messages)).digest('hex');
+import { canonicalJson, catalogFromMessages, } from '@vouchington/localization';
+export function catalogRevision(source) {
+    const catalog = Array.isArray(source) ? catalogFromMessages(source) : source;
+    return createHash('sha256').update(canonicalJson(catalog)).digest('hex');
 }

package/dist/schema.d.mts

@@ -1,3 +1,3 @@
-export declare const SQLITE_SCHEMA = "\nPRAGMA encoding = 'UTF-8';\nPRAGMA foreign_keys = ON;\nCREATE TABLE metadata (\n  key TEXT PRIMARY KEY NOT NULL CHECK (key IN ('contract', 'revision')),\n  value TEXT NOT NULL\n);\nCREATE TABLE messages (\n  id TEXT PRIMARY KEY NOT NULL,\n  descriptor_json TEXT NOT NULL\n);\nCREATE TABLE translations (\n  locale TEXT NOT NULL,\n  message_id TEXT NOT NULL,\n  value_json TEXT NOT NULL,\n  PRIMARY KEY (locale, message_id),\n  FOREIGN KEY (message_id) REFERENCES messages(id)\n);\nCREATE TABLE consumer_membership (\n  consumer TEXT NOT NULL,\n  message_id TEXT NOT NULL,\n  PRIMARY KEY (consumer, message_id),\n  FOREIGN KEY (message_id) REFERENCES messages(id)\n);\nCREATE TABLE editorial_tags (\n  message_id TEXT NOT NULL,\n  tag TEXT NOT NULL,\n  PRIMARY KEY (message_id, tag),\n  FOREIGN KEY (message_id) REFERENCES messages(id)\n);\nCREATE INDEX translations_by_locale_id ON translations (locale, message_id);\nCREATE INDEX membership_by_consumer_id ON consumer_membership (consumer, message_id);\nCREATE INDEX messages_by_id ON messages (id);\n";
+export declare const SQLITE_SCHEMA = "\nPRAGMA encoding = 'UTF-8';\nPRAGMA foreign_keys = ON;\nCREATE TABLE metadata (\n  key TEXT PRIMARY KEY NOT NULL CHECK (key IN ('contract', 'revision')),\n  value TEXT NOT NULL\n);\nCREATE TABLE copies (\n  id TEXT PRIMARY KEY NOT NULL,\n  descriptor_json TEXT NOT NULL\n);\nCREATE TABLE translations (\n  locale TEXT NOT NULL,\n  copy_id TEXT NOT NULL,\n  value_json TEXT NOT NULL,\n  PRIMARY KEY (locale, copy_id),\n  FOREIGN KEY (copy_id) REFERENCES copies(id)\n);\nCREATE TABLE consumer_aliases (\n  consumer TEXT NOT NULL,\n  alias TEXT NOT NULL,\n  copy_id TEXT NOT NULL,\n  PRIMARY KEY (consumer, alias),\n  FOREIGN KEY (copy_id) REFERENCES copies(id)\n);\nCREATE TABLE route_membership (\n  consumer TEXT NOT NULL,\n  selector_id TEXT NOT NULL,\n  alias TEXT NOT NULL,\n  PRIMARY KEY (consumer, selector_id, alias),\n  FOREIGN KEY (consumer, alias) REFERENCES consumer_aliases(consumer, alias)\n);\nCREATE TABLE editorial_tags (\n  copy_id TEXT NOT NULL,\n  tag TEXT NOT NULL,\n  PRIMARY KEY (copy_id, tag),\n  FOREIGN KEY (copy_id) REFERENCES copies(id)\n);\nCREATE INDEX translations_by_locale_id ON translations (locale, copy_id);\nCREATE INDEX aliases_by_consumer_alias ON consumer_aliases (consumer, alias);\nCREATE INDEX routes_by_consumer_selector ON route_membership (consumer, selector_id);\n";
 export declare const DEFAULT_SQLITE_CACHE_KB = 2048;
 export declare const DEFAULT_TTL_SECONDS = 86400;

package/dist/schema.mjs

@@ -5,32 +5,40 @@ CREATE TABLE metadata (
   key TEXT PRIMARY KEY NOT NULL CHECK (key IN ('contract', 'revision')),
   value TEXT NOT NULL
 );
-CREATE TABLE messages (
+CREATE TABLE copies (
   id TEXT PRIMARY KEY NOT NULL,
   descriptor_json TEXT NOT NULL
 );
 CREATE TABLE translations (
   locale TEXT NOT NULL,
-  message_id TEXT NOT NULL,
+  copy_id TEXT NOT NULL,
   value_json TEXT NOT NULL,
-  PRIMARY KEY (locale, message_id),
-  FOREIGN KEY (message_id) REFERENCES messages(id)
+  PRIMARY KEY (locale, copy_id),
+  FOREIGN KEY (copy_id) REFERENCES copies(id)
 );
-CREATE TABLE consumer_membership (
+CREATE TABLE consumer_aliases (
   consumer TEXT NOT NULL,
-  message_id TEXT NOT NULL,
-  PRIMARY KEY (consumer, message_id),
-  FOREIGN KEY (message_id) REFERENCES messages(id)
+  alias TEXT NOT NULL,
+  copy_id TEXT NOT NULL,
+  PRIMARY KEY (consumer, alias),
+  FOREIGN KEY (copy_id) REFERENCES copies(id)
+);
+CREATE TABLE route_membership (
+  consumer TEXT NOT NULL,
+  selector_id TEXT NOT NULL,
+  alias TEXT NOT NULL,
+  PRIMARY KEY (consumer, selector_id, alias),
+  FOREIGN KEY (consumer, alias) REFERENCES consumer_aliases(consumer, alias)
 );
 CREATE TABLE editorial_tags (
-  message_id TEXT NOT NULL,
+  copy_id TEXT NOT NULL,
   tag TEXT NOT NULL,
-  PRIMARY KEY (message_id, tag),
-  FOREIGN KEY (message_id) REFERENCES messages(id)
+  PRIMARY KEY (copy_id, tag),
+  FOREIGN KEY (copy_id) REFERENCES copies(id)
 );
-CREATE INDEX translations_by_locale_id ON translations (locale, message_id);
-CREATE INDEX membership_by_consumer_id ON consumer_membership (consumer, message_id);
-CREATE INDEX messages_by_id ON messages (id);
+CREATE INDEX translations_by_locale_id ON translations (locale, copy_id);
+CREATE INDEX aliases_by_consumer_alias ON consumer_aliases (consumer, alias);
+CREATE INDEX routes_by_consumer_selector ON route_membership (consumer, selector_id);
 `;
 export const DEFAULT_SQLITE_CACHE_KB = 2048;
 export const DEFAULT_TTL_SECONDS = 86_400;

package/dist/table-cli.d.mts

@@ -0,0 +1,5 @@
+export declare function isTablePath(path: string): boolean;
+export declare function upsertTable(path: string, rowJson: string): undefined;
+export declare function removeTable(path: string, id: string, consumer: string | undefined): undefined;
+export declare function mergeTableFiles(ancestor: string, ours: string, theirs: string): void;
+export declare function readTable(path: string): Record<string, unknown>[];

package/dist/table-cli.mjs

@@ -0,0 +1,82 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { CatalogMergeConflict, canonicalJson, serializeCatalogTable, } from '@vouchington/localization';
+const CONFLICT = Symbol('conflict');
+export function isTablePath(path) {
+    return /(?:copies|aliases|routes)\.json$/.test(path) || /translations\/[^/]+\.json$/.test(path);
+}
+export function upsertTable(path, rowJson) {
+    mkdirSync(dirname(path), { recursive: true });
+    const row = JSON.parse(rowJson);
+    const rows = readTable(path);
+    const key = tableKey(row);
+    writeFileSync(path, serializeCatalogTable([...rows.filter((current) => tableKey(current) !== key), row]));
+    return undefined;
+}
+export function removeTable(path, id, consumer) {
+    const rows = readTable(path);
+    const next = rows.filter((row) => !(row.id === id ||
+        (row.alias === id && (consumer === undefined || row.consumer === consumer))));
+    if (next.length === rows.length)
+        throw new TypeError(`Catalog table does not contain "${id}"`);
+    writeFileSync(path, serializeCatalogTable(next));
+    return undefined;
+}
+export function mergeTableFiles(ancestor, ours, theirs) {
+    const base = new Map(readTable(ancestor).map((row) => [tableKey(row), row]));
+    const left = new Map(readTable(ours).map((row) => [tableKey(row), row]));
+    const right = new Map(readTable(theirs).map((row) => [tableKey(row), row]));
+    const merged = [];
+    const conflicts = [];
+    for (const key of [...new Set([...base.keys(), ...left.keys(), ...right.keys()])].sort()) {
+        const value = mergeValue(base.get(key), left.get(key), right.get(key));
+        if (value === CONFLICT)
+            conflicts.push(key);
+        else if (value !== undefined)
+            merged.push(value);
+    }
+    if (conflicts.length > 0) {
+        const text = conflicts.map((key) => conflictText(left.get(key), right.get(key))).join('\n');
+        writeFileSync(ours, `${text}\n`);
+        throw new CatalogMergeConflict(conflicts, text);
+    }
+    writeFileSync(ours, serializeCatalogTable(merged));
+}
+export function readTable(path) {
+    if (!existsSync(path))
+        return [];
+    const value = JSON.parse(readFileSync(path, 'utf8'));
+    if (!Array.isArray(value))
+        throw new TypeError(`${path} must be a JSON array`);
+    return value;
+}
+function mergeValue(base, ours, theirs) {
+    if (same(ours, theirs))
+        return ours;
+    if (same(ours, base))
+        return theirs;
+    if (same(theirs, base))
+        return ours;
+    return CONFLICT;
+}
+function conflictText(ours, theirs) {
+    return [
+        '<<<<<<< ours',
+        ours === undefined ? '' : canonicalJson(ours),
+        '=======',
+        theirs === undefined ? '' : canonicalJson(theirs),
+        '>>>>>>> theirs',
+    ]
+        .filter(Boolean)
+        .join('\n');
+}
+function same(left, right) {
+    if (left === undefined || right === undefined)
+        return left === right;
+    return canonicalJson(left) === canonicalJson(right);
+}
+function tableKey(row) {
+    return ['consumer', 'selectorId', 'alias', 'id']
+        .map((key) => (typeof row[key] === 'string' ? row[key] : ''))
+        .join('\t');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vouchington/localization-compiler",
-  "version": "0.0.2",
+  "version": "0.1.0",
   "description": "Node compiler for localization JSON catalogs, immutable SQLite artifacts, and CLI resolution.",
   "homepage": "https://github.com/vouchington/vouchington-platform/tree/main/packages/localization-compiler#readme",
   "bugs": {
@@ -36,7 +36,7 @@
   },
   "dependencies": {
     "@vouchington/csv": "^0.0.1",
-    "@vouchington/localization": "^0.0.1"
+    "@vouchington/localization": "^0.1.0"
   },
   "engines": {
     "node": ">=24.0.0"