@_linked/translation 0.2.2

package/lib/esm/index.js

@@ -0,0 +1,34 @@
+// Isomorphic barrel (Plan 014 AD-G): side-effect imports register the ontology
+// + shapes into the LINKED tree. Safe on client and server — no backend/Node
+// code here (that lives in ./backend.ts). Ontology FIRST, then shapes.
+import './ontologies/translation.js';
+import './shapes/TranslationKey.js';
+import './shapes/TranslationKeyVersion.js';
+import './shapes/TranslationRelease.js';
+import './shapes/TranslationUnit.js';
+import './shapes/TranslationRevision.js';
+import './shapes/GlossaryTerm.js';
+import './shapes/TranslationInventoryOrigin.js';
+export { canAuthorTranslation, configureTranslationAuthorization, } from './authorization.js';
+export { TranslationKey } from './shapes/TranslationKey.js';
+export { TranslationKeyVersion } from './shapes/TranslationKeyVersion.js';
+export { TranslationRelease } from './shapes/TranslationRelease.js';
+export { TranslationUnit } from './shapes/TranslationUnit.js';
+export { TranslationRevision } from './shapes/TranslationRevision.js';
+export { GlossaryTerm } from './shapes/GlossaryTerm.js';
+export { TranslationInventoryOrigin } from './shapes/TranslationInventoryOrigin.js';
+export { tr } from './ontologies/translation.js';
+export { canonicalLanguageTag, classifyKeyVersion, createArgumentSignature, createMonotonicVersionId, deriveBackfillKeyVersion, deriveTranslationKeyVersionContract, sha256Hex, } from './key-version.js';
+export { defineShapeTranslationCatalog, installShapeTranslationCatalog, shapeCatalogTranslationDiscoverySource, } from './shape-catalog.js';
+export { discoverTranslationInventory, manifestTranslationDiscoverySource, parseTranslationDiscoveryManifest, translationBuildDeclarationsFromInventory, translationDeclarationIdentity, } from './discovery.js';
+export { linkedPackageTranslationDiscoverySource, parseLinkedPackageTranslationCatalog, } from './linked-discovery.js';
+export { clearTranslationFormatAdapters, getTranslationFormatAdapter, isConfirmedBuildDeclaration, listTranslationFormatAdapters, normalizeParsedTranslationExchangeDocument, registerTranslationFormatAdapter, validateTranslationExchangeDocument, } from './exchange.js';
+export { commitVersionedImport, flattenMessages, hasIcuSyntax, planVersionedImport, runImport, tolgeeCdnSource, translationUnitContentHash, } from './import.js';
+export { createTranslationExchangeDocument } from './export.js';
+export { translationCsvAdapter } from './formats/csv.js';
+export { xliff12Adapter, xliff20Adapter } from './formats/xliff.js';
+export { DEFAULT_TRANSLATION_JSON_ARCHIVE_LIMITS, i18nextJsonFormatAdapter, parseI18nextJson, serializeI18nextJsonZip, } from './formats/json.js';
+export { DEFAULT_TRANSLATION_ARCHIVE_LIMITS, createTranslationArchive, parseTranslationArchive, planTranslationArchiveRestore, TRANSLATION_ARCHIVE_COLLECTIONS, TRANSLATION_ARCHIVE_EXCLUSIONS, TRANSLATION_ARCHIVE_MANIFEST_PATH, } from './archive.js';
+export { TranslationLanguage } from './shapes/TranslationLanguage.js';
+export * from './languages.js';
+//# sourceMappingURL=index.js.map

