@_linked/translation 0.2.2

package/src/index.ts

@@ -0,0 +1,207 @@
+// 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 type {
+  TranslationAuthoringAction,
+  TranslationAuthorizationRequest,
+  TranslationAuthorizationResolver,
+} 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 type {
+  DerivedBackfillKeyVersion,
+  ExtractedTranslationKeyContract,
+  KeyVersionDecision,
+  TranslationKeyVersionContract,
+  TranslationKeyVersionLike,
+} from './key-version.js';
+export {
+  defineShapeTranslationCatalog,
+  installShapeTranslationCatalog,
+  shapeCatalogTranslationDiscoverySource,
+} from './shape-catalog.js';
+export type {
+  ShapeTranslationCatalog,
+  ShapeTranslationCatalogEntry,
+  ShapeTranslationCatalogTarget,
+  ShapeTranslationInstallReport,
+} from './shape-catalog.js';
+export {
+  discoverTranslationInventory,
+  manifestTranslationDiscoverySource,
+  parseTranslationDiscoveryManifest,
+  translationBuildDeclarationsFromInventory,
+  translationDeclarationIdentity,
+} from './discovery.js';
+export type {
+  DiscoverTranslationInventoryOptions,
+  TranslationDeclaration,
+  TranslationDeclarationProvenance,
+  TranslationDeclarationSource,
+  TranslationDiscoveryContext,
+  TranslationDiscoveryManifest,
+  TranslationDiscoveryManifestEntry,
+  TranslationDiscoverySource,
+  TranslationInventoryConflict,
+  TranslationInventoryItem,
+  TranslationInventorySnapshot,
+  TranslationInventoryStatus,
+} from './discovery.js';
+export {
+  linkedPackageTranslationDiscoverySource,
+  parseLinkedPackageTranslationCatalog,
+} from './linked-discovery.js';
+export type {
+  LinkedComponentTranslationCatalog,
+  LinkedContentTranslationCatalogEntry,
+  LinkedPackageTranslationCatalog,
+  LinkedSemanticCatalogEntry,
+  LinkedSemanticEntryType,
+} from './linked-discovery.js';
+export {
+  clearTranslationFormatAdapters,
+  getTranslationFormatAdapter,
+  isConfirmedBuildDeclaration,
+  listTranslationFormatAdapters,
+  normalizeParsedTranslationExchangeDocument,
+  registerTranslationFormatAdapter,
+  validateTranslationExchangeDocument,
+} from './exchange.js';
+export type {
+  ParsedTranslationExchangeDocument,
+  ParsedTranslationExchangeEntry,
+  SerializedTranslationDocument,
+  TranslationBuildDeclaration,
+  TranslationDeclarationKind,
+  TranslationDeclarationStatus,
+  TranslationExchangeDocument,
+  TranslationExchangeEntry,
+  TranslationExchangeKind,
+  TranslationExchangeValue,
+  TranslationFormat,
+  TranslationFormatAdapter,
+  TranslationImportDisposition,
+  TranslationImportDryRun,
+  TranslationImportDryRunEntry,
+} from './exchange.js';
+export {
+  commitVersionedImport,
+  flattenMessages,
+  hasIcuSyntax,
+  planVersionedImport,
+  runImport,
+  tolgeeCdnSource,
+  translationUnitContentHash,
+} from './import.js';
+export type {
+  ImportMergePolicy,
+  ImportOptions,
+  ImportReport,
+  ImportTarget,
+  ParsedUnit,
+  TranslationImportSource,
+  VersionedImportCommitReport,
+  VersionedImportCurrentState,
+  VersionedImportDecision,
+  VersionedImportPlan,
+  VersionedImportPlanOptions,
+  VersionedImportTarget,
+} from './import.js';
+export { createTranslationExchangeDocument } from './export.js';
+export type {
+  TranslationExportFinding,
+  TranslationExportOptions,
+  TranslationExportResult,
+} from './export.js';
+export { translationCsvAdapter } from './formats/csv.js';
+export { xliff12Adapter, xliff20Adapter } from './formats/xliff.js';
+export type { XliffFinding, XliffParseOptions } from './formats/xliff.js';
+export {
+  DEFAULT_TRANSLATION_JSON_ARCHIVE_LIMITS,
+  i18nextJsonFormatAdapter,
+  parseI18nextJson,
+  serializeI18nextJsonZip,
+} from './formats/json.js';
+export type {
+  I18nextJsonLayout,
+  TranslationJsonArchiveLimits,
+  TranslationJsonParseOptions,
+  TranslationJsonSerializeOptions,
+} 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 type {
+  ParsedTranslationArchive,
+  PlanTranslationArchiveRestoreOptions,
+  SerializedTranslationArchive,
+  TranslationArchiveCollection,
+  TranslationArchiveContentMapping,
+  TranslationArchiveEntity,
+  TranslationArchiveEntityInput,
+  TranslationArchiveFileInventory,
+  TranslationArchiveJson,
+  TranslationArchiveManifest,
+  TranslationArchiveObjectInput,
+  TranslationArchiveObjectInventory,
+  TranslationArchiveRestoreDecision,
+  TranslationArchiveRestorePlan,
+  TranslationArchiveSnapshot,
+  TranslationArchiveTargetRecord,
+} from './archive.js';
+export type {
+  GlossaryTermRecord,
+  TranslationEntryRecord,
+  TranslationRevisionRecord,
+  TranslationRevisionStatus,
+  TranslationMemoryMatchKind,
+  TranslationMemoryMatchRecord,
+  TranslationMemoryPretranslateCandidate,
+  TranslationMemoryPretranslateReport,
+  TranslationMemoryRecord,
+  TranslationProposalDecision,
+  TranslationReleaseChannel,
+  TranslationReleaseRecord,
+  TranslationReleaseStatus,
+  TranslationState,
+  TranslationKeyVersionRecord,
+  TranslationUnitRecord,
+} from './records.js';
+
+export { TranslationLanguage } from './shapes/TranslationLanguage.js';
+export * from './languages.js';

