@_linked/translation 0.2.2

package/README.md

@@ -0,0 +1,102 @@
+# `@_linked/translation`
+
+Graph-native translation management for LINKED applications. It provides:
+
+- `TranslationKey`, `TranslationUnit`, and `GlossaryTerm` shapes;
+- a server provider for app-scoped keys and language messages;
+- framework-light message formatting;
+- React bindings compatible with Tolgee-style `useTranslate()` calls;
+- a static key-sync tool that reports source drift, conflicts, and orphans.
+
+## Install
+
+```sh
+npm install @_linked/translation
+```
+
+## Entry points
+
+- `@_linked/translation` — shapes and message model
+- `@_linked/translation/backend` — LINKED server provider registration
+- `@_linked/translation/react` — provider, hooks, and `<T>`
+- `@_linked/translation/key-sync` — development-time source extraction and sync
+- `@_linked/translation/key-sync/node` — recursive source-tree scan + dry-run/apply orchestration
+- `@_linked/translation/shape-catalog` — package-owned translations attached to stable shape/property IRIs
+- `@_linked/translation/discovery` — portable declarations and deterministic inventory merging
+- `@_linked/translation/linked-discovery` — serialized LINKED package catalogs
+- `@_linked/translation/archive` — full-fidelity backup and pure restore planning
+
+## Code-canonical discovery
+
+Create Now's Host Agent can inventory a managed app without running its
+packages:
+
+- literal `t()` and `<T>` calls are extracted from `src/`;
+- finite dynamic key families are declared in a root
+  `translation.discovery.json`;
+- a reusable package points to serialized catalog JSON with
+  `"linkedTranslationCatalog": "./translation.catalog.json"` in its
+  `package.json`.
+
+The Host Agent walks installed `dependencies` and `optionalDependencies`,
+parses only JSON, and never imports package JavaScript. A package catalog path
+must remain inside that package. Inventory is branch-local because discovery
+always runs against the exact managed branch clone and persists into that
+branch's metadata dataset.
+
+## Full-fidelity archives
+
+The archive contract complements lossy XLIFF/CSV/JSON interchange. It stores
+translation configuration, keys and versions, units, glossary/style,
+revision history, provenance, content translations, and historical
+release/build references in a deterministic hash-inventoried ZIP. Catalog
+objects may be included for offline recovery or retained as references.
+
+Restore planning is explicit:
+
+- same-app recovery preserves stable IDs and blocks same-ID/different-content
+  collisions;
+- cross-app migration deterministically rebases only app-scoped IRIs and
+  requires explicit node/field mappings for graph content;
+- authors remain inert provenance, and releases always restore as retired
+  history pending a normal target-side publish.
+
+Secrets, sessions, collaborators/invites, entitlements, and identity records
+are rejected at the portable archive boundary.
+
+## Translations shipped with a shape
+
+Reusable asset packages can include a schema-versioned shape translation
+catalog. The catalog is code-canonical package content; installation copies
+only missing keys and active-language units into the consuming app's graph.
+Existing app-authored translations are never overwritten. Packages may export
+the TypeScript object or ship the same contract as JSON for Create Now's Host
+Agent to discover without executing application code.
+
+Create Now's editor, menu contribution, entitlement, and capability activation
+are deliberately not part of this package. They live in Create Now's
+`translation-studio` feature so applications can use this runtime without
+depending on Create Now.
+
+The package targets `@_linked/core` 2.14.4 and uses the permanent identifier
+namespace `https://id.linked.cm/translation/`.
+
+## Open language configuration
+
+Language codes are BCP-47 strings. `TranslationLanguage` stores app-scoped RDF
+resources for the code, stable language identifier, native and English names,
+text direction, parent/fallback links, and enabled/supported flags. Hosts choose
+an explicit configuration store; the portable package does not assume a CN
+control plane. `defineLanguage` supplies editable defaults from the platform's
+Unicode locale data. Validate relationship cycles before saving.
+
+Publish the resource list as `languages.json` alongside the catalogs. Wire
+`createCdnLanguageLoader({base})` to the React provider's `loadLanguages` prop
+and `createCdnLoader({base})` to `loadMessages`. The language menu can then grow
+without an app release. The CDN base remains caller-owned. Complete compiled
+catalogs follow the configured fallback chain before the source language;
+regional variants are separate tags, with no automatic Chinese-script conversion.
+
+Core 2.18.1 compatibility: call `TranslationKey.upsertKey` for translation
+creation. The inherited generic `Shape.upsert` API is preserved. Date-valued
+shape mutations use `Date`; serialized translation records keep ISO strings.

package/lib/cjs/data/translation.json

@@ -0,0 +1,8 @@
+{
+  "@context": {
+    "rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
+    "rdfs": "http://www.w3.org/2000/01/rdf-schema#",
+    "tr": "https://id.linked.cm/translation/vocab#"
+  },
+  "@graph": []
+}

package/lib/esm/archive.d.ts