package/lib/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,6EAA6E;AAC7E,uEAAuE;AACvE,OAAO,6BAA6B,CAAC;AACrC,OAAO,4BAA4B,CAAC;AACpC,OAAO,mCAAmC,CAAC;AAC3C,OAAO,gCAAgC,CAAC;AACxC,OAAO,6BAA6B,CAAC;AACrC,OAAO,iCAAiC,CAAC;AACzC,OAAO,0BAA0B,CAAC;AAClC,OAAO,wCAAwC,CAAC;AAEhD,OAAO,EACL,oBAAoB,EACpB,iCAAiC,GAClC,MAAM,oBAAoB,CAAC;AAO5B,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAC5D,OAAO,EAAE,qBAAqB,EAAE,MAAM,mCAAmC,CAAC;AAC1E,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AACpE,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAC;AACtE,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAE,0BAA0B,EAAE,MAAM,wCAAwC,CAAC;AACpF,OAAO,EAAE,EAAE,EAAE,MAAM,6BAA6B,CAAC;AACjD,OAAO,EACL,oBAAoB,EACpB,kBAAkB,EAClB,uBAAuB,EACvB,wBAAwB,EACxB,wBAAwB,EACxB,mCAAmC,EACnC,SAAS,GACV,MAAM,kBAAkB,CAAC;AAQ1B,OAAO,EACL,6BAA6B,EAC7B,8BAA8B,EAC9B,sCAAsC,GACvC,MAAM,oBAAoB,CAAC;AAO5B,OAAO,EACL,4BAA4B,EAC5B,kCAAkC,EAClC,iCAAiC,EACjC,yCAAyC,EACzC,8BAA8B,GAC/B,MAAM,gBAAgB,CAAC;AAexB,OAAO,EACL,uCAAuC,EACvC,oCAAoC,GACrC,MAAM,uBAAuB,CAAC;AAQ/B,OAAO,EACL,8BAA8B,EAC9B,2BAA2B,EAC3B,2BAA2B,EAC3B,6BAA6B,EAC7B,0CAA0C,EAC1C,gCAAgC,EAChC,mCAAmC,GACpC,MAAM,eAAe,CAAC;AAkBvB,OAAO,EACL,qBAAqB,EACrB,eAAe,EACf,YAAY,EACZ,mBAAmB,EACnB,SAAS,EACT,eAAe,EACf,0BAA0B,GAC3B,MAAM,aAAa,CAAC;AAerB,OAAO,EAAE,iCAAiC,EAAE,MAAM,aAAa,CAAC;AAMhE,OAAO,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEpE,OAAO,EACL,uCAAuC,EACvC,wBAAwB,EACxB,gBAAgB,EAChB,uBAAuB,GACxB,MAAM,mBAAmB,CAAC;AAO3B,OAAO,EACL,kCAAkC,EAClC,wBAAwB,EACxB,uBAAuB,EACvB,6BAA6B,EAC7B,+BAA+B,EAC/B,8BAA8B,EAC9B,iCAAiC,GAClC,MAAM,cAAc,CAAC;AAsCtB,OAAO,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAC;AACtE,cAAc,gBAAgB,CAAC"}

package/lib/esm/key-sync-node.d.ts

@@ -0,0 +1,29 @@
+import { type ExtractedTranslationKey, type TranslationKeySyncOptions, type TranslationKeySyncReport, type TranslationKeySyncTarget } from './key-sync.js';
+import { type TranslationDiscoverySource } from './discovery.js';
+/** Conventional code-canonical manifest for finite dynamic key families. */
+export declare const TRANSLATION_DISCOVERY_MANIFEST_FILE = "translation.discovery.json";
+/** package.json field pointing at a serialized LINKED translation catalog. */
+export declare const LINKED_TRANSLATION_CATALOG_FIELD = "linkedTranslationCatalog";
+/**
+ * Discover serialized app and dependency metadata from one exact workspace.
+ *
+ * This reads JSON only. Dependency JavaScript is never imported or evaluated.
+ * Dynamic keys live in `translation.discovery.json`; reusable LINKED packages
+ * opt in through package.json's `linkedTranslationCatalog` relative path.
+ */
+export declare function loadWorkspaceTranslationDiscoverySources(root: string): Promise<TranslationDiscoverySource[]>;
+export interface ScanTranslationSourceOptions {
+    extensions?: Iterable<string>;
+    ignoredDirectories?: Iterable<string>;
+}
+/** Recursively extract static translation keys from an application's source tree. */
+export declare function scanTranslationSourceTree(root: string, options?: ScanTranslationSourceOptions): Promise<ExtractedTranslationKey[]>;
+/** Portable discovery adapter for an ordinary application's source tree. */
+export declare function sourceTreeTranslationDiscoverySource(root: string, options?: ScanTranslationSourceOptions): TranslationDiscoverySource;
+export interface SyncTranslationSourceTreeOptions extends ScanTranslationSourceOptions, TranslationKeySyncOptions {
+    root: string;
+    appId: string;
+    target: TranslationKeySyncTarget;
+}
+/** Scan an app source tree and report or apply its keys through a provider adapter. */
+export declare function syncTranslationSourceTree({ root, appId, target, dryRun, extensions, ignoredDirectories, }: SyncTranslationSourceTreeOptions): Promise<TranslationKeySyncReport>;

