@vouchington/localization-compiler 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jonathan Ong
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN ANY ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,9 @@
+# @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.
+
+CSV import/export is interchange only: never source of truth and never compiled directly to
+SQLite. Native resource helpers emit strings, RESX, and typed key/descriptor files from the
+same resolved catalog without product path assumptions.

package/dist/bin.d.mts

@@ -0,0 +1 @@
+export {};

package/dist/bin.mjs

@@ -0,0 +1,2 @@
+import { runLocalizationCli } from './cli.mjs';
+await runLocalizationCli(process.argv.slice(2));

package/dist/cli.d.mts

@@ -0,0 +1 @@
+export declare function runLocalizationCli(argv: readonly string[], write?: (value: string) => void): Promise<void>;

package/dist/cli.mjs

@@ -0,0 +1,79 @@
+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 { loadCatalogDirectory } from './load.mjs';
+import { openLocalizationDatabase } from './open.mjs';
+import { explainLocalizationPlan, resolveLocalizationBatch } from './resolve.mjs';
+export async function runLocalizationCli(argv, write = console.log) {
+    const [command, ...rest] = argv;
+    if (command === 'compile') {
+        const loaded = await loadCatalogDirectory(required(rest, '--source'));
+        write(compileLocalizationSqlite(loaded.messages, required(rest, '--output'), loaded.tags));
+        return;
+    }
+    if (command === 'resolve') {
+        withDatabase(required(rest, '--db'), (database) => {
+            write(serializeLocalizationBatch(resolveLocalizationBatch(database, {
+                consumer: required(rest, '--consumer'),
+                locales: required(rest, '--locales').split(','),
+                selectors: required(rest, '--selectors').split(','),
+            })));
+        });
+        return;
+    }
+    if (command === 'inspect') {
+        withDatabase(required(rest, '--db'), (database) => {
+            write(JSON.stringify({ contract: database.contract, revision: database.revision }, null, 2));
+            write(explainLocalizationPlan(database, { kind: 'prefix', prefix: 'nav' }));
+        });
+        return;
+    }
+    if (command === 'csv-export') {
+        const csv = exportLocalizationCsv((await loadCatalogDirectory(required(rest, '--source'))).messages);
+        const output = optional(rest, '--output');
+        if (output === undefined)
+            write(csv);
+        else
+            writeFileSync(output, csv);
+        return;
+    }
+    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'));
+        return;
+    }
+    throw new TypeError(usage());
+}
+function withDatabase(path, run) {
+    const database = openLocalizationDatabase(path);
+    try {
+        run(database);
+    }
+    finally {
+        database.close();
+    }
+}
+function required(args, flag) {
+    const value = optional(args, flag);
+    if (value === undefined)
+        throw new TypeError(usage());
+    return value;
+}
+function optional(args, flag) {
+    const index = args.indexOf(flag);
+    const value = index === -1 ? undefined : args[index + 1];
+    return value === undefined || value.startsWith('--') ? undefined : value;
+}
+function usage() {
+    return [
+        'Usage: vouchington-localization compile --source <dir> --output <file>',
+        'Usage: vouchington-localization resolve --db <file> --consumer <name> --locales <list> --selectors <list>',
+        'Usage: vouchington-localization inspect --db <file>',
+        'Usage: vouchington-localization csv-export --source <dir> [--output <file>]',
+        'Usage: vouchington-localization csv-import --input <file> --output <dir>',
+    ].join('\n');
+}

package/dist/compile.d.mts