@@ -0,0 +1,133 @@
+import { type TranslationJsonArchiveLimits } from './formats/json.js';
+/** Full backups include every language and its revision history. CAT-file
+ * imports retain their smaller defaults; native backups remain bounded too. */
+export declare const DEFAULT_TRANSLATION_ARCHIVE_LIMITS: TranslationJsonArchiveLimits;
+export declare const TRANSLATION_ARCHIVE_MANIFEST_PATH = "create-now.translation-archive.json";
+export type TranslationArchiveCollection = 'configuration' | 'keys' | 'keyVersions' | 'units' | 'glossary' | 'style' | 'revisions' | 'provenance' | 'content' | 'releases' | 'buildPins';
+export declare const TRANSLATION_ARCHIVE_COLLECTIONS: readonly TranslationArchiveCollection[];
+export declare const TRANSLATION_ARCHIVE_EXCLUSIONS: readonly string[];
+export type TranslationArchiveJson = null | boolean | number | string | TranslationArchiveJson[] | {
+    [key: string]: TranslationArchiveJson;
+};
+export interface TranslationArchiveEntityInput {
+    id: string;
+    data: Record<string, TranslationArchiveJson>;
+}
+export interface TranslationArchiveEntity extends TranslationArchiveEntityInput {
+    contentHash: string;
+}
+export interface TranslationArchiveObjectInput {
+    hash: string;
+    body?: Uint8Array;
+    mediaType?: string;
+}
+export interface TranslationArchiveSnapshot {
+    appId: string;
+    branchId: string;
+    revisionWatermark: string;
+    createdAt?: string;
+    collections: Partial<Record<TranslationArchiveCollection, TranslationArchiveEntityInput[]>>;
+    /** Immutable release catalog objects; omitted bodies remain references only. */
+    objects?: TranslationArchiveObjectInput[];
+}
+export interface TranslationArchiveFileInventory {
+    path: string;
+    collection: TranslationArchiveCollection;
+    hash: string;
+    bytes: number;
+    records: number;
+}
+export interface TranslationArchiveObjectInventory {
+    path: string;
+    hash: string;
+    bytes?: number;
+    mediaType?: string;
+    included: boolean;
+}
+export interface TranslationArchiveManifest {
+    schemaVersion: 1;
+    format: 'create-now-translation-archive';
+    appId: string;
+    branchId: string;
+    revisionWatermark: string;
+    createdAt?: string;
+    files: TranslationArchiveFileInventory[];
+    objects: TranslationArchiveObjectInventory[];
+    exclusions: string[];
+    archiveContentHash: string;
+}
+export interface SerializedTranslationArchive {
+    fileName: string;
+    mediaType: 'application/zip';
+    body: Uint8Array;
+    manifest: TranslationArchiveManifest;
+}
+export interface ParsedTranslationArchive {
+    manifest: TranslationArchiveManifest;
+    collections: Record<TranslationArchiveCollection, TranslationArchiveEntity[]>;
+    objects: Array<{
+        hash: string;
+        body?: Uint8Array;
+        mediaType?: string;
+    }>;
+}
+export interface TranslationArchiveTargetRecord {
+    id: string;
+    contentHash: string;
+}
+export interface TranslationArchiveContentMapping {
+    sourceNodeIri: string;
+    sourceFieldIri: string;
+    targetNodeIri: string;
+    targetFieldIri: string;
+}
+export interface PlanTranslationArchiveRestoreOptions {
+    mode: 'same-app' | 'cross-app';
+    targetAppId: string;
+    targetRecords?: TranslationArchiveTargetRecord[];
+    contentMappings?: TranslationArchiveContentMapping[];
+    targetRevisionWatermark?: string;
+}
+export interface TranslationArchiveRestoreDecision {
+    collection: TranslationArchiveCollection;
+    sourceId: string;
+    targetId: string;
+    action: 'create' | 'skip' | 'collision' | 'unmapped';
+    expectedTargetContentHash?: string;
+    record?: TranslationArchiveEntity;
+    reason?: string;
+    retryKey: string;
+}
+export interface TranslationArchiveRestorePlan {
+    schemaVersion: 1;
+    mode: 'same-app' | 'cross-app';
+    sourceAppId: string;
+    targetAppId: string;
+    sourceBranchId: string;
+    archiveContentHash: string;
+    archiveRevisionWatermark: string;
+    expectedTargetRevisionWatermark?: string;
+    blocked: boolean;
+    decisions: TranslationArchiveRestoreDecision[];
+    iriMappings: Record<string, string>;
+    creates: number;
+    skips: number;
+    collisions: number;
+    unresolvedContent: number;
+    historicalReleases: number;
+    identityWrites: 0;
+    assignmentWrites: 0;
+}
+/** Create a deterministic, full-fidelity Create Now translation archive. */
+export declare function createTranslationArchive(snapshot: TranslationArchiveSnapshot, options?: {
+    limits?: Partial<TranslationJsonArchiveLimits>;
+}): Promise<SerializedTranslationArchive>;
+/** Parse and verify every declared content file and optional catalog object. */
+export declare function parseTranslationArchive(input: Uint8Array, options?: {
+    limits?: Partial<TranslationJsonArchiveLimits>;
+}): Promise<ParsedTranslationArchive>;
+/**
+ * Build a pure, conditional restore plan. A blocked plan is never executable:
+ * collisions and unresolved cross-app content mappings must be resolved first.
+ */
+export declare function planTranslationArchiveRestore(archive: ParsedTranslationArchive, options: PlanTranslationArchiveRestoreOptions): Promise<TranslationArchiveRestorePlan>;