package/src/key-sync-node.ts

@@ -0,0 +1,269 @@
+import { access, readdir, readFile, realpath } from 'node:fs/promises';
+import {
+  dirname,
+  extname,
+  isAbsolute,
+  join,
+  relative,
+  resolve,
+  sep,
+} from 'node:path';
+import {
+  extractTranslationKeys,
+  syncTranslationKeys,
+  translationDeclarationsFromExtractedKeys,
+  type ExtractedTranslationKey,
+  type TranslationKeySyncOptions,
+  type TranslationKeySyncReport,
+  type TranslationKeySyncTarget,
+} from './key-sync.js';
+import {
+  manifestTranslationDiscoverySource,
+  type TranslationDiscoverySource,
+} 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';
+
+interface PackageManifest {
+  name?: unknown;
+  dependencies?: unknown;
+  optionalDependencies?: unknown;
+  [LINKED_TRANSLATION_CATALOG_FIELD]?: unknown;
+}
+
+async function readJsonFile(path: string): Promise<unknown> {
+  return JSON.parse(await readFile(path, 'utf8')) as unknown;
+}
+
+async function readOptionalJsonFile(path: string): Promise<unknown | null> {
+  try {
+    return await readJsonFile(path);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+function dependencyNames(manifest: PackageManifest): string[] {
+  const names = new Set<string>();
+  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: string,
+  packageDirectory: string,
+  dependency: string,
+): Promise<string | null> {
+  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 {
+        // 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: string,
+  file: string,
+): Promise<string> {
+  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: string,
+): Promise<TranslationDiscoverySource[]> {
+  const workspaceRoot = resolve(root);
+  const sources: TranslationDiscoverySource[] = [];
+  const appManifest = await readOptionalJsonFile(
+    join(workspaceRoot, TRANSLATION_DISCOVERY_MANIFEST_FILE),
+  );
+  if (appManifest) {
+    sources.push(manifestTranslationDiscoverySource(appManifest));
+  }
+
+  const visited = new Set<string>();
+  const inspectPackage = async (packageDirectory: string): Promise<void> => {
+    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 as PackageManifest;
+    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));
+}
+
+export interface ScanTranslationSourceOptions {
+  extensions?: Iterable<string>;
+  ignoredDirectories?: Iterable<string>;
+}
+
+/** Recursively extract static translation keys from an application's source tree. */
+export async function scanTranslationSourceTree(
+  root: string,
+  options: ScanTranslationSourceOptions = {},
+): Promise<ExtractedTranslationKey[]> {
+  const absoluteRoot = resolve(root);
+  const extensions = new Set(options.extensions ?? SOURCE_EXTENSIONS);
+  const ignored = new Set(options.ignoredDirectories ?? IGNORED_DIRECTORIES);
+  const files: string[] = [];
+
+  const walk = async (directory: string): Promise<void> => {
+    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: string,
+  options: ScanTranslationSourceOptions = {},
+): TranslationDiscoverySource {
+  return {
+    name: `source-tree:${resolve(root)}`,
+    async *discover() {
+      const extracted = await scanTranslationSourceTree(root, options);
+      yield* translationDeclarationsFromExtractedKeys(extracted);
+    },
+  };
+}
+
+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 async function syncTranslationSourceTree({
+  root,
+  appId,
+  target,
+  dryRun,
+  extensions,
+  ignoredDirectories,
+}: SyncTranslationSourceTreeOptions): Promise<TranslationKeySyncReport> {
+  const extracted = await scanTranslationSourceTree(root, { extensions, ignoredDirectories });
+  return syncTranslationKeys(target, appId, extracted, { dryRun });
+}

package/src/key-sync.ts

@@ -0,0 +1,168 @@
+import ts from 'typescript';
+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;
+}
+
+function literalText(node: ts.Node | undefined): string | undefined {
+  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: string,
+  file = 'source.tsx',
+): ExtractedTranslationKey[] {
+  const sourceFile = ts.createSourceFile(
+    file,
+    source,
+    ts.ScriptTarget.Latest,
+    true,
+    file.endsWith('x') ? ts.ScriptKind.TSX : ts.ScriptKind.TS,
+  );
+  const extracted: ExtractedTranslationKey[] = [];
+  const add = (keyNode: ts.Node | undefined, defaultNode: ts.Node | undefined) => {
+    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: ts.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: ts.JsxAttributeValue | undefined) => {
+          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: Iterable<ExtractedTranslationKey>,
+): TranslationDeclaration[] {
+  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: Iterable<ExtractedTranslationKey>,
+  name = 'static-code',
+): TranslationDiscoverySource {
+  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: TranslationKeySyncTarget,
+  appId: string,
+  extracted: ExtractedTranslationKey[],
+  options: TranslationKeySyncOptions = {},
+): Promise<TranslationKeySyncReport> {
+  const existing = await target.list({ appId });
+  const existingByKey = new Map(existing.map((item) => [item.key, item]));
+  const defaultsByKey = new Map<string, Set<string>>();
+  for (const item of extracted) {
+    const defaults = defaultsByKey.get(item.key) ?? new Set<string>();
+    defaults.add(item.sourceText);
+    defaultsByKey.set(item.key, defaults);
+  }
+  const report: TranslationKeySyncReport = {
+    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;
+}