@purposeinplay/payload-ai-translate 0.1.0

package/dist/lexical/classifier.js

@@ -0,0 +1,108 @@
+const RECURSE_TYPES = new Set([
+    'paragraph',
+    'heading',
+    'quote',
+    'listitem',
+    'list',
+    'link'
+]);
+const SKIP_TYPES = new Set([
+    'text',
+    'linebreak',
+    'code',
+    'horizontalrule'
+]);
+export function classifyNode(node, registeredNodes) {
+    const { type } = node;
+    // Built-in recurse types
+    if (RECURSE_TYPES.has(type)) {
+        return {
+            node,
+            classification: 'recurse'
+        };
+    }
+    // Built-in skip types
+    if (SKIP_TYPES.has(type)) {
+        return {
+            node,
+            classification: 'skip'
+        };
+    }
+    // Lexical's `BlocksFeature` embeds Payload blocks inline as
+    // `type: 'block'` nodes with `fields: { blockType, ...blockData }`.
+    // Without this branch the classifier falls through to the unknown-type
+    // path and silently skips the entire block — losing every translatable
+    // field inside it (banner.title, banner.content, etc.).
+    if (type === 'block') {
+        return {
+            node,
+            classification: 'block'
+        };
+    }
+    // Upload / image — translate alt text if present
+    if (type === 'upload') {
+        const alt = node.fields?.alt ?? node.alt;
+        if (alt) {
+            return {
+                node,
+                classification: 'translate-attr',
+                translatableAttributes: [
+                    'alt'
+                ]
+            };
+        }
+        return {
+            node,
+            classification: 'skip'
+        };
+    }
+    // Autolink — skip when the visible text equals the URL
+    if (type === 'autolink') {
+        const url = node.fields?.url;
+        const childText = collectText(node.children);
+        if (url && childText === url) {
+            return {
+                node,
+                classification: 'skip'
+            };
+        }
+        return {
+            node,
+            classification: 'recurse'
+        };
+    }
+    // Custom / registered nodes
+    if (registeredNodes?.length) {
+        const registration = registeredNodes.find((r)=>r.type === type);
+        if (registration) {
+            if (registration.translatable && registration.translatableAttributes?.length) {
+                return {
+                    node,
+                    classification: 'translate-attr',
+                    translatableAttributes: registration.translatableAttributes
+                };
+            }
+            return {
+                node,
+                classification: 'skip'
+            };
+        }
+    }
+    // Unknown node type — skip with warning
+    console.warn(`[ai-translate] Unknown Lexical node type "${type}" — skipping. Register it via lexicalNodes config to translate its attributes.`);
+    return {
+        node,
+        classification: 'skip'
+    };
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function collectText(children) {
+    if (!children) return '';
+    return children.map((child)=>{
+        if (child.type === 'text') return child.text ?? '';
+        if (child.children) return collectText(child.children);
+        return '';
+    }).join('');
+}

package/dist/lexical/deserializer.d.ts

@@ -0,0 +1,4 @@
+import type { LexicalNodeRegistration } from '../types.js';
+import type { LexicalRoot } from './types.js';
+export declare function deserializeLexicalTree(originalRoot: LexicalRoot, translatedUnits: Map<string, string>, registeredNodes?: LexicalNodeRegistration[]): LexicalRoot;
+export { validatePlaceholderIntegrity } from './placeholder-integrity.js';

package/dist/lexical/deserializer.js

@@ -0,0 +1,263 @@
+import { classifyNode } from './classifier.js';
+import { parsePlaceholders } from './placeholders.js';
+import { serializeLexicalTree } from './serializer.js';
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+export function deserializeLexicalTree(originalRoot, translatedUnits, registeredNodes) {
+    const cloned = structuredClone(originalRoot);
+    // Build the same blockId sequence the serializer would produce
+    const originalUnits = serializeLexicalTree(originalRoot, registeredNodes);
+    const unitMap = new Map();
+    for (const unit of originalUnits){
+        unitMap.set(unit.blockId, unit);
+    }
+    // Walk the cloned tree in the same order as serialization
+    let counter = 0;
+    function nextBlockId() {
+        return `blk_${counter++}`;
+    }
+    function walkNodes(nodes) {
+        for (const node of nodes){
+            const classified = classifyNode(node, registeredNodes);
+            switch(classified.classification){
+                case 'recurse':
+                    {
+                        if (node.type === 'paragraph' || node.type === 'heading' || node.type === 'quote' || node.type === 'listitem') {
+                            const hasInlineContent = hasNonListChildren(node);
+                            if (hasInlineContent) {
+                                const blockId = nextBlockId();
+                                const translated = translatedUnits.get(blockId);
+                                if (translated !== undefined) {
+                                    const parsed = parsePlaceholders(translated);
+                                    // Preserve nested lists — they aren't part of inline content
+                                    const nestedLists = (node.children ?? []).filter((c)=>c.type === 'list');
+                                    const rebuilt = segmentsToNodes(parsed);
+                                    node.children = [
+                                        ...rebuilt,
+                                        ...nestedLists
+                                    ];
+                                }
+                            }
+                            // Walk nested lists inside listitems
+                            if (node.type === 'listitem' && node.children) {
+                                for (const child of node.children){
+                                    if (child.type === 'list') {
+                                        walkNodes(child.children ?? []);
+                                    }
+                                }
+                            }
+                        } else if (node.type === 'list') {
+                            walkNodes(node.children ?? []);
+                        } else {
+                            walkNodes(node.children ?? []);
+                        }
+                        break;
+                    }
+                case 'translate-attr':
+                    {
+                        if (node.type === 'upload') {
+                            const alt = getNodeAlt(node);
+                            if (alt) {
+                                const blockId = nextBlockId();
+                                const translated = translatedUnits.get(blockId);
+                                if (translated !== undefined) {
+                                    setNodeAlt(node, translated);
+                                }
+                            }
+                        } else if (classified.translatableAttributes) {
+                            for (const attr of classified.translatableAttributes){
+                                const value = getNestedAttr(node, attr);
+                                if (typeof value === 'string' && value.trim().length > 0) {
+                                    const blockId = nextBlockId();
+                                    const translated = translatedUnits.get(blockId);
+                                    if (translated !== undefined) {
+                                        setNestedAttr(node, attr, translated);
+                                    }
+                                }
+                            }
+                        }
+                        break;
+                    }
+                case 'block':
+                    {
+                        // Mirror of the serializer's 'block' case — walk the embedded
+                        // block's `fields` in the SAME deterministic order so blockIds
+                        // line up. Translated values are mutated in-place on the
+                        // cloned node.
+                        const blockFields = node.fields ?? {};
+                        applyTranslatedBlockData(blockFields, translatedUnits, nextBlockId, walkNodes);
+                        break;
+                    }
+                case 'skip':
+                    break;
+            }
+        }
+    }
+    walkNodes(cloned.root.children ?? []);
+    return cloned;
+}
+export { validatePlaceholderIntegrity } from './placeholder-integrity.js';
+// ---------------------------------------------------------------------------
+// Segment → LexicalNode conversion
+// ---------------------------------------------------------------------------
+function segmentsToNodes(segments) {
+    const nodes = [];
+    for (const segment of segments){
+        switch(segment.type){
+            case 'text':
+                {
+                    if (segment.content.length > 0) {
+                        nodes.push({
+                            type: 'text',
+                            text: segment.content,
+                            format: 0
+                        });
+                    }
+                    break;
+                }
+            case 'format':
+                {
+                    // Each child text segment becomes a text node with this format
+                    const formatChildren = flattenToTextSegments(segment.children);
+                    for (const child of formatChildren){
+                        nodes.push({
+                            type: 'text',
+                            text: child.content,
+                            format: segment.format
+                        });
+                    }
+                    break;
+                }
+            case 'link':
+                {
+                    nodes.push({
+                        type: 'link',
+                        fields: segment.fields,
+                        children: segmentsToNodes(segment.children)
+                    });
+                    break;
+                }
+        }
+    }
+    return nodes;
+}
+/**
+ * Flattens nested parsed segments down to text segments, preserving text
+ * content from format/link children. This is used when a format placeholder
+ * contains other segments — we extract all leaf text.
+ */ function flattenToTextSegments(segments) {
+    const result = [];
+    for (const segment of segments){
+        switch(segment.type){
+            case 'text':
+                result.push({
+                    content: segment.content
+                });
+                break;
+            case 'format':
+            case 'link':
+                result.push(...flattenToTextSegments(segment.children));
+                break;
+        }
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function hasNonListChildren(node) {
+    if (!node.children || node.children.length === 0) return false;
+    return node.children.some((c)=>c.type !== 'list');
+}
+function getNodeAlt(node) {
+    const fromFields = node.fields?.alt;
+    const fromNode = node.alt;
+    const alt = fromFields ?? fromNode;
+    return typeof alt === 'string' ? alt : undefined;
+}
+function setNodeAlt(node, value) {
+    if (node.fields && 'alt' in node.fields) {
+        node.fields.alt = value;
+    } else {
+        node.alt = value;
+    }
+}
+function getNestedAttr(node, attr) {
+    if (node.fields && attr in node.fields) {
+        return node.fields[attr];
+    }
+    return node[attr];
+}
+function setNestedAttr(node, attr, value) {
+    if (node.fields && attr in node.fields) {
+        node.fields[attr] = value;
+    } else {
+        node[attr] = value;
+    }
+}
+/**
+ * Mirror walk of `serializeBlockData` in `serializer.ts`. Visit keys in
+ * the same `Object.entries` order, consume blockIds in the same order,
+ * and replace translated strings + nested Lexical roots in place. Keep
+ * the implementations in lockstep — any divergence drops translations
+ * silently.
+ */ function applyTranslatedBlockData(data, translatedUnits, nextBlockId, innerWalkNodes) {
+    for (const [key, value] of Object.entries(data)){
+        if (key === 'id' || key === 'blockType' || key === 'blockName') continue;
+        if (typeof value === 'string') {
+            // Mirror the serializer's skip — select-option-shaped strings
+            // weren't emitted as translation units, so don't consume a
+            // blockId for them here either, or the sequence will desync.
+            if (value.trim().length > 0 && !isLikelySelectOption(value)) {
+                const blockId = nextBlockId();
+                const translated = translatedUnits.get(blockId);
+                if (translated !== undefined) {
+                    data[key] = translated;
+                }
+            }
+            continue;
+        }
+        if (isLexicalRootValue(value)) {
+            // Recurse via the outer walker so nested richText placeholders
+            // share the parent's blockId sequence + reuse all the existing
+            // inline-format/link handling.
+            innerWalkNodes(value.root.children ?? []);
+            continue;
+        }
+        if (Array.isArray(value)) {
+            for(let i = 0; i < value.length; i++){
+                const item = value[i];
+                if (item && typeof item === 'object' && !Array.isArray(item)) {
+                    applyTranslatedBlockData(item, translatedUnits, nextBlockId, innerWalkNodes);
+                } else if (typeof item === 'string' && item.trim().length > 0) {
+                    const blockId = nextBlockId();
+                    const translated = translatedUnits.get(blockId);
+                    if (translated !== undefined) {
+                        value[i] = translated;
+                    }
+                }
+            }
+            continue;
+        }
+        if (value && typeof value === 'object') {
+            applyTranslatedBlockData(value, translatedUnits, nextBlockId, innerWalkNodes);
+        }
+    }
+}
+function isLexicalRootValue(value) {
+    if (value === null || typeof value !== 'object') return false;
+    const obj = value;
+    return 'root' in obj && obj.root !== null && typeof obj.root === 'object';
+}
+/**
+ * Mirror of `serializer.isLikelySelectOption`. Keep the regexes in
+ * lockstep — divergence would desync the blockId sequence.
+ */ function isLikelySelectOption(text) {
+    const t = text.trim();
+    if (t.length === 0 || t.length > 30) return false;
+    if (/\s/.test(t)) return false;
+    if (/^[a-z][a-z0-9_-]{0,20}$/.test(t)) return true;
+    if (/^[a-z]+(?:[A-Z][a-z0-9]+)+$/.test(t) && t.length <= 30) return true;
+    return false;
+}

package/dist/lexical/placeholder-integrity.d.ts

@@ -0,0 +1,6 @@
+export type PlaceholderIntegrityResult = {
+    valid: boolean;
+    missingIds: string[];
+    extraIds: string[];
+};
+export declare function validatePlaceholderIntegrity(original: string, translated: string): PlaceholderIntegrityResult;

package/dist/lexical/placeholder-integrity.js

@@ -0,0 +1,21 @@
+const PH_ID_REGEX = /<ph id="([^"]+)">/g;
+export function validatePlaceholderIntegrity(original, translated) {
+    const originalIds = extractPlaceholderIds(original);
+    const translatedIds = extractPlaceholderIds(translated);
+    const missingIds = originalIds.filter((id)=>!translatedIds.includes(id));
+    const extraIds = translatedIds.filter((id)=>!originalIds.includes(id));
+    return {
+        valid: missingIds.length === 0 && extraIds.length === 0,
+        missingIds,
+        extraIds
+    };
+}
+function extractPlaceholderIds(text) {
+    const ids = [];
+    let match;
+    const regex = new RegExp(PH_ID_REGEX.source, 'g');
+    while((match = regex.exec(text)) !== null){
+        ids.push(match[1]);
+    }
+    return ids;
+}

package/dist/lexical/placeholders.d.ts

@@ -0,0 +1,21 @@
+export type ParsedSegment = {
+    type: 'text';
+    content: string;
+} | {
+    type: 'format';
+    format: number;
+    children: ParsedSegment[];
+} | {
+    type: 'link';
+    fields: Record<string, unknown>;
+    children: ParsedSegment[];
+};
+export declare function encodeLinkData(fields: Record<string, unknown>): string;
+export declare function decodeLinkData(encoded: string): Record<string, unknown>;
+export declare function wrapFormat(text: string, format: number): string;
+export declare function wrapLink(text: string, linkFields: Record<string, unknown>): string;
+/**
+ * Parses a placeholder-tagged string into a tree of `ParsedSegment` nodes.
+ * Handles arbitrary nesting (e.g. a link containing format spans).
+ */
+export declare function parsePlaceholders(input: string): ParsedSegment[];

package/dist/lexical/placeholders.js

@@ -0,0 +1,117 @@
+// ---------------------------------------------------------------------------
+// Encoding helpers
+// ---------------------------------------------------------------------------
+export function encodeLinkData(fields) {
+    return Buffer.from(JSON.stringify(fields)).toString('base64url');
+}
+export function decodeLinkData(encoded) {
+    return JSON.parse(Buffer.from(encoded, 'base64url').toString());
+}
+// ---------------------------------------------------------------------------
+// Wrap helpers — produce placeholder-tagged strings
+// ---------------------------------------------------------------------------
+export function wrapFormat(text, format) {
+    return `<ph id="f:${format}">${text}</ph>`;
+}
+export function wrapLink(text, linkFields) {
+    return `<ph id="l:${encodeLinkData(linkFields)}">${text}</ph>`;
+}
+// ---------------------------------------------------------------------------
+// Recursive placeholder parser
+// ---------------------------------------------------------------------------
+const PH_OPEN = /<ph id="(f|l):([^"]+)">/;
+const PH_CLOSE = '</ph>';
+/**
+ * Parses a placeholder-tagged string into a tree of `ParsedSegment` nodes.
+ * Handles arbitrary nesting (e.g. a link containing format spans).
+ */ export function parsePlaceholders(input) {
+    const segments = [];
+    let cursor = 0;
+    while(cursor < input.length){
+        // Check for closing tag first — signals the end of a recursive call
+        if (input.startsWith(PH_CLOSE, cursor)) {
+            break;
+        }
+        // Try to match an opening tag at the current position
+        const remaining = input.slice(cursor);
+        const openMatch = PH_OPEN.exec(remaining);
+        if (!openMatch || openMatch.index !== 0) {
+            // Consume text up to the next opening tag or closing tag or end
+            const nextOpen = remaining.search(PH_OPEN);
+            const nextClose = remaining.indexOf(PH_CLOSE);
+            let textEnd;
+            if (nextOpen === -1 && nextClose === -1) {
+                textEnd = remaining.length;
+            } else if (nextOpen === -1) {
+                textEnd = nextClose;
+            } else if (nextClose === -1) {
+                textEnd = nextOpen;
+            } else {
+                textEnd = Math.min(nextOpen, nextClose);
+            }
+            if (textEnd > 0) {
+                segments.push({
+                    type: 'text',
+                    content: remaining.slice(0, textEnd)
+                });
+                cursor += textEnd;
+            }
+            continue;
+        }
+        // We matched an opening tag at position 0
+        const [fullMatch, kind, data] = openMatch;
+        cursor += fullMatch.length;
+        // Recursively parse children until we hit the matching </ph>
+        const childResult = parsePlaceholders(input.slice(cursor));
+        const childrenConsumed = measureConsumed(input, cursor, childResult);
+        cursor += childrenConsumed;
+        // Consume the closing </ph>
+        if (input.startsWith(PH_CLOSE, cursor)) {
+            cursor += PH_CLOSE.length;
+        }
+        if (kind === 'f') {
+            segments.push({
+                type: 'format',
+                format: Number(data),
+                children: childResult
+            });
+        } else {
+            segments.push({
+                type: 'link',
+                fields: decodeLinkData(data),
+                children: childResult
+            });
+        }
+    }
+    return segments;
+}
+/**
+ * Determines how many characters the recursive `parsePlaceholders` call
+ * consumed from the input starting at `offset`.
+ *
+ * We re-serialize the parsed children and match that length, but to avoid
+ * ambiguity we simply scan forward from `offset` until we find the matching
+ * `</ph>` at nesting depth 0.
+ */ function measureConsumed(input, offset, _children) {
+    let depth = 0;
+    let i = offset;
+    while(i < input.length){
+        // Check for closing tag
+        if (input.startsWith(PH_CLOSE, i)) {
+            if (depth === 0) return i - offset;
+            depth--;
+            i += PH_CLOSE.length;
+            continue;
+        }
+        // Check for opening tag (increases nesting depth)
+        const remaining = input.slice(i);
+        const openMatch = PH_OPEN.exec(remaining);
+        if (openMatch && openMatch.index === 0) {
+            depth++;
+            i += openMatch[0].length;
+            continue;
+        }
+        i++;
+    }
+    return i - offset;
+}

