@_linked/translation 0.2.2

package/lib/esm/shapes/TranslationProvider.d.ts

@@ -0,0 +1,409 @@
+import { ShapeProvider } from '@_linked/server-utils/utils/ShapeProvider';
+import type { GlossaryTermRecord, TranslationEntryRecord, TranslationMemoryMatchRecord, TranslationMemoryPretranslateCandidate, TranslationMemoryPretranslateReport, TranslationMemoryRecord, TranslationProposalDecision, TranslationRevisionRecord, TranslationRevisionStatus, TranslationState, TranslationKeyVersionRecord, TranslationReleaseRecord, TranslationUnitRecord } from '../records.js';
+import { TranslationKey } from './TranslationKey.js';
+import type { TranslationMessages } from '../core/messages.js';
+export interface TranslationKeyInput {
+    appId: string;
+    key: string;
+    sourceText: string;
+    namespace?: string;
+    description?: string;
+    kind?: 'ui' | 'content';
+    ofNode?: string;
+    ofField?: string;
+    ofShape?: string;
+    ofProperty?: string;
+    fromPackage?: string;
+    /** Force the override flag; when omitted it is derived (see upsertTranslationKey). */
+    overridden?: boolean;
+    format?: 'simple' | 'icu';
+    sourceLanguage?: string;
+}
+export interface TranslationUnitInput {
+    appId: string;
+    key: string;
+    language: string;
+    text: string;
+    state?: TranslationState;
+    updatedBy?: string;
+}
+/** Who/what authored a unit write — recorded on its `applied` revision (AD-P). */
+export interface TranslationAuthorship {
+    /** WebID of the human author, or the MT provider IRI. */
+    author?: string;
+    authorKind?: 'human' | 'machine';
+    /** MT provider key when authorKind is 'machine'. */
+    mtProvider?: string;
+    note?: string;
+}
+type TranslationKeyRow = Omit<TranslationEntryRecord, 'units'>;
+type TranslationUnitRow = TranslationUnitRecord & {
+    ofKey?: {
+        key?: string;
+    };
+    ofKeyVersion?: string | {
+        id?: string;
+    };
+};
+type TranslationKeyVersionRow = TranslationKeyVersionRecord & {
+    ofKey?: {
+        key?: string;
+    };
+};
+type TranslationMemoryUnitRow = {
+    id?: string | {
+        id?: string;
+    };
+    language?: string;
+    text?: string;
+    state?: string;
+    updatedAt?: string;
+    ofKey?: {
+        key?: string;
+    };
+    ofKeyVersion?: string | {
+        id?: string;
+        sourceText?: string;
+        sourceHash?: string;
+        contractHash?: string;
+    };
+};
+/**
+ * Shared TM/carry-forward classifier (Plan 018 §5.5). Exact source matches may
+ * cross logical keys; changed-source carry-forward candidates never do.
+ */
+export declare function classifyTranslationMemoryMatches(input: {
+    key: string;
+    language: string;
+    currentVersion: TranslationKeyVersionRecord;
+    rows?: TranslationMemoryUnitRow[];
+}): TranslationMemoryMatchRecord[];
+/** Build the reviewed-unit index shown in the explicit TM browser. */
+export declare function toTranslationMemoryRecords(rows?: TranslationMemoryUnitRow[]): TranslationMemoryRecord[];
+/**
+ * Find current untranslated cells that can be filled without MT cost.
+ * Source AND argument-contract hashes must match; the current version can
+ * never source itself.
+ */
+export declare function findExactMemoryPretranslations(input: {
+    entries: TranslationEntryRecord[];
+    memory: TranslationMemoryRecord[];
+    language: string;
+}): TranslationMemoryPretranslateCandidate[];
+/**
+ * Convert LINKED query rows into a deterministic, serialization-safe editor
+ * contract. Exported for package-unit testing; it performs no I/O.
+ */
+export declare function groupTranslationEntries(keyRows?: TranslationKeyRow[], unitRows?: TranslationUnitRow[], versionRows?: TranslationKeyVersionRow[]): TranslationEntryRecord[];
+/** App-scoped key read shared by the RPC provider and managed key-sync flows. */
+export declare function listTranslationKeys(data: {
+    appId: string;
+}): Promise<({
+    namespace: string;
+} & {
+    id: string;
+} & {
+    key: string;
+} & {
+    sourceText: string;
+} & {
+    description: string;
+} & {
+    kind: string;
+} & {
+    ofNode: string;
+} & {
+    ofField: string;
+} & {
+    ofShape: string;
+} & {
+    ofProperty: string;
+} & {
+    fromPackage: string;
+} & {
+    overridden: boolean;
+} & {
+    overridden: boolean;
+} & {
+    format: string;
+} & {
+    currentVersion: {
+        id: string;
+    };
+})[]>;
+/**
+ * App-scoped keys + grouped language units as plain records — the read behind
+ * the editor RPC AND the publish/compile flow (Plan 016 P2.3). No auth of its
+ * own (the RPC wrapper gates); callers on the server run it in request context.
+ */
+export declare function listTranslationEntries(data: {
+    appId: string;
+}): Promise<TranslationEntryRecord[]>;
+export declare function listTranslationKeyVersions(data: {
+    appId: string;
+    key?: string;
+}): Promise<TranslationKeyVersionRecord[]>;
+export declare function listTranslationReleases(data: {
+    appId: string;
+}): Promise<TranslationReleaseRecord[]>;
+export declare function createTranslationRelease(data: Omit<TranslationReleaseRecord, 'id' | 'createdAt'> & {
+    createdAt?: string;
+}): Promise<TranslationReleaseRecord>;
+export declare function advanceTranslationReleaseHotfix(data: {
+    id: string;
+    expectedSequence: number;
+    hotfixSequence: number;
+    manifestHash: string;
+}): Promise<TranslationReleaseRecord>;
+/**
+ * Convert LINKED revision rows into plain RPC-safe records, newest first.
+ * Exported for package-unit testing; performs no I/O.
+ */
+export declare function toRevisionRecords(rows?: Array<Record<string, unknown>>): TranslationRevisionRecord[];
+export declare function getTranslationRevision(data: {
+    appId: string;
+    revisionId: string;
+}): Promise<TranslationRevisionRecord | null>;
+/** Pending human proposals for the app, optionally narrowed to one language. */
+export declare function listTranslationProposals(data: {
+    appId: string;
+    language?: string;
+}): Promise<TranslationRevisionRecord[]>;
+export declare function decideTranslationProposal(data: {
+    appId: string;
+    revisionId: string;
+    decision: 'accept' | 'reject';
+    note?: string;
+}, reviewer?: string): Promise<TranslationProposalDecision>;
+/**
+ * Idempotent key write shared by the RPC provider and managed key-sync flows.
+ * Source drift marks every existing language unit stale before returning.
+ */
+export declare function upsertTranslationKey(data: TranslationKeyInput, authorship?: {
+    createdBy?: string;
+}): Promise<{
+    id: string;
+    versionId: string;
+    versionCreated: boolean;
+}>;
+/**
+ * Append one revision WITHOUT touching the unit (Plan 017 AD-P) — the write
+ * path for MT SUGGESTIONS (Slice B) and translator PROPOSALS (Slice C): a
+ * pending value a reviewer/editor applies later. `basedOnText` should carry
+ * the unit text visible to the author, for conflict detection at decision time.
+ */
+export declare function createTranslationRevision(data: {
+    appId: string;
+    key: string;
+    language: string;
+    text: string;
+    status: TranslationRevisionStatus;
+    author?: string;
+    authorKind?: 'human' | 'machine';
+    mtProvider?: string;
+    basedOnText?: string;
+    note?: string;
+}): Promise<{
+    id: string;
+}>;
+/**
+ * Idempotent unit write shared by the RPC provider, import, and (P4) MT flows.
+ * Every write that CHANGES the text also records an append-only
+ * `status:'applied'` `TranslationRevision` (Plan 017 AD-P) carrying the
+ * previous text as `basedOnText` — the audit trail behind the history UI.
+ * Re-saving identical text updates state/provenance without a revision.
+ */
+export declare function upsertTranslationUnit(data: TranslationUnitInput, authorship?: TranslationAuthorship): Promise<{
+    id: string;
+    revisionId?: string;
+}>;
+/** One app-scoped lookup powers both exact TM and same-key carry-forward. */
+export declare function listTranslationMemoryMatches(data: {
+    appId: string;
+    key: string;
+    language: string;
+}): Promise<TranslationMemoryMatchRecord[]>;
+/** App-scoped reviewed-unit index for search, audit, and exact reuse. */
+export declare function listTranslationMemory(data: {
+    appId: string;
+}): Promise<TranslationMemoryRecord[]>;
+/** Preview or apply every safe exact-match TM candidate for one language. */
+export declare function pretranslateFromMemory(data: {
+    appId: string;
+    language: string;
+    dryRun?: boolean;
+}, authorship?: {
+    author?: string;
+}): Promise<TranslationMemoryPretranslateReport>;
+/** App-data termbase read shared by Studio, MT, and publish quality gates. */
+export declare function listGlossaryTerms(data: {
+    appId: string;
+}): Promise<GlossaryTermRecord[]>;
+/**
+ * Apply a server-validated memory candidate. Exact matches retain `machine`
+ * state and `tm` provenance; changed-source carry-forward is an explicit
+ * reviewer action and becomes reviewed.
+ */
+export declare function applyTranslationMemoryMatch(data: {
+    appId: string;
+    key: string;
+    language: string;
+    unitId: string;
+}, authorship?: {
+    author?: string;
+}): Promise<TranslationUnitRecord>;
+/** Server boundary for app-scoped translation keys and language units. */
+export declare class TranslationProvider extends ShapeProvider {
+    shape: typeof TranslationKey;
+    /**
+     * Authoring gate. Reads `linkedAuth` off the request the LINKED server already
+     * populates — framework-level, so this stays portable (no CN/create-now-js
+     * import, AD-G). Anonymous callers can no longer read or write an app's
+     * translation content via `/call`. Fine-grained "is translation enabled for
+     * this app + is the caller a project member" gating is a Create Now concern and
+     * is enforced additionally at the CN route layer (`isTranslationEnabledForApp`).
+     * `getMessages` intentionally stays public — it is the app's runtime string
+     * fetch, not an authoring surface.
+     */
+    private requireAuthor;
+    private requireAccess;
+    listKeys(data: {
+        appId: string;
+    }): Promise<({
+        namespace: string;
+    } & {
+        id: string;
+    } & {
+        key: string;
+    } & {
+        sourceText: string;
+    } & {
+        description: string;
+    } & {
+        kind: string;
+    } & {
+        ofNode: string;
+    } & {
+        ofField: string;
+    } & {
+        ofShape: string;
+    } & {
+        ofProperty: string;
+    } & {
+        fromPackage: string;
+    } & {
+        overridden: boolean;
+    } & {
+        overridden: boolean;
+    } & {
+        format: string;
+    } & {
+        currentVersion: {
+            id: string;
+        };
+    })[]>;
+    listEntries(data: {
+        appId: string;
+    }): Promise<TranslationEntryRecord[]>;
+    listKeyVersions(data: {
+        appId: string;
+        key?: string;
+    }): Promise<TranslationKeyVersionRecord[]>;
+    listMemoryMatches(data: {
+        appId: string;
+        key: string;
+        language: string;
+    }): Promise<TranslationMemoryMatchRecord[]>;
+    proposeRevision(data: {
+        appId: string;
+        key: string;
+        language: string;
+        text: string;
+        basedOnText?: string;
+        note?: string;
+    }): Promise<{
+        id: string;
+    }>;
+    listProposals(data: {
+        appId: string;
+        language?: string;
+    }): Promise<TranslationRevisionRecord[]>;
+    decideProposal(data: {
+        appId: string;
+        revisionId: string;
+        decision: 'accept' | 'reject';
+        note?: string;
+    }): Promise<TranslationProposalDecision>;
+    listMemory(data: {
+        appId: string;
+    }): Promise<TranslationMemoryRecord[]>;
+    pretranslateMemory(data: {
+        appId: string;
+        language: string;
+        dryRun?: boolean;
+    }): Promise<TranslationMemoryPretranslateReport>;
+    applyMemoryMatch(data: {
+        appId: string;
+        key: string;
+        language: string;
+        unitId: string;
+    }): Promise<TranslationUnitRecord>;
+    listReleases(data: {
+        appId: string;
+    }): Promise<TranslationReleaseRecord[]>;
+    createRelease(data: Omit<TranslationReleaseRecord, 'id' | 'createdAt'> & {
+        createdAt?: string;
+    }): Promise<TranslationReleaseRecord>;
+    advanceReleaseHotfix(data: {
+        id: string;
+        expectedSequence: number;
+        hotfixSequence: number;
+        manifestHash: string;
+    }): Promise<TranslationReleaseRecord>;
+    upsertKey(data: TranslationKeyInput): Promise<{
+        id: string;
+    }>;
+    /** WebID of the signed-in caller — never trust a client-supplied author. */
+    private authorIri;
+    upsertUnit(data: TranslationUnitInput): Promise<{
+        id: string;
+    }>;
+    /**
+     * Glossary CRUD (Plan 017 Slice B). App-data is branch-routed per app, so
+     * every GlossaryTerm in context belongs to the calling app; the appId only
+     * anchors the IRIs. Uniqueness = (term, language) — upsert is
+     * delete-then-create on that identity.
+     */
+    listGlossary(data: {
+        appId: string;
+    }): Promise<GlossaryTermRecord[]>;
+    upsertGlossaryTerm(data: {
+        appId: string;
+        term: string;
+        termType?: 'prefer' | 'require' | 'keep' | 'forbid';
+        translation?: string;
+        useInstead?: string;
+        language?: string;
+        caseSensitive?: boolean;
+        description?: string;
+    }): Promise<{
+        id: string;
+    }>;
+    deleteGlossaryTerm(data: {
+        appId: string;
+        id: string;
+    }): Promise<{
+        deleted: boolean;
+    }>;
+    /** History for one (key, language) cell — newest first (Plan 017 AD-P). */
+    listRevisions(data: {
+        appId: string;
+        key: string;
+        language: string;
+    }): Promise<TranslationRevisionRecord[]>;
+    getMessages(data: {
+        appId: string;
+        language: string;
+    }): Promise<TranslationMessages>;
+}
+export {};