@_linked/translation 0.2.2

package/src/shape-catalog.ts

@@ -0,0 +1,198 @@
+import type {
+  TranslationEntryRecord,
+  TranslationState,
+} from './records.js';
+import type { TranslationDiscoverySource } from './discovery.js';
+
+/**
+ * Code-canonical translations shipped beside one reusable LINKED shape.
+ * Packages may expose this object from code or serialize the same contract as
+ * JSON for Host Agent discovery without executing package code.
+ */
+export interface ShapeTranslationCatalog {
+  schemaVersion: 1;
+  packageName: string;
+  /** Canonical SHACL node-shape IRI, not a display label or filesystem path. */
+  shapeIri: string;
+  /** Optional stable domain-class IRI used for semantic browsing. */
+  targetClass?: string;
+  entries: ShapeTranslationCatalogEntry[];
+}
+
+export interface ShapeTranslationCatalogEntry {
+  key: string;
+  sourceText: string;
+  description?: string;
+  namespace?: string;
+  /** Stable predicate IRI when this message describes a shape property. */
+  propertyIri?: string;
+  format?: 'simple' | 'icu';
+  /** Curated BCP-47 language values supplied by the package. */
+  translations?: Record<
+    string,
+    string | { text: string; state?: TranslationState }
+  >;
+}
+
+export interface ShapeTranslationCatalogTarget {
+  listEntries(data: { appId: string }): Promise<TranslationEntryRecord[]>;
+  upsertKey(data: {
+    appId: string;
+    key: string;
+    sourceText: string;
+    namespace?: string;
+    description?: string;
+    kind: 'ui';
+    format?: 'simple' | 'icu';
+    ofShape: string;
+    ofProperty?: string;
+    fromPackage: string;
+  }): Promise<unknown>;
+  upsertUnit(data: {
+    appId: string;
+    key: string;
+    language: string;
+    text: string;
+    state: TranslationState;
+  }): Promise<unknown>;
+}
+
+export interface ShapeTranslationInstallReport {
+  createdKeys: string[];
+  createdUnits: Array<{ key: string; language: string }>;
+  skippedExistingKeys: string[];
+  skippedExistingUnits: Array<{ key: string; language: string }>;
+}
+
+function requireString(value: unknown, label: string): string {
+  if (typeof value !== 'string' || !value.trim()) {
+    throw new Error(`${label} is required.`);
+  }
+  return value.trim();
+}
+
+/** Validate and freeze the package-owned declaration at module load time. */
+export function defineShapeTranslationCatalog(
+  catalog: ShapeTranslationCatalog,
+): Readonly<ShapeTranslationCatalog> {
+  if (catalog?.schemaVersion !== 1) {
+    throw new Error('Shape translation catalog schemaVersion must be 1.');
+  }
+  requireString(catalog.packageName, 'packageName');
+  requireString(catalog.shapeIri, 'shapeIri');
+  if (!Array.isArray(catalog.entries)) {
+    throw new Error('Shape translation catalog entries must be an array.');
+  }
+  const keys = new Set<string>();
+  for (const entry of catalog.entries) {
+    const key = requireString(entry?.key, 'entry.key');
+    requireString(entry?.sourceText, `sourceText for ${key}`);
+    if (keys.has(key)) throw new Error(`Duplicate shape translation key "${key}".`);
+    keys.add(key);
+  }
+  return Object.freeze(catalog);
+}
+
+/** Adapt the existing schema-v1 catalog without changing its install contract. */
+export function shapeCatalogTranslationDiscoverySource(
+  input: ShapeTranslationCatalog,
+): TranslationDiscoverySource {
+  const catalog = defineShapeTranslationCatalog(input);
+  return {
+    name: `shape-catalog:${catalog.packageName}:${catalog.shapeIri}`,
+    async *discover() {
+      for (const entry of catalog.entries) {
+        yield {
+          schemaVersion: 1,
+          key: entry.key,
+          sourceText: entry.sourceText,
+          kind: 'ui',
+          format: entry.format ?? 'simple',
+          ...(entry.namespace ? { namespace: entry.namespace } : {}),
+          ...(entry.description ? { description: entry.description } : {}),
+          provenance: {
+            source: 'package',
+            sourceId: `${catalog.packageName}:${catalog.shapeIri}`,
+            authoritative: true,
+            ownerIri: catalog.shapeIri,
+            shapeIri: catalog.shapeIri,
+            fromPackage: catalog.packageName,
+            ...(catalog.targetClass
+              ? { targetClass: catalog.targetClass }
+              : {}),
+            ...(entry.propertyIri
+              ? { propertyIri: entry.propertyIri }
+              : {}),
+          },
+        };
+      }
+    },
+  };
+}
+
+/**
+ * Seed only missing app values for the currently activated languages.
+ * Existing project-authored keys and units always win over package defaults.
+ */
+export async function installShapeTranslationCatalog(
+  target: ShapeTranslationCatalogTarget,
+  input: {
+    appId: string;
+    catalog: ShapeTranslationCatalog;
+    activeLanguages: Iterable<string>;
+  },
+): Promise<ShapeTranslationInstallReport> {
+  const appId = requireString(input.appId, 'appId');
+  const catalog = defineShapeTranslationCatalog(input.catalog);
+  const activeLanguages = new Set(
+    [...input.activeLanguages].map((language) => language.trim()).filter(Boolean),
+  );
+  const existing = new Map(
+    (await target.listEntries({ appId })).map((entry) => [entry.key, entry]),
+  );
+  const report: ShapeTranslationInstallReport = {
+    createdKeys: [],
+    createdUnits: [],
+    skippedExistingKeys: [],
+    skippedExistingUnits: [],
+  };
+
+  for (const entry of catalog.entries) {
+    const current = existing.get(entry.key);
+    if (current) report.skippedExistingKeys.push(entry.key);
+    else {
+      await target.upsertKey({
+        appId,
+        key: entry.key,
+        sourceText: entry.sourceText,
+        namespace: entry.namespace,
+        description: entry.description,
+        kind: 'ui',
+        format: entry.format,
+        ofShape: catalog.shapeIri,
+        ofProperty: entry.propertyIri,
+        fromPackage: catalog.packageName,
+      });
+      report.createdKeys.push(entry.key);
+    }
+
+    for (const language of [...activeLanguages].sort()) {
+      const value = entry.translations?.[language];
+      if (value === undefined) continue;
+      if (current?.units[language]) {
+        report.skippedExistingUnits.push({ key: entry.key, language });
+        continue;
+      }
+      const unit = typeof value === 'string' ? { text: value } : value;
+      await target.upsertUnit({
+        appId,
+        key: entry.key,
+        language,
+        text: unit.text,
+        state: unit.state ?? 'reviewed',
+      });
+      report.createdUnits.push({ key: entry.key, language });
+    }
+  }
+  return report;
+}