package/lib/esm/key-sync-node.js

@@ -0,0 +1,174 @@
+import { access, readdir, readFile, realpath } from 'node:fs/promises';
+import { dirname, extname, isAbsolute, join, relative, resolve, sep, } from 'node:path';
+import { extractTranslationKeys, syncTranslationKeys, translationDeclarationsFromExtractedKeys, } from './key-sync.js';
+import { manifestTranslationDiscoverySource, } from './discovery.js';
+import { linkedPackageTranslationDiscoverySource } from './linked-discovery.js';
+const SOURCE_EXTENSIONS = new Set(['.js', '.jsx', '.ts', '.tsx']);
+const IGNORED_DIRECTORIES = new Set([
+    '.git',
+    'build',
+    'coverage',
+    'dist',
+    'lib',
+    'node_modules',
+]);
+/** Conventional code-canonical manifest for finite dynamic key families. */
+export const TRANSLATION_DISCOVERY_MANIFEST_FILE = 'translation.discovery.json';
+/** package.json field pointing at a serialized LINKED translation catalog. */
+export const LINKED_TRANSLATION_CATALOG_FIELD = 'linkedTranslationCatalog';
+async function readJsonFile(path) {
+    return JSON.parse(await readFile(path, 'utf8'));
+}
+async function readOptionalJsonFile(path) {
+    try {
+        return await readJsonFile(path);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+}
+function dependencyNames(manifest) {
+    const names = new Set();
+    for (const group of [manifest.dependencies, manifest.optionalDependencies]) {
+        if (!group || typeof group !== 'object' || Array.isArray(group))
+            continue;
+        for (const name of Object.keys(group))
+            names.add(name);
+    }
+    return [...names].sort();
+}
+async function dependencyDirectory(workspaceRoot, packageDirectory, dependency) {
+    let search = packageDirectory;
+    while (true) {
+        const candidate = join(search, 'node_modules', ...dependency.split('/'));
+        const boundary = relative(workspaceRoot, candidate);
+        if (!isAbsolute(boundary) && !boundary.startsWith('..')) {
+            try {
+                await access(join(candidate, 'package.json'));
+                return candidate;
+            }
+            catch (_a) {
+                // Hoisted dependencies may live in a parent node_modules directory.
+            }
+        }
+        if (search === workspaceRoot)
+            return null;
+        const parent = dirname(search);
+        if (parent === search || relative(workspaceRoot, parent).startsWith('..')) {
+            return null;
+        }
+        search = parent;
+    }
+}
+async function safePackageFile(packageDirectory, file) {
+    const clean = file.trim();
+    if (!clean) {
+        throw new Error(`${LINKED_TRANSLATION_CATALOG_FIELD} must be a non-empty relative path.`);
+    }
+    const lexicalFile = resolve(packageDirectory, clean);
+    const lexicalBoundary = relative(packageDirectory, lexicalFile);
+    if (isAbsolute(lexicalBoundary) ||
+        lexicalBoundary === '..' ||
+        lexicalBoundary.startsWith(`..${sep}`)) {
+        throw new Error(`${LINKED_TRANSLATION_CATALOG_FIELD} must stay inside its package.`);
+    }
+    const [realPackageDirectory, realFile] = await Promise.all([
+        realpath(packageDirectory),
+        realpath(lexicalFile),
+    ]);
+    const boundary = relative(realPackageDirectory, realFile);
+    if (isAbsolute(boundary) ||
+        boundary === '..' ||
+        boundary.startsWith(`..${sep}`)) {
+        throw new Error(`${LINKED_TRANSLATION_CATALOG_FIELD} must stay inside its package.`);
+    }
+    return realFile;
+}
+/**
+ * Discover serialized app and dependency metadata from one exact workspace.
+ *
+ * This reads JSON only. Dependency JavaScript is never imported or evaluated.
+ * Dynamic keys live in `translation.discovery.json`; reusable LINKED packages
+ * opt in through package.json's `linkedTranslationCatalog` relative path.
+ */
+export async function loadWorkspaceTranslationDiscoverySources(root) {
+    const workspaceRoot = resolve(root);
+    const sources = [];
+    const appManifest = await readOptionalJsonFile(join(workspaceRoot, TRANSLATION_DISCOVERY_MANIFEST_FILE));
+    if (appManifest) {
+        sources.push(manifestTranslationDiscoverySource(appManifest));
+    }
+    const visited = new Set();
+    const inspectPackage = async (packageDirectory) => {
+        const absoluteDirectory = resolve(packageDirectory);
+        if (visited.has(absoluteDirectory))
+            return;
+        const raw = await readOptionalJsonFile(join(absoluteDirectory, 'package.json'));
+        if (!raw)
+            return;
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+            throw new Error(`Invalid package.json in ${absoluteDirectory}.`);
+        }
+        visited.add(absoluteDirectory);
+        const manifest = raw;
+        const catalogFile = manifest[LINKED_TRANSLATION_CATALOG_FIELD];
+        if (catalogFile !== undefined) {
+            if (typeof catalogFile !== 'string') {
+                throw new Error(`${LINKED_TRANSLATION_CATALOG_FIELD} in ${absoluteDirectory}/package.json must be a string.`);
+            }
+            sources.push(linkedPackageTranslationDiscoverySource(await readFile(await safePackageFile(absoluteDirectory, catalogFile))));
+        }
+        for (const dependency of dependencyNames(manifest)) {
+            const directory = await dependencyDirectory(workspaceRoot, absoluteDirectory, dependency);
+            if (directory)
+                await inspectPackage(directory);
+        }
+    };
+    await inspectPackage(workspaceRoot);
+    return sources.sort((left, right) => left.name.localeCompare(right.name));
+}
+/** Recursively extract static translation keys from an application's source tree. */
+export async function scanTranslationSourceTree(root, options = {}) {
+    var _a, _b;
+    const absoluteRoot = resolve(root);
+    const extensions = new Set((_a = options.extensions) !== null && _a !== void 0 ? _a : SOURCE_EXTENSIONS);
+    const ignored = new Set((_b = options.ignoredDirectories) !== null && _b !== void 0 ? _b : IGNORED_DIRECTORIES);
+    const files = [];
+    const walk = async (directory) => {
+        const entries = await readdir(directory, { withFileTypes: true });
+        entries.sort((a, b) => a.name.localeCompare(b.name));
+        for (const entry of entries) {
+            if (entry.isSymbolicLink())
+                continue;
+            const path = resolve(directory, entry.name);
+            if (entry.isDirectory()) {
+                if (!ignored.has(entry.name))
+                    await walk(path);
+            }
+            else if (entry.isFile() && extensions.has(extname(entry.name))) {
+                files.push(path);
+            }
+        }
+    };
+    await walk(absoluteRoot);
+    const extracted = await Promise.all(files.map(async (file) => extractTranslationKeys(await readFile(file, 'utf8'), relative(absoluteRoot, file))));
+    return extracted.flat();
+}
+/** Portable discovery adapter for an ordinary application's source tree. */
+export function sourceTreeTranslationDiscoverySource(root, options = {}) {
+    return {
+        name: `source-tree:${resolve(root)}`,
+        async *discover() {
+            const extracted = await scanTranslationSourceTree(root, options);
+            yield* translationDeclarationsFromExtractedKeys(extracted);
+        },
+    };
+}
+/** Scan an app source tree and report or apply its keys through a provider adapter. */
+export async function syncTranslationSourceTree({ root, appId, target, dryRun, extensions, ignoredDirectories, }) {
+    const extracted = await scanTranslationSourceTree(root, { extensions, ignoredDirectories });
+    return syncTranslationKeys(target, appId, extracted, { dryRun });
+}
+//# sourceMappingURL=key-sync-node.js.map

