@purposeinplay/payload-ai-translate 0.1.0

package/dist/lib/content-extractor.js

@@ -0,0 +1,410 @@
+import { serializeLexicalTree } from '../lexical/serializer.js';
+import { isExcluded } from './exclude-fields.js';
+/**
+ * Field types whose string values are translatable when found inside a
+ * `blocks` field. Mirror of the leaf-type set in `field-resolver.ts` —
+ * used by the schema-aware path in `extractBlockFields` to skip select /
+ * radio / checkbox / number / date / color values that would otherwise
+ * be heuristically translated and reject Payload's locale-write
+ * validation downstream.
+ */ const BLOCK_TRANSLATABLE_LEAF_TYPES = new Set([
+    'text',
+    'textarea',
+    'richText',
+    'json'
+]);
+/**
+ * Build a `blockType → Block` map from a Payload collection / global's
+ * raw `fields` array. Walks `type: 'blocks'` fields anywhere in the tree
+ * (including under tabs, groups, arrays) and gathers their registered
+ * `blocks: Block[]` configurations.
+ *
+ * The result lets the extractor gate which block-internal keys are
+ * translatable based on the SCHEMA rather than the heuristic
+ * "every-string-is-text" walk that produces false positives for select
+ * values, color codes, etc. (the BUG-04 family).
+ */ export function collectBlocksConfig(fields) {
+    const out = new Map();
+    walkFieldsForBlocks(fields, out);
+    return out;
+}
+function walkFieldsForBlocks(fields, out) {
+    for (const raw of fields){
+        const f = raw;
+        const type = typeof f.type === 'string' ? f.type : undefined;
+        if (type === 'blocks' && Array.isArray(f.blocks)) {
+            for (const block of f.blocks){
+                const slug = block.slug;
+                if (slug && !out.has(slug)) out.set(slug, block);
+                if (Array.isArray(block.fields)) {
+                    walkFieldsForBlocks(block.fields, out);
+                }
+            }
+            continue;
+        }
+        if ((type === 'group' || type === 'array' || type === 'row' || type === 'collapsible') && Array.isArray(f.fields)) {
+            walkFieldsForBlocks(f.fields, out);
+            continue;
+        }
+        if (type === 'tabs' && Array.isArray(f.tabs)) {
+            for (const tab of f.tabs){
+                if (Array.isArray(tab.fields)) {
+                    walkFieldsForBlocks(tab.fields, out);
+                }
+            }
+        }
+    }
+}
+/**
+ * Returns a `keyName → declared field type` map for a Block. Recurses
+ * into nested group/array sub-fields so paths like `link.url` resolve.
+ */ function buildBlockFieldTypeMap(block) {
+    const map = new Map();
+    walkBlockFieldsForTypeMap(block.fields ?? [], '', map);
+    return map;
+}
+function walkBlockFieldsForTypeMap(fields, prefix, map) {
+    for (const raw of fields){
+        const f = raw;
+        const type = typeof f.type === 'string' ? f.type : undefined;
+        const name = typeof f.name === 'string' ? f.name : undefined;
+        if (type === 'row' || type === 'collapsible') {
+            if (Array.isArray(f.fields)) {
+                walkBlockFieldsForTypeMap(f.fields, prefix, map);
+            }
+            continue;
+        }
+        if (type === 'tabs' && Array.isArray(f.tabs)) {
+            for (const tab of f.tabs){
+                const tabName = typeof tab.name === 'string' ? tab.name : '';
+                const tabPath = tabName ? prefix ? `${prefix}.${tabName}` : tabName : prefix;
+                if (Array.isArray(tab.fields)) {
+                    walkBlockFieldsForTypeMap(tab.fields, tabPath, map);
+                }
+            }
+            continue;
+        }
+        if (!name || !type) continue;
+        const path = prefix ? `${prefix}.${name}` : name;
+        map.set(path, type);
+        if ((type === 'group' || type === 'array') && Array.isArray(f.fields)) {
+            walkBlockFieldsForTypeMap(f.fields, path, map);
+        }
+    }
+}
+const blockTypeMapCache = new WeakMap();
+function getCachedBlockTypeMap(block) {
+    let map = blockTypeMapCache.get(block);
+    if (!map) {
+        map = buildBlockFieldTypeMap(block);
+        blockTypeMapCache.set(block, map);
+    }
+    return map;
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+export function extractTranslationUnits(doc, fields, excludePatterns, blocksConfig) {
+    const units = [];
+    for (const field of fields){
+        if (isExcluded(field.path, excludePatterns)) continue;
+        const value = getValueAtPath(doc, field.path);
+        if (value === undefined || value === null) continue;
+        switch(field.type){
+            case 'text':
+            case 'textarea':
+                {
+                    if (typeof value === 'string' && value.trim().length > 0) {
+                        units.push({
+                            id: `${field.path}::0`,
+                            fieldPath: field.path,
+                            text: value,
+                            kind: 'plain'
+                        });
+                    }
+                    break;
+                }
+            case 'richText':
+                {
+                    if (isLexicalRoot(value)) {
+                        const serialized = serializeLexicalTree(value);
+                        for (const unit of serialized){
+                            units.push({
+                                id: `${field.path}::${unit.blockId}`,
+                                fieldPath: field.path,
+                                text: unit.text,
+                                kind: 'block'
+                            });
+                        }
+                    }
+                    break;
+                }
+            case 'json':
+                {
+                    if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+                        extractJsonUnits(value, field.path, excludePatterns, units);
+                    }
+                    break;
+                }
+            case 'group':
+                {
+                    if (typeof value === 'object' && !Array.isArray(value)) {
+                        extractGroupUnits(value, field.path, fields, excludePatterns, units);
+                    }
+                    break;
+                }
+            case 'array':
+                {
+                    if (Array.isArray(value)) {
+                        extractArrayUnits(value, field.path, fields, excludePatterns, units, blocksConfig);
+                    }
+                    break;
+                }
+            case 'blocks':
+                {
+                    if (Array.isArray(value)) {
+                        extractBlocksUnits(value, field.path, excludePatterns, units, blocksConfig);
+                    }
+                    break;
+                }
+        }
+    }
+    return units;
+}
+// ---------------------------------------------------------------------------
+// JSON extractor
+// ---------------------------------------------------------------------------
+function extractJsonUnits(obj, basePath, excludePatterns, units) {
+    for (const [key, value] of Object.entries(obj)){
+        const fieldPath = `${basePath}.${key}`;
+        if (isExcluded(fieldPath, excludePatterns)) continue;
+        if (typeof value === 'string' && value.trim().length > 0) {
+            units.push({
+                id: `${fieldPath}::0`,
+                fieldPath,
+                text: value,
+                kind: 'plain'
+            });
+        } else if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+            // Recurse into nested objects
+            extractJsonUnits(value, fieldPath, excludePatterns, units);
+        }
+    // Skip arrays, numbers, booleans, nulls — not translatable
+    }
+}
+// ---------------------------------------------------------------------------
+// Container extractors
+// ---------------------------------------------------------------------------
+function extractGroupUnits(groupValue, groupPath, allFields, excludePatterns, units) {
+    // Find child leaf fields that are under this group's path
+    const childLeaves = allFields.filter((f)=>f.path.startsWith(`${groupPath}.`) && (f.type === 'text' || f.type === 'textarea' || f.type === 'richText'));
+    for (const leaf of childLeaves){
+        if (isExcluded(leaf.path, excludePatterns)) continue;
+        // Resolve relative to the group value
+        const relativePath = leaf.path.slice(groupPath.length + 1);
+        const value = getValueAtPath(groupValue, relativePath);
+        if (value === undefined || value === null) continue;
+        extractLeafValue(value, leaf, units);
+    }
+}
+function extractArrayUnits(items, arrayPath, allFields, excludePatterns, units, blocksConfig) {
+    // Direct text leaves under this array — only those NOT reached through
+    // a deeper array/blocks container. Leaves that traverse another array
+    // are handled by recursing into that array below.
+    const childLeaves = allFields.filter((f)=>f.path.startsWith(`${arrayPath}.`) && (f.type === 'text' || f.type === 'textarea' || f.type === 'richText') && !pathTraversesNestedArray(f.path, arrayPath, allFields));
+    // Direct nested arrays/blocks under this array (not under another nested one)
+    const nestedContainers = allFields.filter((f)=>f.path.startsWith(`${arrayPath}.`) && (f.type === 'array' || f.type === 'blocks') && !pathTraversesNestedArray(f.path, arrayPath, allFields));
+    for(let i = 0; i < items.length; i++){
+        const item = items[i];
+        if (!item || typeof item !== 'object') continue;
+        for (const leaf of childLeaves){
+            const relativePath = leaf.path.slice(arrayPath.length + 1);
+            const indexedPath = `${arrayPath}.${i}.${relativePath}`;
+            if (isExcluded(indexedPath, excludePatterns)) continue;
+            const value = getValueAtPath(item, relativePath);
+            if (value === undefined || value === null) continue;
+            extractLeafValueWithPath(value, leaf.type, indexedPath, units);
+        }
+        for (const container of nestedContainers){
+            const relativePath = container.path.slice(arrayPath.length + 1);
+            const indexedContainerPath = `${arrayPath}.${i}.${relativePath}`;
+            const nestedValue = getValueAtPath(item, relativePath);
+            if (!Array.isArray(nestedValue)) continue;
+            const mappedFields = remapFieldsUnderPath(allFields, container.path, indexedContainerPath);
+            if (container.type === 'array') {
+                extractArrayUnits(nestedValue, indexedContainerPath, mappedFields, excludePatterns, units, blocksConfig);
+            } else {
+                extractBlocksUnits(nestedValue, indexedContainerPath, excludePatterns, units, blocksConfig);
+            }
+        }
+    }
+}
+function pathTraversesNestedArray(path, containerPath, allFields) {
+    for (const f of allFields){
+        if (f.type !== 'array' && f.type !== 'blocks') continue;
+        if (f.path === containerPath) continue;
+        if (!f.path.startsWith(`${containerPath}.`)) continue;
+        if (path.startsWith(`${f.path}.`)) return true;
+    }
+    return false;
+}
+function remapFieldsUnderPath(allFields, fromPath, toPath) {
+    return allFields.filter((f)=>f.path === fromPath || f.path.startsWith(`${fromPath}.`)).map((f)=>({
+            ...f,
+            path: toPath + f.path.slice(fromPath.length)
+        }));
+}
+function extractBlocksUnits(blocks, blocksPath, excludePatterns, units, blocksConfig) {
+    for(let i = 0; i < blocks.length; i++){
+        const block = blocks[i];
+        if (!block || typeof block !== 'object') continue;
+        const blockType = block.blockType;
+        const prefix = `${blocksPath}.${i}`;
+        extractBlockFields(block, prefix, blockType, excludePatterns, units, blocksConfig);
+    }
+}
+/**
+ * Walk a block's data. When `blocksConfig` has an entry for the current
+ * `blockType`, this becomes schema-aware: only keys whose declared type
+ * is text/textarea/richText/json get emitted as translation units.
+ * Select / radio / number / date / color / etc. are silently skipped,
+ * which fixes BUG-04 (non-text strings translated as text → locale-write
+ * validator rejects). Without a config entry the walker falls back to
+ * the previous heuristic so third-party blocks the plugin doesn't know
+ * about still translate.
+ */ function extractBlockFields(obj, pathPrefix, blockType, excludePatterns, units, blocksConfig, fieldTypeMap, fieldTypeMapPrefix = '') {
+    // Resolve the typeMap for the current block (if known). Falls back to
+    // an inherited map when recursing into nested groups inside the same
+    // block — sub-paths are still gated by the same schema.
+    const block = blockType && blocksConfig ? blocksConfig.get(blockType) : undefined;
+    const typeMap = block ? getCachedBlockTypeMap(block) : fieldTypeMap ?? null;
+    for (const [key, value] of Object.entries(obj)){
+        // Skip Payload internal block metadata
+        if (key === 'id' || key === 'blockType' || key === 'blockName') continue;
+        const fieldPath = `${pathPrefix}.${key}`;
+        if (isExcluded(fieldPath, excludePatterns)) continue;
+        // Schema-aware gating: only allow keys whose declared type is a
+        // translatable leaf, group, array, or blocks. Anything else (select,
+        // radio, number, date, color, upload, relationship, point, code) is
+        // skipped silently — non-translatable, but they're stored as plain
+        // strings/numbers that the heuristic walker used to translate.
+        const declared = typeMap ? typeMap.get(fieldTypeMapPrefix ? `${fieldTypeMapPrefix}.${key}` : key) : undefined;
+        if (typeMap && declared && !isTranslatableOrContainerType(declared)) continue;
+        if (typeof value === 'string' && value.trim().length > 0) {
+            // When the schema declares this key as a non-text leaf (e.g. an
+            // arbitrary `code` field that happens to be string-typed), skip.
+            // When the schema declares it as a leaf-text type, emit. When the
+            // schema doesn't know about this key (declared=undefined), only
+            // emit if there's no typeMap (no schema configured at all) — with
+            // a typeMap present, unknown keys are out-of-schema data that
+            // shouldn't be translated.
+            if (typeMap) {
+                if (!declared) continue;
+                if (!BLOCK_TRANSLATABLE_LEAF_TYPES.has(declared)) continue;
+            }
+            units.push({
+                id: `${fieldPath}::0`,
+                fieldPath,
+                text: value,
+                kind: 'plain'
+            });
+        } else if (isLexicalRoot(value)) {
+            if (typeMap && declared && declared !== 'richText') continue;
+            const serialized = serializeLexicalTree(value);
+            for (const unit of serialized){
+                units.push({
+                    id: `${fieldPath}::${unit.blockId}`,
+                    fieldPath,
+                    text: unit.text,
+                    kind: 'block'
+                });
+            }
+        } else if (Array.isArray(value)) {
+            // Nested array of blocks / items / strings.
+            // Object items recurse; primitive strings are extracted at indexed paths
+            // so JSON-typed fields with arrays of strings (e.g. `tags: ["a", "b"]`)
+            // are translated rather than passed through verbatim.
+            for(let i = 0; i < value.length; i++){
+                const item = value[i];
+                if (item && typeof item === 'object' && !Array.isArray(item)) {
+                    const childBlockType = item.blockType;
+                    extractBlockFields(item, `${fieldPath}.${i}`, childBlockType, excludePatterns, units, blocksConfig, // When recursing into a non-block array (e.g. `link.options[]`)
+                    // we want to keep walking with the same typeMap if it covers
+                    // sub-paths, otherwise fall back to heuristic.
+                    childBlockType ? undefined : typeMap ?? undefined, childBlockType ? '' : `${fieldTypeMapPrefix || ''}${fieldTypeMapPrefix ? '.' : ''}${key}`);
+                } else if (typeof item === 'string' && item.trim().length > 0) {
+                    units.push({
+                        id: `${fieldPath}.${i}::0`,
+                        fieldPath: `${fieldPath}.${i}`,
+                        text: item,
+                        kind: 'plain'
+                    });
+                }
+            }
+        } else if (value && typeof value === 'object' && !Array.isArray(value)) {
+            // Nested group within the block — keep the same typeMap so paths
+            // like `link.url`, `link.type` are gated by the block's schema.
+            extractBlockFields(value, fieldPath, undefined, excludePatterns, units, blocksConfig, typeMap ?? undefined, fieldTypeMapPrefix ? `${fieldTypeMapPrefix}.${key}` : key);
+        }
+    }
+}
+function isTranslatableOrContainerType(declared) {
+    return BLOCK_TRANSLATABLE_LEAF_TYPES.has(declared) || declared === 'group' || declared === 'array' || declared === 'blocks';
+}
+// ---------------------------------------------------------------------------
+// Leaf helpers
+// ---------------------------------------------------------------------------
+function extractLeafValue(value, field, units) {
+    extractLeafValueWithPath(value, field.type, field.path, units);
+}
+function extractLeafValueWithPath(value, fieldType, fieldPath, units) {
+    if (fieldType === 'text' || fieldType === 'textarea') {
+        if (typeof value === 'string' && value.trim().length > 0) {
+            units.push({
+                id: `${fieldPath}::0`,
+                fieldPath,
+                text: value,
+                kind: 'plain'
+            });
+        }
+    } else if (fieldType === 'richText') {
+        if (isLexicalRoot(value)) {
+            const serialized = serializeLexicalTree(value);
+            for (const unit of serialized){
+                units.push({
+                    id: `${fieldPath}::${unit.blockId}`,
+                    fieldPath,
+                    text: unit.text,
+                    kind: 'block'
+                });
+            }
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Path utilities
+// ---------------------------------------------------------------------------
+export function getValueAtPath(obj, path) {
+    const segments = path.split('.');
+    let current = obj;
+    for (const segment of segments){
+        if (current === null || current === undefined) return undefined;
+        if (typeof current !== 'object') return undefined;
+        if (Array.isArray(current)) {
+            const index = Number(segment);
+            if (Number.isNaN(index)) return undefined;
+            current = current[index];
+        } else {
+            current = current[segment];
+        }
+    }
+    return current;
+}
+// ---------------------------------------------------------------------------
+// Type guards
+// ---------------------------------------------------------------------------
+function isLexicalRoot(value) {
+    if (value === null || typeof value !== 'object') return false;
+    const obj = value;
+    return 'root' in obj && obj.root !== null && typeof obj.root === 'object';
+}

package/dist/lib/content-hash.d.ts

@@ -0,0 +1 @@
+export declare function hashFieldContent(value: unknown): string;

package/dist/lib/content-hash.js

@@ -0,0 +1,19 @@
+import { createHash } from 'node:crypto';
+function sortKeys(value) {
+    if (value == null || typeof value !== 'object') {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        return value.map(sortKeys);
+    }
+    const sorted = {};
+    for (const key of Object.keys(value).sort()){
+        sorted[key] = sortKeys(value[key]);
+    }
+    return sorted;
+}
+export function hashFieldContent(value) {
+    const normalized = sortKeys(value);
+    const serialized = JSON.stringify(normalized) ?? 'undefined';
+    return createHash('sha256').update(serialized).digest('hex');
+}

package/dist/lib/content-patcher.d.ts

@@ -0,0 +1,15 @@
+import type { TranslatableField } from '../types.js';
+/**
+ * @param base Merge base — target-locale-first state that will be mutated
+ *   (via structured clone) and returned with translated leaves written in.
+ *   This was previously misleadingly called `sourceDoc`; it's the BASE that
+ *   accumulates translated text on top of prior target-locale state.
+ * @param translatedUnits Map of unitId → translated text.
+ * @param fields Translatable field descriptors.
+ * @param sourceDoc The TRUE source-locale doc. Read-only. Used to recover
+ *   structural skeletons (e.g. Lexical trees) when the base's target-locale
+ *   row is empty or otherwise missing the source shape — without this the
+ *   deserializer walks an empty/stale skeleton and discards source structure.
+ */
+export declare function patchTranslatedContent(base: Record<string, unknown>, translatedUnits: Map<string, string>, fields: TranslatableField[], sourceDoc: Record<string, unknown>): Record<string, unknown>;
+export declare function setValueAtPath(obj: Record<string, unknown>, path: string, value: unknown): void;