package/src/shapes/GlossaryTerm.ts

@@ -0,0 +1,61 @@
+import { Shape } from '@_linked/core/shapes/Shape';
+import { literalProperty } from '@_linked/core/shapes/SHACL';
+import { tr } from '../ontologies/translation.js';
+import { linkedShape } from '../package.js';
+
+/**
+ * A glossary entry that steers machine translation (Plan 014 AD-L) — e.g. keep
+ * a brand/term consistent or fixed across languages. Fed to the MT provider's
+ * prompt. Per-app content like the rest of the translation model.
+ */
+@linkedShape
+export class GlossaryTerm extends Shape {
+  static targetClass = tr.GlossaryTerm;
+
+  /** The source term (English). */
+  @literalProperty({ path: tr.term, maxCount: 1 })
+  get term(): string {
+    return '';
+  }
+
+  /** Preferred translation for the target language (optional; empty = keep as-is). */
+  @literalProperty({ path: tr.glossaryTranslation, maxCount: 1 })
+  get translation(): string {
+    return '';
+  }
+
+  /** Target language this entry applies to (empty = all). */
+  @literalProperty({ path: tr.glossaryLanguage, maxCount: 1 })
+  get language(): string {
+    return '';
+  }
+
+  @literalProperty({ path: tr.description, maxCount: 1 })
+  get description(): string {
+    return '';
+  }
+
+  /**
+   * Termbase entry type: 'prefer' advises {@link translation}; 'require'
+   * enforces that wording whenever the source uses the term; 'keep' =
+   * do-not-translate, preserved exactly (proper
+   * nouns, stay-one-language words); 'forbid' = never use this word/spelling —
+   * {@link useInstead} names the replacement (alternative-spelling policing).
+   */
+  @literalProperty({ path: tr.termType, maxCount: 1 })
+  get termType(): string {
+    return 'prefer';
+  }
+
+  /** Replacement wording for a 'forbid' entry. */
+  @literalProperty({ path: tr.useInstead, maxCount: 1 })
+  get useInstead(): string {
+    return '';
+  }
+
+  /** Match with exact casing (proper nouns / all-caps brand styling). */
+  @literalProperty({ path: tr.caseSensitive, maxCount: 1 })
+  get caseSensitive(): boolean {
+    return false;
+  }
+}