@@ -0,0 +1,4 @@
+import { 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;

package/dist/compile.mjs

@@ -0,0 +1,60 @@
+import { mkdirSync, mkdtempSync, renameSync, rmSync, writeFileSync } 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, } 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);
+    mkdirSync(dirname(outputPath), { recursive: true });
+    const temporaryDirectory = mkdtempSync(join(tmpdir(), 'localization-'));
+    const temporary = join(temporaryDirectory, 'catalog.sqlite');
+    const database = new DatabaseSync(temporary);
+    try {
+        database.exec('PRAGMA journal_mode = OFF');
+        database.exec(SQLITE_SCHEMA);
+        insertMetadata(database, revision);
+        insertMessages(database, messages);
+        insertTags(database, tags);
+        database.exec('PRAGMA foreign_keys = ON');
+        assertSqliteIntegrity(database);
+    }
+    finally {
+        database.close();
+    }
+    renameSync(temporary, outputPath);
+    rmSync(temporaryDirectory, { recursive: true, force: true });
+    return revision;
+}
+export function writeJsonCatalog(messages, path) {
+    writeFileSync(path, `${JSON.stringify({ messages }, null, 2)}\n`);
+}
+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) => (left.id < right.id ? -1 : 1))) {
+        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);
+    }
+}

package/dist/csv.d.mts

@@ -0,0 +1,8 @@
+import { type CatalogMessage } from '@vouchington/localization';
+declare const COLUMNS: readonly ['id', 'locale', 'consumers', 'descriptor_json', 'value_json', 'catalog_revision'];
+export declare function exportLocalizationCsv(messages: readonly CatalogMessage[]): string;
+export declare function importLocalizationCsv(csv: string, options?: {
+    expectedRevision?: string;
+}): CatalogMessage[];
+export declare function csvRecord(row: readonly string[]): Record<(typeof COLUMNS)[number], string>;
+export {};

package/dist/csv.mjs

@@ -0,0 +1,83 @@
+import { parseCsvRows, stringifyCsvRows } from '@vouchington/csv';
+import { catalogMessageFromRecord, canonicalJson, compareCodePoints, } from '@vouchington/localization';
+import { catalogRevision } from './revision.mjs';
+import { validateCatalogMessages } from './validate.mjs';
+const COLUMNS = [
+    'id',
+    'locale',
+    'consumers',
+    'descriptor_json',
+    'value_json',
+    'catalog_revision',
+];
+export function exportLocalizationCsv(messages) {
+    validateCatalogMessages(messages);
+    const revision = catalogRevision(messages);
+    const rows = messages.flatMap((message) => Object.keys(message.translations)
+        .toSorted(compareCodePoints)
+        .map((locale) => ({
+        id: message.id,
+        locale,
+        consumers: message.consumers.join('|'),
+        descriptor_json: canonicalJson(message.descriptor),
+        value_json: canonicalJson(message.translations[locale]),
+        catalog_revision: revision,
+    })));
+    return stringifyCsvRows(rows, COLUMNS);
+}
+export function importLocalizationCsv(csv, options = {}) {
+    const [header, ...rows] = parseCsvRows(csv);
+    if (header === undefined || header.join(',') !== COLUMNS.join(',')) {
+        throw new TypeError('CSV header must match the localization interchange contract');
+    }
+    if (rows.length === 0)
+        throw new TypeError('CSV has no data rows');
+    const drafts = new Map();
+    const seen = new Set();
+    let revision;
+    for (const row of rows) {
+        const record = csvRecord(row);
+        if (revision !== undefined && record.catalog_revision !== revision) {
+            throw new TypeError('CSV rows must share a single catalog_revision');
+        }
+        revision = record.catalog_revision;
+        const key = `${record.id}\t${record.locale}`;
+        if (seen.has(key))
+            throw new TypeError(`Duplicate CSV row for "${record.id}" in ${record.locale}`);
+        seen.add(key);
+        const draft = drafts.get(record.id) ?? {
+            consumers: record.consumers,
+            descriptor_json: record.descriptor_json,
+            translations: {},
+        };
+        draft.translations[record.locale] = record.value_json;
+        drafts.set(record.id, draft);
+    }
+    const messages = [...drafts].map(([id, draft]) => catalogMessageFromRecord({
+        id,
+        consumers: draft.consumers.split('|'),
+        descriptor: JSON.parse(draft.descriptor_json),
+        translations: Object.fromEntries(Object.entries(draft.translations).map(([locale, value]) => [
+            locale,
+            JSON.parse(value),
+        ])),
+    }));
+    if (options.expectedRevision !== undefined && revision !== options.expectedRevision) {
+        throw new TypeError('CSV catalog_revision does not match the source contract hash');
+    }
+    validateCatalogMessages(messages);
+    if (revision !== catalogRevision(messages)) {
+        throw new TypeError('CSV catalog_revision does not match reconstructed catalog');
+    }
+    return messages;
+}
+export function csvRecord(row) {
+    const record = {};
+    for (const [index, column] of COLUMNS.entries()) {
+        const value = row[index];
+        if (value === undefined)
+            throw new TypeError(`CSV row is missing ${column}`);
+        record[column] = value;
+    }
+    return record;
+}

