@_linked/translation 0.9.4 → 0.9.5

package/src/exchange.ts

@@ -1,437 +0,0 @@
-import { sharedState } from '@_linked/core/utils/sharedState';
-import type { MessageFormat } from './core/messages.js';
-import { canonicalLanguageTag } from './key-version.js';
-import type { TranslationState } from './records.js';
-
-export type TranslationExchangeKind = 'ui' | 'semantic';
-export type TranslationDeclarationKind =
-  | TranslationExchangeKind
-  | 'content';
-export type TranslationDeclarationStatus = 'confirmed' | 'pending';
-
-/**
- * The build-facing subset of the later multi-source discovery contract.
- * Static extraction omits the optional fields and retains its existing
- * confirmed/simple behavior.
- */
-export interface TranslationBuildDeclaration {
-  key: string;
-  sourceText: string;
-  format?: MessageFormat;
-  kind?: TranslationDeclarationKind;
-  status?: TranslationDeclarationStatus;
-  authoritative?: boolean;
-  namespace?: string;
-  file?: string;
-  line?: number;
-}
-
-export interface TranslationExchangeValue {
-  text: string;
-  state?: TranslationState;
-  note?: string;
-}
-
-export interface TranslationExchangeEntry {
-  key: string;
-  namespace?: string;
-  kind: TranslationExchangeKind;
-  sourceText: string;
-  keyVersionId: string;
-  sourceHash: string;
-  contractHash: string;
-  argumentSignature: string;
-  description?: string;
-  format: MessageFormat;
-  translations: Record<string, TranslationExchangeValue>;
-}
-
-export interface TranslationExchangeDocument {
-  schemaVersion: 1;
-  appId?: string;
-  branchId?: string;
-  sourceLanguage: string;
-  targetLanguages: string[];
-  exportedAt?: string;
-  revisionWatermark?: string;
-  contractSetHash?: string;
-  entries: TranslationExchangeEntry[];
-}
-
-export type ParsedTranslationExchangeEntry = Omit<
-  TranslationExchangeEntry,
-  | 'sourceText'
-  | 'keyVersionId'
-  | 'sourceHash'
-  | 'contractHash'
-  | 'argumentSignature'
-> & {
-  sourceText?: string;
-  keyVersionId?: string;
-  sourceHash?: string;
-  contractHash?: string;
-  argumentSignature?: string;
-};
-
-export interface ParsedTranslationExchangeDocument
-  extends Omit<TranslationExchangeDocument, 'entries'> {
-  entries: ParsedTranslationExchangeEntry[];
-}
-
-export type TranslationFormat =
-  | 'xliff-1.2'
-  | 'xliff-2.0'
-  | 'csv'
-  | 'json';
-
-export interface SerializedTranslationDocument {
-  fileName: string;
-  mediaType: string;
-  body: Uint8Array;
-}
-
-export interface TranslationFormatAdapter {
-  readonly format: TranslationFormat;
-  sniff(input: Uint8Array, fileName?: string): boolean;
-  parse(
-    input: Uint8Array,
-    options?: unknown,
-  ): Promise<ParsedTranslationExchangeDocument>;
-  serialize(
-    document: TranslationExchangeDocument,
-    options?: unknown,
-  ): Promise<SerializedTranslationDocument>;
-}
-
-export type TranslationImportDisposition =
-  | 'import'
-  | 'carry-forward'
-  | 'unverified-source'
-  | 'conflict'
-  | 'skip';
-
-export interface TranslationImportDryRunEntry {
-  key: string;
-  language: string;
-  disposition: TranslationImportDisposition;
-  expectedKeyVersionId?: string;
-  expectedUnitContentHash?: string;
-}
-
-export interface TranslationImportDryRun {
-  sessionId: string;
-  documentHash: string;
-  revisionWatermark: string;
-  expiresAt: string;
-  entries: TranslationImportDryRunEntry[];
-}
-
-const EXCHANGE_STATES = new Set<TranslationState>([
-  'untranslated',
-  'machine',
-  'reviewed',
-  'stale',
-]);
-// On globalThis so an adapter the host registers on one copy of this module is found by
-// another copy.
-const { adapters } = sharedState('@_linked/translation', 'exchange', () => ({
-  adapters: new Map<TranslationFormat, TranslationFormatAdapter>(),
-}));
-
-function record(value: unknown, label: string): Record<string, unknown> {
-  if (!value || typeof value !== 'object' || Array.isArray(value)) {
-    throw new Error(`${label} must be an object.`);
-  }
-  return value as Record<string, unknown>;
-}
-
-function requiredString(value: unknown, label: string): string {
-  if (typeof value !== 'string' || !value.trim()) {
-    throw new Error(`${label} is required.`);
-  }
-  return value.trim();
-}
-
-function optionalString(value: unknown, label: string): string | undefined {
-  if (value === undefined) return undefined;
-  if (typeof value !== 'string' || !value.trim()) {
-    throw new Error(`${label} must be a non-empty string when supplied.`);
-  }
-  return value.trim();
-}
-
-function messageFormat(value: unknown, label: string): MessageFormat {
-  if (value !== 'simple' && value !== 'icu') {
-    throw new Error(`${label} must be "simple" or "icu".`);
-  }
-  return value;
-}
-
-function exchangeKind(value: unknown, label: string): TranslationExchangeKind {
-  if (value !== 'ui' && value !== 'semantic') {
-    throw new Error(`${label} must be "ui" or "semantic".`);
-  }
-  return value;
-}
-
-function canonicalLanguages(value: unknown, label: string): string[] {
-  if (!Array.isArray(value)) throw new Error(`${label} must be an array.`);
-  const canonical: string[] = [];
-  const seen = new Set<string>();
-  for (const item of value) {
-    if (typeof item !== 'string') {
-      throw new Error(`${label} must contain only BCP-47 strings.`);
-    }
-    const language = canonicalLanguageTag(item);
-    if (!seen.has(language)) {
-      seen.add(language);
-      canonical.push(language);
-    }
-  }
-  return canonical;
-}
-
-function normalizeTranslations(
-  value: unknown,
-  label: string,
-): Record<string, TranslationExchangeValue> {
-  const input = record(value, label);
-  const translations: Record<string, TranslationExchangeValue> = {};
-  for (const [rawLanguage, rawValue] of Object.entries(input)) {
-    const language = canonicalLanguageTag(rawLanguage);
-    if (translations[language]) {
-      throw new Error(
-        `${label} contains duplicate canonical language "${language}".`,
-      );
-    }
-    const item = record(rawValue, `${label}.${rawLanguage}`);
-    if (typeof item.text !== 'string') {
-      throw new Error(`${label}.${rawLanguage}.text must be a string.`);
-    }
-    const state = item.state;
-    if (state !== undefined && !EXCHANGE_STATES.has(state as TranslationState)) {
-      throw new Error(`${label}.${rawLanguage}.state is invalid.`);
-    }
-    translations[language] = {
-      text: item.text,
-      ...(state ? { state: state as TranslationState } : {}),
-      ...(item.note === undefined
-        ? {}
-        : {
-            note: requiredString(
-              item.note,
-              `${label}.${rawLanguage}.note`,
-            ),
-          }),
-    };
-  }
-  return translations;
-}
-
-function normalizeEntry(
-  value: unknown,
-  index: number,
-): ParsedTranslationExchangeEntry {
-  const item = record(value, `entries[${index}]`);
-  const key = requiredString(item.key, `entries[${index}].key`);
-  return {
-    key,
-    ...(item.namespace === undefined
-      ? {}
-      : {
-          namespace: requiredString(
-            item.namespace,
-            `entries[${index}].namespace`,
-          ),
-        }),
-    kind: exchangeKind(item.kind, `entries[${index}].kind`),
-    format: messageFormat(item.format, `entries[${index}].format`),
-    ...(item.sourceText === undefined
-      ? {}
-      : {
-          sourceText:
-            typeof item.sourceText === 'string'
-              ? item.sourceText
-              : requiredString(item.sourceText, `entries[${index}].sourceText`),
-        }),
-    ...(item.keyVersionId === undefined
-      ? {}
-      : {
-          keyVersionId: requiredString(
-            item.keyVersionId,
-            `entries[${index}].keyVersionId`,
-          ),
-        }),
-    ...(item.sourceHash === undefined
-      ? {}
-      : {
-          sourceHash: requiredString(
-            item.sourceHash,
-            `entries[${index}].sourceHash`,
-          ),
-        }),
-    ...(item.contractHash === undefined
-      ? {}
-      : {
-          contractHash: requiredString(
-            item.contractHash,
-            `entries[${index}].contractHash`,
-          ),
-        }),
-    ...(item.argumentSignature === undefined
-      ? {}
-      : {
-          argumentSignature: requiredString(
-            item.argumentSignature,
-            `entries[${index}].argumentSignature`,
-          ),
-        }),
-    ...(item.description === undefined
-      ? {}
-      : {
-          description: requiredString(
-            item.description,
-            `entries[${index}].description`,
-          ),
-        }),
-    translations: normalizeTranslations(
-      item.translations,
-      `entries[${index}].translations`,
-    ),
-  };
-}
-
-/**
- * Normalize adapter output without inventing evidence missing from a foreign
- * file. Import disposition handles those entries as unverified later.
- */
-export function normalizeParsedTranslationExchangeDocument(
-  value: unknown,
-): ParsedTranslationExchangeDocument {
-  const input = record(value, 'Translation exchange document');
-  if (input.schemaVersion !== 1) {
-    throw new Error('Translation exchange schemaVersion must be 1.');
-  }
-  const sourceLanguage = canonicalLanguageTag(
-    requiredString(input.sourceLanguage, 'sourceLanguage'),
-  );
-  const targetLanguages = canonicalLanguages(
-    input.targetLanguages,
-    'targetLanguages',
-  );
-  if (!Array.isArray(input.entries)) {
-    throw new Error('entries must be an array.');
-  }
-  const entries = input.entries.map(normalizeEntry);
-  const identities = new Set<string>();
-  for (const entry of entries) {
-    for (const language of Object.keys(entry.translations)) {
-      const identity = `${entry.namespace ?? ''}\u0000${entry.key}\u0000${language}`;
-      if (identities.has(identity)) {
-        throw new Error(
-          `Duplicate translation entry for "${entry.key}" in ${language}.`,
-        );
-      }
-      identities.add(identity);
-    }
-  }
-  return {
-    schemaVersion: 1,
-    ...(input.appId === undefined
-      ? {}
-      : { appId: requiredString(input.appId, 'appId') }),
-    ...(input.branchId === undefined
-      ? {}
-      : { branchId: requiredString(input.branchId, 'branchId') }),
-    sourceLanguage,
-    targetLanguages,
-    ...(input.exportedAt === undefined
-      ? {}
-      : { exportedAt: requiredString(input.exportedAt, 'exportedAt') }),
-    ...(input.revisionWatermark === undefined
-      ? {}
-      : {
-          revisionWatermark: requiredString(
-            input.revisionWatermark,
-            'revisionWatermark',
-          ),
-        }),
-    ...(input.contractSetHash === undefined
-      ? {}
-      : {
-          contractSetHash: requiredString(
-            input.contractSetHash,
-            'contractSetHash',
-          ),
-        }),
-    entries,
-  };
-}
-
-/** Validate the stronger, version-evidenced document this package's own exports carry. */
-export function validateTranslationExchangeDocument(
-  value: unknown,
-): TranslationExchangeDocument {
-  const parsed = normalizeParsedTranslationExchangeDocument(value);
-  const entries = parsed.entries.map((entry, index): TranslationExchangeEntry => ({
-    ...entry,
-    sourceText:
-      entry.sourceText ??
-      requiredString(undefined, `entries[${index}].sourceText`),
-    keyVersionId:
-      entry.keyVersionId ??
-      requiredString(undefined, `entries[${index}].keyVersionId`),
-    sourceHash:
-      entry.sourceHash ??
-      requiredString(undefined, `entries[${index}].sourceHash`),
-    contractHash:
-      entry.contractHash ??
-      requiredString(undefined, `entries[${index}].contractHash`),
-    argumentSignature:
-      entry.argumentSignature ??
-      requiredString(undefined, `entries[${index}].argumentSignature`),
-  }));
-  return { ...parsed, entries };
-}
-
-export function isConfirmedBuildDeclaration(
-  declaration: TranslationBuildDeclaration,
-): boolean {
-  return (
-    (declaration.kind ?? 'ui') !== 'content' &&
-    (declaration.status ?? 'confirmed') === 'confirmed' &&
-    declaration.authoritative !== false
-  );
-}
-
-export function registerTranslationFormatAdapter(
-  adapter: TranslationFormatAdapter,
-): void {
-  const registered = adapters.get(adapter.format);
-  // The registry is process-wide, so the same adapter registered again (by a second copy of
-  // the host module that registers it) is not a conflict; a different adapter for the format is.
-  if (registered === adapter) return;
-  if (registered) {
-    throw new Error(
-      `Translation format adapter "${adapter.format}" is already registered.`,
-    );
-  }
-  adapters.set(adapter.format, adapter);
-}
-
-export function getTranslationFormatAdapter(
-  format: TranslationFormat,
-): TranslationFormatAdapter | undefined {
-  return adapters.get(format);
-}
-
-export function listTranslationFormatAdapters(): TranslationFormatAdapter[] {
-  return [...adapters.values()].sort((left, right) =>
-    left.format.localeCompare(right.format),
-  );
-}
-
-/** Test/host reset hook; adapters are registered explicitly by the host. */
-export function clearTranslationFormatAdapters(): void {
-  adapters.clear();
-}