package/src/shapes/TranslationInventoryOrigin.ts

@@ -0,0 +1,131 @@
+import { Shape } from '@_linked/core/shapes/Shape';
+import { literalProperty, objectProperty } from '@_linked/core/shapes/SHACL';
+import { xsd } from '@_linked/core/ontologies/xsd';
+import { tr } from '../ontologies/translation.js';
+import { linkedShape } from '../package.js';
+
+/**
+ * One observed origin for a branch translation-inventory item.
+ *
+ * Host code executes queries for this shape against the explicit branch
+ * metadata dataset. It is intentionally not globally pinned by the portable
+ * package: standalone LINKED apps may use a different metadata topology.
+ */
+@linkedShape
+export class TranslationInventoryOrigin extends Shape {
+  static targetClass = tr.TranslationInventoryOrigin;
+
+  @objectProperty({ path: tr.ofApplication, maxCount: 1 })
+  get ofApplication(): string {
+    return '';
+  }
+
+  @objectProperty({ path: tr.inventoryBranch, maxCount: 1 })
+  get branch(): string {
+    return '';
+  }
+
+  @literalProperty({ path: tr.inventoryIdentity, maxCount: 1 })
+  get identity(): string {
+    return '';
+  }
+
+  @literalProperty({ path: tr.key, maxCount: 1 })
+  get key(): string {
+    return '';
+  }
+
+  @literalProperty({ path: tr.namespace, maxCount: 1 })
+  get namespace(): string {
+    return '';
+  }
+
+  @literalProperty({ path: tr.sourceText, maxCount: 1 })
+  get sourceText(): string {
+    return '';
+  }
+
+  @literalProperty({ path: tr.kind, maxCount: 1 })
+  get kind(): string {
+    return 'ui';
+  }
+
+  @literalProperty({ path: tr.format, maxCount: 1 })
+  get format(): string {
+    return 'simple';
+  }
+
+  @literalProperty({ path: tr.description, maxCount: 1 })
+  get description(): string {
+    return '';
+  }
+
+  @literalProperty({ path: tr.inventoryStatus, maxCount: 1 })
+  get status(): string {
+    return 'pending';
+  }
+
+  @literalProperty({ path: tr.inventorySource, maxCount: 1 })
+  get sourceKind(): string {
+    return '';
+  }
+
+  @literalProperty({ path: tr.inventorySourceId, maxCount: 1 })
+  get sourceId(): string {
+    return '';
+  }
+
+  @literalProperty({ path: tr.inventoryAuthoritative, maxCount: 1 })
+  get authoritative(): boolean {
+    return false;
+  }
+
+  @literalProperty({ path: tr.inventoryFile, maxCount: 1 })
+  get file(): string {
+    return '';
+  }
+
+  @literalProperty({ path: tr.inventoryLine, datatype: xsd.integer, maxCount: 1 })
+  get line(): number {
+    return 0;
+  }
+
+  @objectProperty({ path: tr.inventoryOwner, maxCount: 1 })
+  get ownerIri(): string {
+    return '';
+  }
+
+  @objectProperty({ path: tr.inventoryShape, maxCount: 1 })
+  get shapeIri(): string {
+    return '';
+  }
+
+  @objectProperty({ path: tr.inventoryProperty, maxCount: 1 })
+  get propertyIri(): string {
+    return '';
+  }
+
+  @objectProperty({ path: tr.inventoryNode, maxCount: 1 })
+  get nodeIri(): string {
+    return '';
+  }
+
+  @literalProperty({ path: tr.fromPackage, maxCount: 1 })
+  get fromPackage(): string {
+    return '';
+  }
+
+  @literalProperty({ path: tr.inventoryTargetClass, maxCount: 1 })
+  get targetClass(): string {
+    return '';
+  }
+
+  @literalProperty({
+    path: tr.inventoryObservedAt,
+    datatype: xsd.dateTime,
+    maxCount: 1,
+  })
+  get observedAt(): Date {
+    return new Date(0);
+  }
+}