package/lib/esm/key-sync-node.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"key-sync-node.js","sourceRoot":"","sources":["../../src/key-sync-node.ts"],"names":[],"mappings":"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"}

package/lib/esm/key-sync.d.ts

@@ -0,0 +1,46 @@
+import type { TranslationDeclaration, TranslationDiscoverySource } from './discovery.js';
+export interface ExtractedTranslationKey {
+    key: string;
+    sourceText: string;
+    file: string;
+    line: number;
+}
+export interface TranslationKeySyncTarget {
+    list(data: {
+        appId: string;
+    }): Promise<Array<{
+        key: string;
+        sourceText?: string;
+    }>>;
+    upsert(data: {
+        appId: string;
+        key: string;
+        sourceText: string;
+        kind: 'ui';
+    }): Promise<unknown>;
+}
+export interface TranslationKeySyncReport {
+    created: string[];
+    updated: string[];
+    unchanged: string[];
+    orphaned: string[];
+    conflicts: Array<{
+        key: string;
+        defaults: string[];
+    }>;
+}
+export interface TranslationKeySyncOptions {
+    /** Report changes without writing them to the target. */
+    dryRun?: boolean;
+}
+/** Extract static `t(key, default)` and `<T keyName defaultValue>` call sites. */
+export declare function extractTranslationKeys(source: string, file?: string): ExtractedTranslationKey[];
+/** Adapt the shipped static extractor to the portable discovery contract. */
+export declare function translationDeclarationsFromExtractedKeys(extracted: Iterable<ExtractedTranslationKey>): TranslationDeclaration[];
+/** Create a portable source from already-extracted static call sites. */
+export declare function staticTranslationDiscoverySource(extracted: Iterable<ExtractedTranslationKey>, name?: string): TranslationDiscoverySource;
+/**
+ * Apply extracted keys. Source drift is delegated to the provider, which marks
+ * existing units stale. Orphans are deliberately report-only.
+ */
+export declare function syncTranslationKeys(target: TranslationKeySyncTarget, appId: string, extracted: ExtractedTranslationKey[], options?: TranslationKeySyncOptions): Promise<TranslationKeySyncReport>;