package/dist/index.d.mts

@@ -0,0 +1,9 @@
+export { compileLocalizationSqlite } from './compile.mts';
+export { exportLocalizationCsv, importLocalizationCsv } from './csv.mts';
+export { loadCatalogDirectory } from './load.mts';
+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 { validateCatalogMessages, parseCatalogFile } from './validate.mts';
+export { runLocalizationCli } from './cli.mts';

package/dist/index.mjs

@@ -0,0 +1,9 @@
+export { compileLocalizationSqlite } from './compile.mjs';
+export { exportLocalizationCsv, importLocalizationCsv } from './csv.mjs';
+export { loadCatalogDirectory } from './load.mjs';
+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 { validateCatalogMessages, parseCatalogFile } from './validate.mjs';
+export { runLocalizationCli } from './cli.mjs';

package/dist/integrity.d.mts

@@ -0,0 +1,2 @@
+import type { DatabaseSync } from 'node:sqlite';
+export declare function assertSqliteIntegrity(database: DatabaseSync): void;

package/dist/integrity.mjs

@@ -0,0 +1,6 @@
+export function assertSqliteIntegrity(database) {
+    const row = database.prepare('PRAGMA integrity_check').get();
+    if (row.integrity_check !== 'ok') {
+        throw new Error(`SQLite integrity_check failed: ${row.integrity_check}`);
+    }
+}

package/dist/load.d.mts

@@ -0,0 +1,6 @@
+import { type CatalogMessage } from '@vouchington/localization';
+export type EditorialTags = Readonly<Record<string, readonly string[]>>;
+export declare function loadCatalogDirectory(directory: string): Promise<{
+    messages: CatalogMessage[];
+    tags: EditorialTags;
+}>;

package/dist/load.mjs