package/src/shapes/TranslationKey.ts

@@ -0,0 +1,174 @@
+import { Shape } from '@_linked/core/shapes/Shape';
+import { literalProperty, objectProperty } from '@_linked/core/shapes/SHACL';
+import { Server } from '@_linked/server-utils/utils/Server';
+import { tr } from '../ontologies/translation.js';
+import { linkedShape } from '../package.js';
+import type {
+  TranslationEntryRecord,
+  TranslationKeyVersionRecord,
+  TranslationState,
+} from '../records.js';
+import type { TranslationMessages } from '../core/messages.js';
+import type { TranslationKeyVersion } from './TranslationKeyVersion.js';
+
+/**
+ * A translatable key (Plan 014 AD-H). Covers both UI-string keys (`kind:'ui'`)
+ * and graph-content translations (`kind:'content'` + `ofNode`/`ofField`), unified
+ * in one scheme. `sourceText` is the canonical English (R7); `format` pins the
+ * message syntax so imported FormatSimple strings aren't reinterpreted as ICU
+ * (R8). Named `TranslationKey` (its per-language values are {@link TranslationUnit}s,
+ * not `Translation` — avoids collision with serve's legacy shape, R13).
+ */
+@linkedShape
+export class TranslationKey extends Shape {
+  static targetClass = tr.TranslationKey;
+
+  /** Dotted namespace grouping, e.g. "account". */
+  @literalProperty({ path: tr.namespace, maxCount: 1 })
+  get namespace(): string {
+    return '';
+  }
+
+  /** The key path, e.g. "account.title". */
+  @literalProperty({ path: tr.key, maxCount: 1 })
+  get key(): string {
+    return '';
+  }
+
+  /** Canonical English source string. */
+  @literalProperty({ path: tr.sourceText, maxCount: 1 })
+  get sourceText(): string {
+    return '';
+  }
+
+  @literalProperty({ path: tr.description, maxCount: 1 })
+  get description(): string {
+    return '';
+  }
+
+  /** 'ui' (chrome string) | 'content' (graph field). */
+  @literalProperty({ path: tr.kind, maxCount: 1 })
+  get kind(): string {
+    return 'ui';
+  }
+
+  /** IRI of the owning Application (translation content is app-scoped, AD-I). */
+  @objectProperty({ path: tr.ofApplication, maxCount: 1 })
+  get ofApplication(): string {
+    return '';
+  }
+
+  /** For kind:'content' — the IRI of the translated subject node. */
+  @objectProperty({ path: tr.ofNode, maxCount: 1 })
+  get ofNode(): string {
+    return '';
+  }
+
+  /** For kind:'content' — the field/predicate being translated. */
+  @literalProperty({ path: tr.ofField, maxCount: 1 })
+  get ofField(): string {
+    return '';
+  }
+
+  /** SHACL node-shape IRI this packaged key accompanies. */
+  @objectProperty({ path: tr.ofShape, maxCount: 1 })
+  get ofShape(): string {
+    return '';
+  }
+
+  /** Stable predicate IRI when this key describes one shape property. */
+  @objectProperty({ path: tr.ofProperty, maxCount: 1 })
+  get ofProperty(): string {
+    return '';
+  }
+
+  /** Reusable package that supplied the seed value. */
+  @literalProperty({ path: tr.fromPackage, maxCount: 1 })
+  get fromPackage(): string {
+    return '';
+  }
+
+  /**
+   * True when this app copy of a shape-owned key has been edited locally and
+   * should NOT be overwritten by shape-route propagation (AD-N: "never
+   * overwrites an app's own override"). Set when the per-app editor changes the
+   * source of a key that carries `ofShape`.
+   */
+  @literalProperty({ path: tr.overridden, maxCount: 1 })
+  get overridden(): boolean {
+    return false;
+  }
+
+  /**
+   * The shape's canonical source captured the moment this app first overrode the
+   * key — what "clear override" reverts to when no non-overridden sibling copy is
+   * available to read the current canonical from (AD-N).
+   */
+  @literalProperty({ path: tr.shapeSource, maxCount: 1 })
+  get shapeSource(): string {
+    return '';
+  }
+
+  /** Message syntax: 'simple' (FormatSimple) | 'icu'. */
+  @literalProperty({ path: tr.format, maxCount: 1 })
+  get format(): string {
+    return 'simple';
+  }
+
+  /** Current immutable source/argument contract. Populated by Plan 018 migration. */
+  @objectProperty({ path: tr.currentVersion, maxCount: 1 })
+  get currentVersion(): TranslationKeyVersion {
+    return undefined as any;
+  }
+
+  static list(data: { appId: string }) {
+    return Server.call(this, 'listKeys', data);
+  }
+
+  /** Plain app-scoped records for authoring UIs; no live Shape crosses RPC. */
+  static listEntries(data: { appId: string }) {
+    return Server.call(this, 'listEntries', data) as Promise<
+      TranslationEntryRecord[]
+    >;
+  }
+
+  static listVersions(data: { appId: string; key?: string }) {
+    return Server.call(this, 'listKeyVersions', data) as Promise<
+      TranslationKeyVersionRecord[]
+    >;
+  }
+
+  // Shape.upsert is the framework's typed graph-update builder. Keep the
+  // app-scoped translation RPC separate from that inherited API.
+  static upsertKey(data: {
+    appId: string;
+    key: string;
+    sourceText: string;
+    namespace?: string;
+    description?: string;
+    kind?: 'ui' | 'content';
+    ofNode?: string;
+    ofField?: string;
+    ofShape?: string;
+    ofProperty?: string;
+    fromPackage?: string;
+    format?: 'simple' | 'icu';
+  }): Promise<{ id: string }> {
+    return Server.call(this, 'upsertKey', data);
+  }
+
+  static upsertUnit(data: {
+    appId: string;
+    key: string;
+    language: string;
+    text: string;
+    state?: TranslationState;
+    updatedBy?: string;
+  }) {
+    return Server.call(this, 'upsertUnit', data);
+  }
+
+  static getMessages(data: { appId: string; language: string }) {
+    return Server.call(this, 'getMessages', data) as Promise<TranslationMessages>;
+  }
+}