package/src/export.ts

@@ -1,138 +0,0 @@
-import {
-  validateTranslationExchangeDocument,
-  type TranslationExchangeDocument,
-  type TranslationExchangeEntry,
-} from './exchange.js';
-import { canonicalLanguageTag, sha256Hex } from './key-version.js';
-import { canonicalJson, translationContractSetHash } from './release.js';
-import type {
-  TranslationEntryRecord,
-  TranslationState,
-} from './records.js';
-
-export interface TranslationExportOptions {
-  appId?: string;
-  branchId?: string;
-  sourceLanguage: string;
-  revisionWatermark: string;
-  exportedAt?: string;
-  languages?: readonly string[];
-  namespaces?: readonly string[];
-  keys?: readonly string[];
-  states?: readonly TranslationState[];
-}
-
-export interface TranslationExportFinding {
-  key: string;
-  code: 'content-key-unsupported' | 'missing-current-version';
-  message: string;
-}
-
-export interface TranslationExportResult {
-  document: TranslationExchangeDocument;
-  documentHash: string;
-  findings: TranslationExportFinding[];
-}
-
-/**
- * Build one deterministic, version-evidenced exchange snapshot. Content keys
- * and versionless keys are reported rather than silently losing metadata.
- */
-export async function createTranslationExchangeDocument(
-  entries: readonly TranslationEntryRecord[],
-  options: TranslationExportOptions,
-): Promise<TranslationExportResult> {
-  const sourceLanguage = canonicalLanguageTag(options.sourceLanguage);
-  const languageFilter = options.languages
-    ? new Set(options.languages.map(canonicalLanguageTag))
-    : undefined;
-  const namespaceFilter = options.namespaces
-    ? new Set(options.namespaces)
-    : undefined;
-  const keyFilter = options.keys ? new Set(options.keys) : undefined;
-  const stateFilter = options.states ? new Set(options.states) : undefined;
-  const findings: TranslationExportFinding[] = [];
-  const exportEntries: TranslationExchangeEntry[] = [];
-
-  for (const entry of [...entries].sort((left, right) =>
-    `${left.namespace}\u0000${left.key}`.localeCompare(
-      `${right.namespace}\u0000${right.key}`,
-    ),
-  )) {
-    if (namespaceFilter && !namespaceFilter.has(entry.namespace)) continue;
-    if (keyFilter && !keyFilter.has(entry.key)) continue;
-    if (entry.kind === 'content') {
-      findings.push({
-        key: entry.key,
-        code: 'content-key-unsupported',
-        message: 'Content translations are not part of the UI exchange format.',
-      });
-      continue;
-    }
-    const version = entry.currentVersion;
-    if (!version) {
-      findings.push({
-        key: entry.key,
-        code: 'missing-current-version',
-        message: 'The key has no current immutable version.',
-      });
-      continue;
-    }
-    const translations: TranslationExchangeEntry['translations'] = {};
-    for (const [rawLanguage, unit] of Object.entries(entry.units).sort(
-      ([left], [right]) => left.localeCompare(right),
-    )) {
-      const language = canonicalLanguageTag(rawLanguage);
-      if (language === sourceLanguage) continue;
-      if (languageFilter && !languageFilter.has(language)) continue;
-      if (stateFilter && !stateFilter.has(unit.state)) continue;
-      translations[language] = {
-        text: unit.text,
-        state: unit.state,
-      };
-    }
-    exportEntries.push({
-      key: entry.key,
-      namespace: entry.namespace,
-      kind:
-        entry.ofShape ||
-        entry.ofProperty ||
-        entry.ofResource ||
-        entry.fromPackage
-          ? 'semantic'
-          : 'ui',
-      sourceText: version.sourceText,
-      keyVersionId: version.id,
-      sourceHash: version.sourceHash,
-      contractHash: version.contractHash,
-      argumentSignature: version.argumentSignature,
-      description: entry.description,
-      format: version.format,
-      translations,
-    });
-  }
-
-  const targetLanguages = [
-    ...new Set(
-      exportEntries.flatMap((entry) => Object.keys(entry.translations)),
-    ),
-  ].sort();
-  const document = validateTranslationExchangeDocument({
-    schemaVersion: 1,
-    appId: options.appId,
-    branchId: options.branchId,
-    sourceLanguage,
-    targetLanguages,
-    exportedAt: options.exportedAt,
-    revisionWatermark: options.revisionWatermark,
-    contractSetHash: await translationContractSetHash(
-      entries.filter((entry) => entry.kind === 'ui') as TranslationEntryRecord[],
-    ),
-    entries: exportEntries,
-  });
-  return {
-    document,
-    documentHash: await sha256Hex(canonicalJson(document)),
-    findings,
-  };
-}