package/dist/lexical/serializer.d.ts

@@ -0,0 +1,21 @@
+import type { LexicalNodeRegistration } from '../types.js';
+import type { LexicalNode, LexicalRoot, SerializedUnit } from './types.js';
+/**
+ * Walks an embedded Payload block (`type: 'block'` Lexical node, surfaced
+ * by `BlocksFeature`) in a deterministic order, emitting translation
+ * units for strings and recursing into nested Lexical roots / arrays /
+ * objects. Walk order MUST match `applyTranslatedBlockData` in the
+ * deserializer so blockId sequence stays in sync between serialize and
+ * deserialize passes.
+ *
+ * No full schema awareness yet — the BlocksFeature config isn't
+ * reachable from the extractor at runtime. As a defensive heuristic the
+ * walker skips strings that look like select-option values (short,
+ * lowercase identifiers like `info`, `warning`, `oneThird`) so the LLM
+ * doesn't translate them into invalid values that Payload's locale
+ * write validator would reject. The top-level blocks-field path
+ * (handled by `extractBlockFields` in `lib/content-extractor.ts`) uses
+ * full schema-aware gating.
+ */
+export declare function serializeBlockData(data: Record<string, unknown>, units: SerializedUnit[], nextBlockId: () => string, innerWalkNodes: (nodes: LexicalNode[]) => void): void;
+export declare function serializeLexicalTree(root: LexicalRoot, registeredNodes?: LexicalNodeRegistration[]): SerializedUnit[];