package/lib/esm/key-sync.js

@@ -0,0 +1,114 @@
+import ts from 'typescript';
+function literalText(node) {
+    return node && (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node))
+        ? node.text
+        : undefined;
+}
+/** Extract static `t(key, default)` and `<T keyName defaultValue>` call sites. */
+export function extractTranslationKeys(source, file = 'source.tsx') {
+    const sourceFile = ts.createSourceFile(file, source, ts.ScriptTarget.Latest, true, file.endsWith('x') ? ts.ScriptKind.TSX : ts.ScriptKind.TS);
+    const extracted = [];
+    const add = (keyNode, defaultNode) => {
+        const key = literalText(keyNode);
+        const sourceText = literalText(defaultNode);
+        if (!key || sourceText === undefined)
+            return;
+        const { line } = sourceFile.getLineAndCharacterOfPosition(keyNode.getStart(sourceFile));
+        extracted.push({ key, sourceText, file, line: line + 1 });
+    };
+    const visit = (node) => {
+        if (ts.isCallExpression(node) &&
+            ts.isIdentifier(node.expression) &&
+            node.expression.text === 't') {
+            add(node.arguments[0], node.arguments[1]);
+        }
+        else if (ts.isJsxSelfClosingElement(node) || ts.isJsxOpeningElement(node)) {
+            if (node.tagName.getText(sourceFile) === 'T') {
+                const attrs = new Map(node.attributes.properties
+                    .filter(ts.isJsxAttribute)
+                    .map((attr) => [attr.name.getText(sourceFile), attr.initializer]));
+                const fromAttribute = (initializer) => {
+                    if (!initializer)
+                        return undefined;
+                    if (ts.isStringLiteral(initializer))
+                        return initializer;
+                    return ts.isJsxExpression(initializer) ? initializer.expression : undefined;
+                };
+                add(fromAttribute(attrs.get('keyName')), fromAttribute(attrs.get('defaultValue')));
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+    return extracted;
+}
+/** Adapt the shipped static extractor to the portable discovery contract. */
+export function translationDeclarationsFromExtractedKeys(extracted) {
+    return [...extracted].map((item) => ({
+        schemaVersion: 1,
+        key: item.key,
+        sourceText: item.sourceText,
+        kind: 'ui',
+        format: 'simple',
+        provenance: {
+            source: 'code',
+            sourceId: item.file,
+            authoritative: true,
+            file: item.file,
+            line: item.line,
+        },
+    }));
+}
+/** Create a portable source from already-extracted static call sites. */
+export function staticTranslationDiscoverySource(extracted, name = 'static-code') {
+    const declarations = translationDeclarationsFromExtractedKeys(extracted);
+    return {
+        name,
+        async *discover() {
+            yield* declarations;
+        },
+    };
+}
+/**
+ * Apply extracted keys. Source drift is delegated to the provider, which marks
+ * existing units stale. Orphans are deliberately report-only.
+ */
+export async function syncTranslationKeys(target, appId, extracted, options = {}) {
+    var _a;
+    const existing = await target.list({ appId });
+    const existingByKey = new Map(existing.map((item) => [item.key, item]));
+    const defaultsByKey = new Map();
+    for (const item of extracted) {
+        const defaults = (_a = defaultsByKey.get(item.key)) !== null && _a !== void 0 ? _a : new Set();
+        defaults.add(item.sourceText);
+        defaultsByKey.set(item.key, defaults);
+    }
+    const report = {
+        created: [], updated: [], unchanged: [], orphaned: [], conflicts: [],
+    };
+    for (const [key, defaults] of defaultsByKey) {
+        if (defaults.size > 1) {
+            report.conflicts.push({ key, defaults: [...defaults].sort() });
+            continue;
+        }
+        const sourceText = [...defaults][0];
+        const current = existingByKey.get(key);
+        if (!current)
+            report.created.push(key);
+        else if (current.sourceText !== sourceText)
+            report.updated.push(key);
+        else {
+            report.unchanged.push(key);
+            continue;
+        }
+        if (!options.dryRun) {
+            await target.upsert({ appId, key, sourceText, kind: 'ui' });
+        }
+    }
+    report.orphaned = existing
+        .map((item) => item.key)
+        .filter((key) => !defaultsByKey.has(key))
+        .sort();
+    return report;
+}
+//# sourceMappingURL=key-sync.js.map

package/lib/esm/key-sync.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"key-sync.js","sourceRoot":"","sources":["../../src/key-sync.ts"],"names":[],"mappings":"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"}

package/lib/esm/key-version.d.ts

@@ -0,0 +1,50 @@
+import type { MessageFormat } from './core/messages.js';
+export interface TranslationKeyVersionContract {
+    sourceLanguage: string;
+    sourceText: string;
+    format: MessageFormat;
+    argumentSignature: string;
+    contractHash: string;
+    sourceHash: string;
+}
+export interface DerivedBackfillKeyVersion extends TranslationKeyVersionContract {
+    versionId: string;
+}
+export interface TranslationKeyVersionLike {
+    sourceText: string;
+    format: MessageFormat;
+    argumentSignature: string;
+}
+export interface ExtractedTranslationKeyContract {
+    sourceText: string;
+    format: MessageFormat;
+}
+export interface KeyVersionDecision {
+    action: 'unchanged' | 'create-version' | 'retire';
+    reason: 'same-source-and-contract' | 'source-changed' | 'format-changed' | 'argument-contract-changed' | 'missing-from-source';
+}
+/** Monotonic ULID for newly authored key versions. */
+export declare function createMonotonicVersionId(now?: number, randomBytes?: Uint8Array): string;
+/** Portable SHA-256 used by both the browser-safe package and Node publishers. */
+export declare function sha256Hex(value: string): Promise<string>;
+export declare function canonicalLanguageTag(language: string): string;
+/**
+ * Stable runtime-argument contract. Object/argument ordering is canonical so
+ * extraction order and translator word order cannot change the hash.
+ */
+export declare function createArgumentSignature(sourceText: string, format: MessageFormat): string;
+export declare function classifyKeyVersion(current: TranslationKeyVersionLike | undefined, extracted: ExtractedTranslationKeyContract | undefined): KeyVersionDecision;
+export declare function deriveTranslationKeyVersionContract(input: {
+    sourceLanguage: string;
+    sourceText: string;
+    format: MessageFormat;
+}): Promise<TranslationKeyVersionContract>;
+/**
+ * Existing keys need a deterministic first version so a restarted migration
+ * cannot create a second node. Future authored versions use monotonic ULIDs.
+ */
+export declare function deriveBackfillKeyVersion(input: {
+    sourceLanguage: string;
+    sourceText: string;
+    format: MessageFormat;
+}): Promise<DerivedBackfillKeyVersion>;

package/lib/esm/key-version.js

@@ -0,0 +1,134 @@
+import { analyzeMessage } from './message-format.js';
+const bytesToHex = (bytes) => [...bytes].map((byte) => byte.toString(16).padStart(2, '0')).join('');
+const ULID_ALPHABET = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+const BIGINT_FIVE = BigInt(5);
+const BIGINT_EIGHT = BigInt(8);
+const BIGINT_THIRTY_ONE = BigInt(31);
+let lastUlidTime = -1;
+let lastUlidRandom = new Uint8Array(10);
+function encodeUlidTime(timestamp) {
+    let value = BigInt(timestamp);
+    let encoded = '';
+    for (let index = 0; index < 10; index++) {
+        encoded = ULID_ALPHABET[Number(value & BIGINT_THIRTY_ONE)] + encoded;
+        value >>= BIGINT_FIVE;
+    }
+    return encoded;
+}
+function encodeUlidRandom(bytes) {
+    let value = BigInt(0);
+    for (const byte of bytes)
+        value = (value << BIGINT_EIGHT) | BigInt(byte);
+    let encoded = '';
+    for (let index = 0; index < 16; index++) {
+        encoded = ULID_ALPHABET[Number(value & BIGINT_THIRTY_ONE)] + encoded;
+        value >>= BIGINT_FIVE;
+    }
+    return encoded;
+}
+function incrementRandom(bytes) {
+    const next = new Uint8Array(bytes);
+    for (let index = next.length - 1; index >= 0; index--) {
+        next[index] = (next[index] + 1) & 0xff;
+        if (next[index] !== 0)
+            return next;
+    }
+    throw new Error('ULID random component overflowed within one millisecond.');
+}
+/** Monotonic ULID for newly authored key versions. */
+export function createMonotonicVersionId(now = Date.now(), randomBytes) {
+    if (!Number.isSafeInteger(now) || now < 0 || now > 0xffffffffffff) {
+        throw new Error('ULID timestamp is outside the supported 48-bit range.');
+    }
+    const timestamp = Math.max(now, lastUlidTime);
+    if (timestamp === lastUlidTime) {
+        lastUlidRandom = incrementRandom(lastUlidRandom);
+    }
+    else {
+        const next = randomBytes !== null && randomBytes !== void 0 ? randomBytes : globalThis.crypto.getRandomValues(new Uint8Array(10));
+        if (next.length !== 10) {
+            throw new Error('ULID randomness must contain exactly 10 bytes.');
+        }
+        lastUlidTime = timestamp;
+        lastUlidRandom = new Uint8Array(next);
+    }
+    return `${encodeUlidTime(timestamp)}${encodeUlidRandom(lastUlidRandom)}`;
+}
+/** Portable SHA-256 used by both the browser-safe package and Node publishers. */
+export async function sha256Hex(value) {
+    const digest = await globalThis.crypto.subtle.digest('SHA-256', new TextEncoder().encode(value));
+    return bytesToHex(new Uint8Array(digest));
+}
+export function canonicalLanguageTag(language) {
+    var _a;
+    const value = language.trim();
+    if (!value)
+        throw new Error('sourceLanguage is required.');
+    try {
+        return (_a = Intl.getCanonicalLocales(value)[0]) !== null && _a !== void 0 ? _a : value;
+    }
+    catch (_b) {
+        throw new Error(`Invalid BCP-47 source language: ${language}`);
+    }
+}
+/**
+ * Stable runtime-argument contract. Object/argument ordering is canonical so
+ * extraction order and translator word order cannot change the hash.
+ */
+export function createArgumentSignature(sourceText, format) {
+    const analysis = analyzeMessage(sourceText, format);
+    if (!analysis.valid) {
+        throw new Error(`Cannot version invalid ${format.toUpperCase()} source text: ${analysis.error}`);
+    }
+    return JSON.stringify(analysis.arguments.map(({ name, kinds }) => [name, [...kinds].sort()]));
+}
+export function classifyKeyVersion(current, extracted) {
+    if (!extracted) {
+        return { action: 'retire', reason: 'missing-from-source' };
+    }
+    if (!current) {
+        return { action: 'create-version', reason: 'source-changed' };
+    }
+    if (current.format !== extracted.format) {
+        return { action: 'create-version', reason: 'format-changed' };
+    }
+    const nextSignature = createArgumentSignature(extracted.sourceText, extracted.format);
+    if (current.argumentSignature !== nextSignature) {
+        return {
+            action: 'create-version',
+            reason: 'argument-contract-changed',
+        };
+    }
+    if (current.sourceText !== extracted.sourceText) {
+        return { action: 'create-version', reason: 'source-changed' };
+    }
+    return { action: 'unchanged', reason: 'same-source-and-contract' };
+}
+export async function deriveTranslationKeyVersionContract(input) {
+    const sourceLanguage = canonicalLanguageTag(input.sourceLanguage);
+    const argumentSignature = createArgumentSignature(input.sourceText, input.format);
+    const [sourceHash, contractHash] = await Promise.all([
+        sha256Hex(JSON.stringify([sourceLanguage, input.sourceText])),
+        sha256Hex(JSON.stringify([input.format, argumentSignature])),
+    ]);
+    return {
+        sourceLanguage,
+        sourceText: input.sourceText,
+        format: input.format,
+        argumentSignature,
+        contractHash,
+        sourceHash,
+    };
+}
+/**
+ * Existing keys need a deterministic first version so a restarted migration
+ * cannot create a second node. Future authored versions use monotonic ULIDs.
+ */
+export async function deriveBackfillKeyVersion(input) {
+    const contract = await deriveTranslationKeyVersionContract(input);
+    return {
+        ...contract,
+        versionId: `backfill-${contract.sourceHash.slice(0, 16)}-${contract.contractHash.slice(0, 16)}`,
+    };
+}
+//# sourceMappingURL=key-version.js.map

package/lib/esm/key-version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"key-version.js","sourceRoot":"","sources":["../../src/key-version.ts"],"names":[],"mappings":"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"}

package/lib/esm/languages.d.ts

@@ -0,0 +1,18 @@
+/** Portable language metadata. Codes are open BCP-47 strings, never an enum. */
+export interface TranslationLanguageDefinition {
+    id: string;
+    code: string;
+    nativeName: string;
+    englishName: string;
+    direction: 'ltr' | 'rtl';
+    parent?: string;
+    fallback?: string;
+    enabled: boolean;
+    supported: boolean;
+}
+export declare function canonicalLocale(code: string): string;
+export declare function localeDirection(code: string): 'ltr' | 'rtl';
+export declare function defineLanguage(code: string, input?: Partial<TranslationLanguageDefinition>): TranslationLanguageDefinition;
+/** Ordered explicit fallback chain, ending at the source; safe against cycles. */
+export declare function languageFallbacks(code: string, source: string, definitions?: readonly TranslationLanguageDefinition[]): string[];
+export declare function validateLanguageDefinitions(definitions: readonly TranslationLanguageDefinition[]): void;