package/src/shapes/TranslationKeyVersion.ts

@@ -0,0 +1,77 @@
+import { Shape } from '@_linked/core/shapes/Shape';
+import { literalProperty, objectProperty } from '@_linked/core/shapes/SHACL';
+import { xsd } from '@_linked/core/ontologies/xsd';
+import { tr } from '../ontologies/translation.js';
+import { linkedShape } from '../package.js';
+import { TranslationKey } from './TranslationKey.js';
+
+/** Immutable source text + runtime argument contract for one logical key. */
+@linkedShape
+export class TranslationKeyVersion extends Shape {
+  static targetClass = tr.TranslationKeyVersion;
+
+  @objectProperty({ path: tr.ofApplication, maxCount: 1 })
+  get ofApplication(): string {
+    return '';
+  }
+
+  @objectProperty({ path: tr.ofKey, shape: TranslationKey, maxCount: 1 })
+  get ofKey(): TranslationKey {
+    return undefined as any;
+  }
+
+  /** Monotonic ULID for new versions; deterministic `backfill-*` for migration. */
+  @literalProperty({ path: tr.versionId, maxCount: 1 })
+  get versionId(): string {
+    return '';
+  }
+
+  @literalProperty({ path: tr.sourceLanguage, maxCount: 1 })
+  get sourceLanguage(): string {
+    return '';
+  }
+
+  @literalProperty({ path: tr.sourceText, maxCount: 1 })
+  get sourceText(): string {
+    return '';
+  }
+
+  @literalProperty({ path: tr.format, maxCount: 1 })
+  get format(): string {
+    return 'simple';
+  }
+
+  @literalProperty({ path: tr.argumentSignature, maxCount: 1 })
+  get argumentSignature(): string {
+    return '[]';
+  }
+
+  @literalProperty({ path: tr.contractHash, maxCount: 1 })
+  get contractHash(): string {
+    return '';
+  }
+
+  @literalProperty({ path: tr.sourceHash, maxCount: 1 })
+  get sourceHash(): string {
+    return '';
+  }
+
+  @objectProperty({
+    path: tr.supersedes,
+    shape: TranslationKeyVersion,
+    maxCount: 1,
+  })
+  get supersedes(): TranslationKeyVersion {
+    return undefined as any;
+  }
+
+  @literalProperty({ path: tr.createdAt, datatype: xsd.dateTime, maxCount: 1 })
+  get createdAt(): Date {
+    return new Date(0);
+  }
+
+  @objectProperty({ path: tr.createdBy, maxCount: 1 })
+  get createdBy(): string {
+    return '';
+  }
+}