@@ -0,0 +1,44 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { compareCodePoints } from '@vouchington/localization';
+import { parseCatalogFile, validateCatalogMessages } from './validate.mjs';
+export async function loadCatalogDirectory(directory) {
+    const names = (await readdir(directory))
+        .filter((name) => name.endsWith('.json'))
+        .toSorted(compareCodePoints);
+    if (names.length === 0)
+        throw new TypeError(`No catalog JSON files in "${directory}"`);
+    const messages = [];
+    let tags = {};
+    for (const name of names) {
+        const parsed = JSON.parse(await readFile(join(directory, name), 'utf8'));
+        if (name === 'tags.json') {
+            tags = parseTags(parsed);
+            continue;
+        }
+        messages.push(...parseCatalogFile(parsed));
+    }
+    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)) {
+        throw new TypeError('tags.json must be an object mapping message ids to tag arrays');
+    }
+    return Object.fromEntries(Object.entries(value).map(([id, tags]) => {
+        if (!Array.isArray(tags) || tags.some((tag) => typeof tag !== 'string' || tag.length === 0)) {
+            throw new TypeError(`Invalid editorial tags for "${id}"`);
+        }
+        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/native.d.mts

@@ -0,0 +1,10 @@
+import { type LocalizationLeaf, type MessageDescriptor } from '@vouchington/localization';
+export type NativeIdentifier = (id: string) => string;
+export type NativeResourceEntry = readonly [string, string];
+export declare function nativeLeafVariants(id: string, leaf: LocalizationLeaf): NativeResourceEntry[];
+export declare function renderSwiftStrings(entries: readonly NativeResourceEntry[]): string;
+export declare function renderResx(entries: readonly NativeResourceEntry[]): string;
+export declare function renderSwiftKeys(ids: readonly string[], identifier: NativeIdentifier): string;
+export declare function renderDotnetKeys(ids: readonly string[], identifier: NativeIdentifier): string;
+export declare function renderSwiftDescriptors(entries: ReadonlyArray<readonly [string, MessageDescriptor]>, identifier: NativeIdentifier): string;
+export declare function renderDotnetDescriptors(entries: ReadonlyArray<readonly [string, MessageDescriptor]>, identifier: NativeIdentifier): string;

package/dist/native.mjs

@@ -0,0 +1,71 @@
+import { compareCodePoints, } from '@vouchington/localization';
+export function nativeLeafVariants(id, leaf) {
+    if (typeof leaf === 'string')
+        return [[id, leaf]];
+    if (leaf.kind === 'plural') {
+        return [
+            [`${id}.__plural.one`, requireOne(id, leaf.forms)],
+            [`${id}.__plural.other`, leaf.forms.other],
+        ];
+    }
+    return Object.entries(leaf.cases)
+        .toSorted(([left], [right]) => compareCodePoints(left, right))
+        .flatMap(([selected, forms]) => [
+        [`${id}.__select.${selected}.one`, requireOne(id, forms)],
+        [`${id}.__select.${selected}.other`, forms.other],
+    ]);
+}
+export function renderSwiftStrings(entries) {
+    return `// Generated localization strings. Do not edit.\n${entries
+        .map(([key, value]) => `"${key}" = "${escapeSwift(value)}";`)
+        .join('\n')}\n`;
+}
+export function renderResx(entries) {
+    const data = entries
+        .map(([key, value]) => `  <data name="${escapeXml(key)}" xml:space="preserve"><value>${escapeXml(value)}</value></data>`)
+        .join('\n');
+    return `<?xml version="1.0" encoding="utf-8"?>\n<root>\n${data}\n</root>\n`;
+}
+export function renderSwiftKeys(ids, identifier) {
+    const lines = ids.map((id) => `    public static let ${identifier(id)} = UiMessageKey(rawValue: "${id}")`);
+    return `// Generated localization keys. Do not edit.\npublic struct UiMessageKey: Hashable, Sendable {\n    public let rawValue: String\n    public init(rawValue: String) { self.rawValue = rawValue }\n${lines.join('\n')}\n}\n`;
+}
+export function renderDotnetKeys(ids, identifier) {
+    const lines = ids.map((id) => `    public static readonly UiMessageKey ${identifier(id)} = new("${id}");`);
+    return `// Generated localization keys. Do not edit.\n#nullable enable\nnamespace Localization;\n\npublic readonly record struct UiMessageKey(string Value)\n{\n${lines.join('\n')}\n}\n`;
+}
+export function renderSwiftDescriptors(entries, identifier) {
+    const values = entries.map(([id, descriptor]) => swiftDescriptorLine(id, descriptor, identifier));
+    return `// Generated localization descriptors. Do not edit.\npublic struct UiMessageDescriptor: Sendable {\n    public enum Kind: Sendable { case plural, selectPlural }\n    public let kind: Kind\n    public let valueParameter: String\n    public let selectParameter: String?\n    public let numberParameters: [String]\n    public let cases: [String]\n}\n\npublic let uiMessageDescriptors: [UiMessageKey: UiMessageDescriptor] = [\n${values.join(',\n')}\n]\n`;
+}
+export function renderDotnetDescriptors(entries, identifier) {
+    const values = entries.map(([id, descriptor]) => dotnetDescriptorLine(id, descriptor, identifier));
+    return `// Generated localization descriptors. Do not edit.\n#nullable enable\nnamespace Localization;\n\npublic sealed record UiMessageDescriptor(string Kind, string ValueParameter, string? SelectParameter, IReadOnlyList<string> NumberParameters, IReadOnlyList<string> Cases);\n\npublic static class UiMessageDescriptors\n{\n    public static IReadOnlyDictionary<UiMessageKey, UiMessageDescriptor> All { get; } =\n        new Dictionary<UiMessageKey, UiMessageDescriptor>\n        {\n${values.join(',\n')}\n        };\n}\n`;
+}
+function swiftDescriptorLine(id, descriptor, identifier) {
+    const select = descriptor.kind === 'select-plural' ? `"${descriptor.selectParameter}"` : 'nil';
+    const cases = descriptor.kind === 'select-plural'
+        ? JSON.stringify([...descriptor.cases].toSorted(compareCodePoints))
+        : '[]';
+    return `    .${identifier(id)}: UiMessageDescriptor(kind: .${identifier(descriptor.kind)}, valueParameter: "${descriptor.valueParameter}", selectParameter: ${select}, numberParameters: ${JSON.stringify(descriptor.numberParameters ?? [])}, cases: ${cases})`;
+}
+function dotnetDescriptorLine(id, descriptor, identifier) {
+    const select = descriptor.kind === 'select-plural' ? `"${descriptor.selectParameter}"` : 'null';
+    const cases = descriptor.kind === 'select-plural' ? [...descriptor.cases].toSorted(compareCodePoints) : [];
+    return `        [UiMessageKey.${identifier(id)}] = new("${descriptor.kind}", "${descriptor.valueParameter}", ${select}, [${(descriptor.numberParameters ?? []).map((value) => `"${value}"`).join(', ')}], [${cases.map((value) => `"${value}"`).join(', ')}])`;
+}
+function requireOne(id, forms) {
+    if (forms.one === undefined)
+        throw new TypeError(`Native descriptor "${id}" must define a one form`);
+    return forms.one;
+}
+function escapeSwift(value) {
+    return value.replaceAll('\\', '\\\\').replaceAll('"', '\\"').replaceAll('\n', '\\n');
+}
+function escapeXml(value) {
+    return value
+        .replaceAll('&', '&amp;')
+        .replaceAll('<', '&lt;')
+        .replaceAll('>', '&gt;')
+        .replaceAll('"', '&quot;');
+}

package/dist/open.d.mts

@@ -0,0 +1,10 @@
+import { DatabaseSync } from 'node:sqlite';
+export type LocalizationDatabase = {
+    readonly revision: string;
+    readonly contract: string;
+    readonly sqlite: DatabaseSync;
+    close(): void;
+};
+export declare function openLocalizationDatabase(path: string, options?: {
+    cacheKb?: number;
+}): LocalizationDatabase;

package/dist/open.mjs

@@ -0,0 +1,33 @@
+import { DatabaseSync } from 'node:sqlite';
+import { LOCALIZATION_WIRE_CONTRACT } from '@vouchington/localization';
+import { assertSqliteIntegrity } from './integrity.mjs';
+import { DEFAULT_SQLITE_CACHE_KB } from './schema.mjs';
+export function openLocalizationDatabase(path, options = {}) {
+    const sqlite = new DatabaseSync(path, { readOnly: true });
+    sqlite.exec('PRAGMA query_only = ON');
+    sqlite.exec(`PRAGMA cache_size = -${options.cacheKb ?? DEFAULT_SQLITE_CACHE_KB}`);
+    sqlite.exec('PRAGMA mmap_size = 0');
+    assertSqliteIntegrity(sqlite);
+    const contract = readMetadata(sqlite, 'contract');
+    const revision = readMetadata(sqlite, 'revision');
+    if (contract !== LOCALIZATION_WIRE_CONTRACT) {
+        sqlite.close();
+        throw new Error(`Unsupported localization contract "${contract}"`);
+    }
+    return {
+        revision,
+        contract,
+        sqlite,
+        close() {
+            sqlite.close();
+        },
+    };
+}
+function readMetadata(database, key) {
+    const row = database.prepare('SELECT value FROM metadata WHERE key = ?').get(key);
+    if (row === undefined) {
+        database.close();
+        throw new Error(`Localization artifact is missing metadata "${key}"`);
+    }
+    return row.value;
+}

package/dist/resolve.d.mts

@@ -0,0 +1,13 @@
+import { type LocalizationBounds, type LocalizationLeaf, type LocalizationRequest, type LocalizationSelector } from '@vouchington/localization';
+import type { LocalizationDatabase } from './open.mts';
+export declare function resolveLocalizationBatch(database: LocalizationDatabase, request: LocalizationRequest, options?: {
+    bounds?: LocalizationBounds;
+    ttlSeconds?: number;
+    availableLocales?: readonly string[];
+}): Readonly<{
+    contract: import("@vouchington/localization").LocalizationWireContract;
+    revision: string;
+    ttlSeconds: number;
+    messages: Readonly<Record<string, LocalizationLeaf>>;
+}>;
+export declare function explainLocalizationPlan(database: LocalizationDatabase, selector: LocalizationSelector): string;

package/dist/resolve.mjs

@@ -0,0 +1,57 @@
+import { DEFAULT_LOCALIZATION_BOUNDS, assertMessageCount, assertPayloadBytes, canonicalJson, compareCodePoints, createLocalizationBatch, firstAvailableTranslation, leafForTranslation, normalizeLocalizationRequest, parseDescriptor, prefixRange, serializeLocalizationBatch, } from '@vouchington/localization';
+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();
+    for (const row of rows) {
+        const current = byId.get(row.id) ?? {
+            descriptor: parseDescriptor(JSON.parse(row.descriptor_json)),
+            translations: {},
+        };
+        current.translations[row.locale] = JSON.parse(row.value_json);
+        byId.set(row.id, current);
+    }
+    const messages = {};
+    for (const id of [...byId.keys()].toSorted(compareCodePoints)) {
+        const entry = byId.get(id);
+        const value = firstAvailableTranslation(normalized.locales, entry.translations);
+        if (value === undefined)
+            continue;
+        messages[id] = 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);
+    assertPayloadBytes(serializeLocalizationBatch(batch), options.bounds ?? DEFAULT_LOCALIZATION_BOUNDS);
+    return batch;
+}
+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 < ?`;
+    const statement = database.sqlite.prepare(sql);
+    const rows = selector.kind === 'exact'
+        ? statement.all(selector.id)
+        : statement.all(...prefixRange(selector.prefix));
+    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 rows = [];
+    for (const selector of selectors) {
+        const found = selector.kind === 'exact'
+            ? exact.all(consumer, selector.id)
+            : prefix.all(consumer, ...prefixRange(selector.prefix));
+        rows.push(...found);
+    }
+    return rows;
+}

package/dist/revision.d.mts

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

package/dist/revision.mjs

@@ -0,0 +1,5 @@
+import { createHash } from 'node:crypto';
+import { serializeCatalogMessages } from '@vouchington/localization';
+export function catalogRevision(messages) {
+    return createHash('sha256').update(serializeCatalogMessages(messages)).digest('hex');
+}

package/dist/schema.d.mts

@@ -0,0 +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 DEFAULT_SQLITE_CACHE_KB = 2048;
+export declare const DEFAULT_TTL_SECONDS = 86400;

package/dist/schema.mjs

@@ -0,0 +1,36 @@
+export const SQLITE_SCHEMA = `
+PRAGMA encoding = 'UTF-8';
+PRAGMA foreign_keys = ON;
+CREATE TABLE metadata (
+  key TEXT PRIMARY KEY NOT NULL CHECK (key IN ('contract', 'revision')),
+  value TEXT NOT NULL
+);
+CREATE TABLE messages (
+  id TEXT PRIMARY KEY NOT NULL,
+  descriptor_json TEXT NOT NULL
+);
+CREATE TABLE translations (
+  locale TEXT NOT NULL,
+  message_id TEXT NOT NULL,
+  value_json TEXT NOT NULL,
+  PRIMARY KEY (locale, message_id),
+  FOREIGN KEY (message_id) REFERENCES messages(id)
+);
+CREATE TABLE consumer_membership (
+  consumer TEXT NOT NULL,
+  message_id TEXT NOT NULL,
+  PRIMARY KEY (consumer, message_id),
+  FOREIGN KEY (message_id) REFERENCES messages(id)
+);
+CREATE TABLE editorial_tags (
+  message_id TEXT NOT NULL,
+  tag TEXT NOT NULL,
+  PRIMARY KEY (message_id, tag),
+  FOREIGN KEY (message_id) REFERENCES messages(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);
+`;
+export const DEFAULT_SQLITE_CACHE_KB = 2048;
+export const DEFAULT_TTL_SECONDS = 86_400;

package/dist/test-helpers.d.mts

@@ -0,0 +1,3 @@
+import type { CatalogMessage } from '@vouchington/localization';
+export declare function sampleMessages(): CatalogMessage[];
+export declare function writeCatalog(files: Record<string, unknown>): string;

package/dist/test-helpers.mjs

@@ -0,0 +1,49 @@
+import { mkdtempSync, mkdirSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+export function sampleMessages() {
+    return [
+        {
+            id: 'nav.home',
+            descriptor: null,
+            consumers: ['web', 'swift'],
+            translations: { 'en-US': 'Home', es: 'Inicio' },
+        },
+        {
+            id: 'common.save',
+            descriptor: null,
+            consumers: ['web'],
+            translations: { 'en-US': 'Save "{name}"' },
+        },
+        {
+            id: 'settings.count',
+            descriptor: { kind: 'plural', valueParameter: 'count' },
+            consumers: ['web', 'dotnet'],
+            translations: {
+                'en-US': { one: '{count} item', other: '{count} items' },
+                es: { one: '{count} artículo', other: '{count} artículos' },
+            },
+        },
+        {
+            id: 'settings.ago',
+            descriptor: {
+                kind: 'select-plural',
+                valueParameter: 'value',
+                selectParameter: 'unit',
+                cases: ['day'],
+            },
+            consumers: ['email'],
+            translations: {
+                'en-US': { day: { one: '{value} day ago', other: '{value} days ago' } },
+            },
+        },
+    ];
+}
+export function writeCatalog(files) {
+    const directory = mkdtempSync(join(tmpdir(), 'catalog-'));
+    mkdirSync(directory, { recursive: true });
+    for (const [name, value] of Object.entries(files)) {
+        writeFileSync(join(directory, name), `${JSON.stringify(value, null, 2)}\n`);
+    }
+    return directory;
+}

package/dist/validate.d.mts

@@ -0,0 +1,3 @@
+import { type CatalogMessage } from '@vouchington/localization';
+export declare function validateCatalogMessages(messages: readonly CatalogMessage[]): void;
+export declare function parseCatalogFile(value: unknown): CatalogMessage[];

package/dist/validate.mjs

@@ -0,0 +1,69 @@
+import { CANONICAL_SOURCE_LOCALE, ENGLISH_LOCALE_ALIAS, catalogMessageFromRecord, compareCodePoints, descriptorSignature, isPluralForms, isSelectPluralCases, normalizeLocale, placeholdersIn, } from '@vouchington/localization';
+export function validateCatalogMessages(messages) {
+    const seen = new Set();
+    for (const message of messages) {
+        if (seen.has(message.id))
+            throw new TypeError(`Duplicate message id "${message.id}"`);
+        seen.add(message.id);
+        if (!Object.hasOwn(message.translations, CANONICAL_SOURCE_LOCALE)) {
+            throw new TypeError(`Message "${message.id}" is missing ${CANONICAL_SOURCE_LOCALE}`);
+        }
+        const canonical = message.translations[CANONICAL_SOURCE_LOCALE];
+        assertValueMatchesDescriptor(message.id, CANONICAL_SOURCE_LOCALE, message.descriptor, canonical);
+        const expected = placeholdersFor(canonical);
+        for (const [locale, value] of Object.entries(message.translations)) {
+            const normalized = normalizeLocale(locale);
+            if (normalized === null)
+                throw new TypeError(`Invalid locale "${locale}" on "${message.id}"`);
+            if (locale === ENGLISH_LOCALE_ALIAS || locale !== normalized) {
+                throw new TypeError(`Locale "${locale}" on "${message.id}" must be stored as ${normalized}`);
+            }
+            assertValueMatchesDescriptor(message.id, locale, message.descriptor, value);
+            if (message.descriptor?.kind === 'select-plural') {
+                assertSelectCases(message.id, locale, message.descriptor, value);
+            }
+            if (expected.join(',') !== placeholdersFor(value).join(',')) {
+                throw new TypeError(`Placeholder mismatch for "${message.id}" in ${locale}`);
+            }
+        }
+    }
+}
+export function parseCatalogFile(value) {
+    const records = Array.isArray(value) ? value : isMessagesDocument(value) ? value.messages : null;
+    if (records === null)
+        throw new TypeError('Catalog file must be an array or { messages } document');
+    return records.map((record) => catalogMessageFromRecord(record));
+}
+function placeholdersFor(value) {
+    const names = typeof value === 'string'
+        ? placeholdersIn(value)
+        : isPluralForms(value)
+            ? Object.values(value).flatMap(placeholdersIn)
+            : Object.values(value).flatMap((forms) => Object.values(forms).flatMap(placeholdersIn));
+    return [...new Set(names)].toSorted(compareCodePoints);
+}
+function assertValueMatchesDescriptor(id, locale, descriptor, value) {
+    if (descriptor === null && typeof value !== 'string') {
+        throw new TypeError(`String message "${id}" has a non-string value in ${locale}`);
+    }
+    if (descriptor?.kind === 'plural' && !isPluralForms(value)) {
+        throw new TypeError(`Plural message "${id}" has invalid forms in ${locale}`);
+    }
+    if (descriptor?.kind === 'select-plural' && (typeof value === 'string' || isPluralForms(value))) {
+        throw new TypeError(`Select-plural message "${id}" has invalid cases in ${locale}`);
+    }
+}
+function assertSelectCases(id, locale, descriptor, value) {
+    if (typeof value === 'string' || isPluralForms(value) || !isSelectPluralCases(value)) {
+        throw new TypeError(`Select-plural message "${id}" has invalid cases in ${locale}`);
+    }
+    const actual = descriptorSignature({ ...descriptor, cases: Object.keys(value) });
+    if (descriptorSignature(descriptor) !== actual) {
+        throw new TypeError(`Select-plural cases mismatch for "${id}" in ${locale}`);
+    }
+}
+function isMessagesDocument(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        Array.isArray(value.messages));
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@vouchington/localization-compiler",
+  "version": "0.0.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": {
+    "url": "https://github.com/vouchington/vouchington-platform/issues"
+  },
+  "license": "MIT",
+  "author": "Jonathan Ong",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vouchington/vouchington-platform.git",
+    "directory": "packages/localization-compiler"
+  },
+  "bin": {
+    "vouchington-localization": "./dist/bin.mjs"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "prepack": "pnpm run build"
+  },
+  "dependencies": {
+    "@vouchington/csv": "^0.0.1",
+    "@vouchington/localization": "^0.0.0"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  }
+}