package/src/shapes/TranslationLanguage.ts

@@ -0,0 +1,51 @@
+import { Shape } from '@_linked/core/shapes/Shape';
+import { literalProperty, objectProperty } from '@_linked/core/shapes/SHACL';
+import { linkedShape } from '../package.js';
+import { tr } from '../ontologies/translation.js';
+
+/** App language configuration. Hosts choose the explicit control-plane store. */
+@linkedShape
+export class TranslationLanguage extends Shape {
+  static targetClass = tr.TranslationLanguage;
+
+  @objectProperty({ path: tr.ofApplication, maxCount: 1 })
+  get ofApplication(): string {
+    return '';
+  }
+  @objectProperty({ path: tr.languageIdentifier, maxCount: 1 })
+  get identifier(): string {
+    return '';
+  }
+  @literalProperty({ path: tr.languageCode, maxCount: 1 })
+  get code(): string {
+    return '';
+  }
+  @literalProperty({ path: tr.nativeName, maxCount: 1 })
+  get nativeName(): string {
+    return '';
+  }
+  @literalProperty({ path: tr.englishName, maxCount: 1 })
+  get englishName(): string {
+    return '';
+  }
+  @literalProperty({ path: tr.textDirection, maxCount: 1 })
+  get direction(): string {
+    return 'ltr';
+  }
+  @objectProperty({ path: tr.parentLanguage, maxCount: 1 })
+  get parent(): string {
+    return '';
+  }
+  @objectProperty({ path: tr.fallbackLanguage, maxCount: 1 })
+  get fallback(): string {
+    return '';
+  }
+  @literalProperty({ path: tr.languageEnabled, maxCount: 1 })
+  get enabled(): boolean {
+    return false;
+  }
+  @literalProperty({ path: tr.languageSupported, maxCount: 1 })
+  get supported(): boolean {
+    return false;
+  }
+}