@focus-reactive/payload-plugin-translator 0.5.0 → 0.6.0

package/dist/server/modules/translation-pipeline/stages/data-reconciler/DataReconciler.js

@@ -1,12 +1,76 @@
-import { fieldAffectsData, fieldIsArrayType, fieldIsBlockType, fieldIsGroupType, tabHasName } from 'payload/shared';
-import { hasFields, isBlockItem, isTabsField, isEmpty, isObject } from '../../../../shared';
+import { isEmpty, isObject } from "../../../../shared";
+import { matchElementById, resolveBlockFields, walkFields } from "../../../../shared/field-traversal";
+const asObject = (value)=>isObject(value) ? value : {};
 /**
- * Deep merges source and target data with target priority.
- * Creates full document shape needed for Payload validation.
+ * Reconcile walker: produces the full document shape from source + target, with target
+ * priority (source fills empty target slots). Iteration is driven by `source`; a field with
+ * no source value is dropped, `id` is stripped from array/block elements (Postgres rejects it
+ * on update), `blockType` is preserved, and non-object array items / unknown blocks pass
+ * through unchanged.
  *
- * Logic:
- * - If targetValue exists and is not empty → use targetValue
- * - Otherwise → use sourceValue
+ * Array/block elements are paired with their target counterpart by `id`, not by position (see
+ * {@link matchElementById}); output order always follows `source`.
+ */ const reconcileWalker = {
+    enterObject (field, cursor) {
+        const sourceValue = cursor.source[field.name];
+        if (!isObject(sourceValue)) return "skip"; // undefined / non-object source → drop the field
+        return {
+            source: sourceValue,
+            target: asObject(cursor.target[field.name])
+        };
+    },
+    enterList (field, cursor) {
+        const sourceValue = cursor.source[field.name];
+        if (!Array.isArray(sourceValue)) return "skip";
+        const targetValue = cursor.target[field.name];
+        const targetArr = Array.isArray(targetValue) ? targetValue : [];
+        const isBlocks = field.type === "blocks";
+        const children = [];
+        sourceValue.forEach((item, index)=>{
+            if (!isObject(item)) return; // non-object element → passthrough (rebuilt in combine)
+            const fields = isBlocks ? resolveBlockFields(field, item) : field.fields;
+            if (!fields) return; // unknown blockType → passthrough
+            // Pair by id, not position: target[index] may be a different element under per-locale ordering.
+            children.push({
+                cursor: {
+                    source: item,
+                    target: matchElementById(targetArr, item, isBlocks)
+                },
+                fields,
+                key: index
+            });
+        });
+        return children;
+    },
+    leaf (field, cursor) {
+        const sourceValue = cursor.source[field.name];
+        if (sourceValue === undefined) return undefined; // no source value → field dropped
+        const targetValue = cursor.target[field.name];
+        return isEmpty(targetValue) ? sourceValue : targetValue; // target priority, fallback to source
+    },
+    combine (container, children, cursor) {
+        if (container.kind === "list") {
+            // Rebuild the full array in source order: reconciled objects keyed by source position, raw
+            // source items (non-object / unknown block) otherwise.
+            const sourceArr = cursor.source[container.key] ?? [];
+            const byIndex = new Map(children.map((child)=>[
+                    child.key,
+                    child.out
+                ]));
+            return sourceArr.map((item, index)=>byIndex.has(index) ? byIndex.get(index) : item);
+        }
+        const result = {};
+        for (const child of children)result[child.key] = child.out;
+        // Block elements keep their blockType; id is intentionally stripped (Postgres rejects it on update).
+        if (container.kind === "element" && container.field.type === "blocks") {
+            result.blockType = cursor.source.blockType;
+        }
+        return result;
+    }
+};
+/**
+ * Deep-merges source and target data with target priority, producing the full document shape
+ * Payload validation needs. Built on the shared {@link walkFields} engine.
  *
  * Stage 1 of the translation pipeline.
  */ export class DataReconciler {
@@ -16,81 +80,16 @@ import { hasFields, isBlockItem, isTabsField, isEmpty, isObject } from '../../..
     }
     /**
    * Reconciles source and target data into a complete document shape.
-   * The result contains all fields needed for Payload validation.
    *
    * @param sourceData - Source locale document data
    * @param targetData - Target locale document data (may be empty/partial)
    * @returns Complete document shape with reconciled field values
    */ reconcile(sourceData, targetData) {
-        return this.reconcileFields(this.schema, sourceData, targetData ?? {});
-    }
-    reconcileFields(fields, source, target) {
-        const result = {};
-        for (const field of fields){
-            if (isTabsField(field)) {
-                for (const tab of field.tabs){
-                    if (hasFields(tab)) {
-                        if (tabHasName(tab)) {
-                            const tabSource = source[tab.name];
-                            const tabTarget = target[tab.name];
-                            if (isObject(tabSource)) {
-                                result[tab.name] = this.reconcileFields(tab.fields, tabSource, isObject(tabTarget) ? tabTarget : {});
-                            }
-                        } else {
-                            Object.assign(result, this.reconcileFields(tab.fields, source, target));
-                        }
-                    }
-                }
-                continue;
-            }
-            if (!fieldAffectsData(field)) {
-                if (hasFields(field)) Object.assign(result, this.reconcileFields(field.fields, source, target));
-                continue;
-            }
-            const sourceValue = source[field.name];
-            const targetValue = target[field.name];
-            // Skip undefined source values
-            if (sourceValue === undefined) continue;
-            // Group - recursively reconcile
-            if (fieldIsGroupType(field) && isObject(sourceValue)) {
-                const targetGroup = isObject(targetValue) ? targetValue : {};
-                result[field.name] = this.reconcileFields(field.fields, sourceValue, targetGroup);
-                continue;
-            }
-            // Array - recursively reconcile each item (without id - Postgres rejects it)
-            if (fieldIsArrayType(field) && Array.isArray(sourceValue)) {
-                const targetArray = Array.isArray(targetValue) ? targetValue : [];
-                result[field.name] = sourceValue.map((sourceItem, index)=>{
-                    if (isObject(sourceItem)) {
-                        const targetItem = isObject(targetArray[index]) ? targetArray[index] : {};
-                        return this.reconcileFields(field.fields, sourceItem, targetItem);
-                    }
-                    return sourceItem;
-                });
-                continue;
-            }
-            // Blocks - recursively reconcile each block (without id - Postgres rejects it)
-            if (fieldIsBlockType(field) && Array.isArray(sourceValue)) {
-                const targetArray = Array.isArray(targetValue) ? targetValue : [];
-                result[field.name] = sourceValue.map((sourceItem, index)=>{
-                    if (isBlockItem(sourceItem)) {
-                        const block = field.blocks.find((b)=>b.slug === sourceItem.blockType);
-                        if (block) {
-                            const targetItem = isObject(targetArray[index]) ? targetArray[index] : {};
-                            return {
-                                ...this.reconcileFields(block.fields, sourceItem, targetItem),
-                                blockType: sourceItem.blockType
-                            };
-                        }
-                    }
-                    return sourceItem;
-                });
-                continue;
-            }
-            // Deep merge: target priority, fallback to source
-            result[field.name] = isEmpty(targetValue) ? sourceValue : targetValue;
-        }
-        return result;
+        const root = {
+            source: sourceData,
+            target: targetData ?? {}
+        };
+        return walkFields(this.schema, root, reconcileWalker) ?? {};
     }
 }
 

package/dist/server/modules/translation-pipeline/stages/data-reconciler/DataReconciler.stage.d.ts

@@ -1,4 +1,4 @@
-import type { PipelineContext, PipelineStage } from '../../types';
+import type { PipelineContext, PipelineStage } from "../../types";
 /**
  * Deep merges source and target data with target priority.
  * Stage 1 of the translation pipeline.

package/dist/server/modules/translation-pipeline/stages/data-reconciler/DataReconciler.stage.js

@@ -1,4 +1,4 @@
-import { DataReconciler } from './DataReconciler';
+import { DataReconciler } from "./DataReconciler";
 /**
  * Deep merges source and target data with target priority.
  * Stage 1 of the translation pipeline.

package/dist/server/modules/translation-pipeline/stages/field-collector/FieldChunkCollector.d.ts

@@ -1,18 +1,20 @@
-import type { Field } from 'payload';
-import type { FieldChunk } from '../../types';
-import type { TranslationStrategy } from '../../strategies';
+import type { Field } from "payload";
+import type { TranslationStrategy } from "../../strategies";
+import type { FieldChunk } from "../../types";
 /**
- * Collects FieldChunks by traversing schema and data in parallel.
- * Each chunk contains a reference to the parent data object for later mutation.
+ * Collects FieldChunks by walking schema + data with the shared {@link walkFields} engine.
+ * Iteration is driven by `filteredData`; each translatable, localized, non-excluded leaf that
+ * the strategy approves is written with its source value and pushed as a chunk carrying a
+ * mutable reference to its parent object (for later write-back). Collect-only — `combine` is a
+ * no-op; results accumulate in a closure.
  *
- * Applies all filtering logic:
- * - isTranslatableField
- * - isLocalizedField
- * - strategy.shouldTranslate(sourceValue, targetValue)
- * - !isFieldExcludedFromTranslation
+ * Array/block elements pair their `source` by position (`filteredData` is built in source order)
+ * but their `target` by `id` (see {@link matchElementById}) — the target locale's elements may be
+ * independently ordered, so a positional target would feed `strategy.shouldTranslate` the wrong
+ * element's value and skip/re-translate the wrong leaf.
  *
- * IMPORTANT: Expects ORIGINAL collection schemas (before Payload sanitization).
- * Original schemas preserve `localized: true` on nested fields.
+ * IMPORTANT: Expects ORIGINAL collection schemas (before Payload sanitization). Original
+ * schemas preserve `localized: true` on nested fields.
  */
 export declare class FieldChunkCollector {
     private readonly schema;
@@ -20,15 +22,7 @@ export declare class FieldChunkCollector {
     private readonly sourceData;
     private readonly targetData;
     private readonly strategy;
-    private chunks;
     constructor(schema: Field[], filteredData: Record<string, unknown>, sourceData: Record<string, unknown>, targetData: Record<string, unknown>, strategy: TranslationStrategy);
-    /**
-     * Collects translatable field chunks that need translation.
-     */
+    /** Collects translatable field chunks that need translation. */
     collect(): FieldChunk[];
-    /**
-     * Traverses fields recursively, collecting translatable fields that need translation.
-     * Uses strategy.shouldTranslate() to determine if field needs translation.
-     */
-    private traverseFields;
 }

package/dist/server/modules/translation-pipeline/stages/field-collector/FieldChunkCollector.js

@@ -1,128 +1,116 @@
-import { fieldAffectsData, fieldIsArrayType, fieldIsBlockType, fieldIsGroupType, tabHasName } from 'payload/shared';
-import { hasFields, isBlockItem, isLocalizedField, isObject, isTabsField, isTranslatableField, isFieldExcludedFromTranslation } from '../../../../shared';
+import { isFieldExcludedFromTranslation, isLocalizedField, isObject, isTranslatableField } from "../../../../shared";
+import { matchElementById, resolveBlockFields, walkFields } from "../../../../shared/field-traversal";
+const asObject = (value)=>isObject(value) ? value : {};
 /**
- * Collects FieldChunks by traversing schema and data in parallel.
- * Each chunk contains a reference to the parent data object for later mutation.
+ * Collects FieldChunks by walking schema + data with the shared {@link walkFields} engine.
+ * Iteration is driven by `filteredData`; each translatable, localized, non-excluded leaf that
+ * the strategy approves is written with its source value and pushed as a chunk carrying a
+ * mutable reference to its parent object (for later write-back). Collect-only — `combine` is a
+ * no-op; results accumulate in a closure.
  *
- * Applies all filtering logic:
- * - isTranslatableField
- * - isLocalizedField
- * - strategy.shouldTranslate(sourceValue, targetValue)
- * - !isFieldExcludedFromTranslation
+ * Array/block elements pair their `source` by position (`filteredData` is built in source order)
+ * but their `target` by `id` (see {@link matchElementById}) — the target locale's elements may be
+ * independently ordered, so a positional target would feed `strategy.shouldTranslate` the wrong
+ * element's value and skip/re-translate the wrong leaf.
  *
- * IMPORTANT: Expects ORIGINAL collection schemas (before Payload sanitization).
- * Original schemas preserve `localized: true` on nested fields.
+ * IMPORTANT: Expects ORIGINAL collection schemas (before Payload sanitization). Original
+ * schemas preserve `localized: true` on nested fields.
  */ export class FieldChunkCollector {
     schema;
     filteredData;
     sourceData;
     targetData;
     strategy;
-    chunks;
     constructor(schema, filteredData, sourceData, targetData, strategy){
         this.schema = schema;
         this.filteredData = filteredData;
         this.sourceData = sourceData;
         this.targetData = targetData;
         this.strategy = strategy;
-        this.chunks = [];
     }
-    /**
-   * Collects translatable field chunks that need translation.
-   */ collect() {
-        this.chunks = [];
-        this.traverseFields(this.schema, this.filteredData, this.sourceData, this.targetData, []);
-        return this.chunks;
-    }
-    /**
-   * Traverses fields recursively, collecting translatable fields that need translation.
-   * Uses strategy.shouldTranslate() to determine if field needs translation.
-   */ traverseFields(fields, data, source, target, path) {
-        for (const field of fields){
-            if (isTabsField(field)) {
-                for (const tab of field.tabs){
-                    if (hasFields(tab)) {
-                        if (tabHasName(tab)) {
-                            const tabData = data[tab.name];
-                            const tabSource = source[tab.name];
-                            const tabTarget = target[tab.name];
-                            if (isObject(tabData)) {
-                                this.traverseFields(tab.fields, tabData, isObject(tabSource) ? tabSource : {}, isObject(tabTarget) ? tabTarget : {}, [
-                                    ...path,
-                                    tab.name
-                                ]);
-                            }
-                        } else {
-                            this.traverseFields(tab.fields, data, source, target, path);
-                        }
-                    }
-                }
-                continue;
-            }
-            if (!fieldAffectsData(field)) {
-                if (hasFields(field)) this.traverseFields(field.fields, data, source, target, path);
-                continue;
-            }
-            const value = data[field.name];
-            const sourceValue = source[field.name];
-            const targetValue = target[field.name];
-            if (value === undefined || value === null) continue;
-            const currentPath = [
-                ...path,
-                field.name
-            ];
-            if (fieldIsGroupType(field) && isObject(value)) {
-                this.traverseFields(field.fields, value, isObject(sourceValue) ? sourceValue : {}, isObject(targetValue) ? targetValue : {}, currentPath);
-                continue;
-            }
-            if (fieldIsArrayType(field) && Array.isArray(value)) {
-                const sourceArray = Array.isArray(sourceValue) ? sourceValue : [];
-                const targetArray = Array.isArray(targetValue) ? targetValue : [];
+    /** Collects translatable field chunks that need translation. */ collect() {
+        const chunks = [];
+        const { strategy } = this;
+        const walker = {
+            enterObject (field, cursor) {
+                const value = cursor.data[field.name];
+                if (!isObject(value)) return "skip";
+                return {
+                    data: value,
+                    source: asObject(cursor.source[field.name]),
+                    target: asObject(cursor.target[field.name]),
+                    path: [
+                        ...cursor.path,
+                        field.name
+                    ]
+                };
+            },
+            enterList (field, cursor) {
+                const value = cursor.data[field.name];
+                if (!Array.isArray(value)) return "skip";
+                const sourceValue = cursor.source[field.name];
+                const targetValue = cursor.target[field.name];
+                const sourceArr = Array.isArray(sourceValue) ? sourceValue : [];
+                const targetArr = Array.isArray(targetValue) ? targetValue : [];
+                const isBlocks = field.type === "blocks";
+                const children = [];
                 value.forEach((item, index)=>{
-                    if (isObject(item)) {
-                        const sourceItem = isObject(sourceArray[index]) ? sourceArray[index] : {};
-                        const targetItem = isObject(targetArray[index]) ? targetArray[index] : {};
-                        this.traverseFields(field.fields, item, sourceItem, targetItem, [
-                            ...currentPath,
-                            String(index)
-                        ]);
-                    }
-                });
-                continue;
-            }
-            if (fieldIsBlockType(field) && Array.isArray(value)) {
-                const sourceArray = Array.isArray(sourceValue) ? sourceValue : [];
-                const targetArray = Array.isArray(targetValue) ? targetValue : [];
-                value.forEach((item, index)=>{
-                    if (isBlockItem(item)) {
-                        const block = field.blocks.find((b)=>b.slug === item.blockType);
-                        if (block) {
-                            const sourceItem = isObject(sourceArray[index]) ? sourceArray[index] : {};
-                            const targetItem = isObject(targetArray[index]) ? targetArray[index] : {};
-                            this.traverseFields(block.fields, item, sourceItem, targetItem, [
-                                ...currentPath,
+                    if (!isObject(item)) return;
+                    const fields = isBlocks ? resolveBlockFields(field, item) : field.fields;
+                    if (!fields) return; // unknown blockType → skip element
+                    // source pairs by index (filteredData shares source order); target by the source
+                    // element's id, since the target locale may be reordered independently.
+                    const sourceItem = asObject(sourceArr[index]);
+                    children.push({
+                        cursor: {
+                            data: item,
+                            source: sourceItem,
+                            target: matchElementById(targetArr, sourceItem, isBlocks),
+                            path: [
+                                ...cursor.path,
+                                field.name,
                                 String(index)
-                            ]);
-                        }
-                    }
-                });
-                continue;
-            }
-            // Collect if: translatable, localized, not excluded, and strategy says to translate
-            if (isTranslatableField(field) && isLocalizedField(field) && !isFieldExcludedFromTranslation(field) && this.strategy.shouldTranslate({
-                sourceValue,
-                targetValue
-            })) {
-                // Write sourceValue to filteredData — this is what will be translated
-                data[field.name] = sourceValue;
-                this.chunks.push({
-                    schema: field,
-                    dataRef: data,
-                    key: field.name,
-                    path: currentPath
+                            ]
+                        },
+                        fields,
+                        key: index
+                    });
                 });
+                return children;
+            },
+            leaf (field, cursor) {
+                const value = cursor.data[field.name];
+                if (value === undefined || value === null) return undefined;
+                const sourceValue = cursor.source[field.name];
+                const targetValue = cursor.target[field.name];
+                if (isTranslatableField(field) && isLocalizedField(field) && !isFieldExcludedFromTranslation(field) && strategy.shouldTranslate({
+                    sourceValue,
+                    targetValue
+                })) {
+                    cursor.data[field.name] = sourceValue; // write source value into filteredData — this is what gets translated
+                    chunks.push({
+                        schema: field,
+                        dataRef: cursor.data,
+                        key: field.name,
+                        path: [
+                            ...cursor.path,
+                            field.name
+                        ]
+                    });
+                }
+                return undefined;
+            },
+            combine () {
+                return undefined; // collect-only — nothing to assemble
             }
-        }
+        };
+        walkFields(this.schema, {
+            data: this.filteredData,
+            source: this.sourceData,
+            target: this.targetData,
+            path: []
+        }, walker);
+        return chunks;
     }
 }
 

package/dist/server/modules/translation-providers/OpenAITranslation.provider.d.ts

@@ -76,6 +76,23 @@ export type OpenAIProviderConfig = {
      * @default false
      */
     dryRun?: boolean | DryRunConfig;
+    /**
+     * Per-request timeout in milliseconds for the OpenAI client. A translation job blocks on this
+     * call, so the OpenAI SDK default (10 minutes) is usually too long. Omit to keep the SDK default.
+     *
+     * @example
+     * timeout: 60_000 // 60s
+     *
+     * @since 0.6.0
+     */
+    timeout?: number;
+    /**
+     * Maximum automatic retries the OpenAI client performs on transient errors (429, 5xx, network).
+     * Omit to keep the SDK default (2). Set `0` to disable retries.
+     *
+     * @since 0.6.0
+     */
+    maxRetries?: number;
 };
 /** @deprecated Use `createOpenAIProvider` function instead */
 export declare class OpenAITranslationProvider implements TranslationProvider {

package/dist/server/modules/translation-providers/OpenAITranslation.provider.js

@@ -4,8 +4,12 @@ import { isObject } from "../../shared";
     openAiClient;
     config;
     constructor(config){
+        // `timeout`/`maxRetries` are passed through to the OpenAI SDK; `undefined` keeps the SDK
+        // defaults (10 min timeout, 2 retries). A blocking translation job rarely wants the full 10 min.
         this.openAiClient = new OpenAI({
-            apiKey: config.apiKey
+            apiKey: config.apiKey,
+            timeout: config.timeout,
+            maxRetries: config.maxRetries
         });
         this.config = config;
     }
@@ -43,7 +47,9 @@ import { isObject } from "../../shared";
                 type: "json_object"
             }
         });
-        const translatedContent = chatCompletion.choices[0].message.content;
+        // Guard `choices[0]`: an empty `choices` array (e.g. content-filtered response) would otherwise
+        // throw a TypeError instead of the intended graceful `null`.
+        const translatedContent = chatCompletion.choices[0]?.message?.content;
         if (!translatedContent) return null;
         try {
             return JSON.parse(translatedContent);

package/dist/server/shared/field-config/types.js

@@ -17,6 +17,6 @@
  * ```
  */ /**
  * Key used to store TranslateKit configuration in field.custom
- */ export const TRANSLATE_KIT_CUSTOM_KEY = 'translateKit';
+ */ export const TRANSLATE_KIT_CUSTOM_KEY = "translateKit";
 
 //# sourceMappingURL=types.js.map

package/dist/server/shared/field-traversal/findFieldByPath.d.ts

@@ -0,0 +1,55 @@
+import type { Field } from "payload";
+import type { LeafField } from "./types";
+/**
+ * Outcome of navigating a field schema by a path of segment names (see {@link findFieldByPath}).
+ *
+ * - `leaf` — the path lands on a data-affecting leaf field (carries it).
+ * - `container` — the path lands on a `group`/`array`/`blocks` field, a single block element, or a
+ *   named tab (a container, not a leaf).
+ * - `inside-blocks` — the path descends THROUGH a `blocks` field that can't be resolved: no
+ *   document data was supplied (so the element's `blockType` is unknown), the data is missing at
+ *   that index, or the `blockType` matches no defined block.
+ * - `localized-list-ancestor` — the path descends THROUGH a `localized` `blocks`/`array` field.
+ *   Such fields are stored independently per locale (different order/content), so an element index
+ *   is not a stable cross-locale identity; a caller translating *by path across locales* should
+ *   refuse rather than resolve positionally. (See the "cross-locale block identity" design.)
+ * - `not-found` — no field matches a segment, or the path continues past a leaf.
+ *
+ * @public
+ */
+export type FieldPathResult = {
+    status: "leaf";
+    field: LeafField;
+} | {
+    status: "container";
+} | {
+    status: "inside-blocks";
+} | {
+    status: "localized-list-ancestor";
+} | {
+    status: "not-found";
+};
+/**
+ * Navigate a field schema by a path of segment NAMES, descending one matching branch at a time
+ * with early-exit (targeted navigation, not an exhaustive walk). Presentational containers
+ * (`row`/`collapsible`/unnamed `group`) and unnamed tabs are transparent — searched in the same
+ * path scope. Built on {@link classifyField} / {@link tabScopes} / {@link resolveBlockFields} so
+ * the structural dispatch lives in one place.
+ *
+ * **Array indices and `blocks`.** Array element configs are shared, so a numeric segment after an
+ * array name selects the data item but not the schema (the schema continues into `array.fields`).
+ * A `blocks` field is polymorphic — which block (and thus which fields) sits at an index lives in
+ * the *data*, not the schema. So to descend through `blocks` the caller must pass the document
+ * `data` and keep the element index in the path: this function reads `data[name][index].blockType`
+ * and resolves the matching block via {@link resolveBlockFields}. Without `data` (or with a
+ * non-indexed path), descending through `blocks` returns `inside-blocks`.
+ *
+ * @param fields - The schema level to search.
+ * @param segments - Remaining path segments to match, head-first. Keep array/block element indices
+ *   in the path when navigating with `data`.
+ * @param data - The document (sub)tree aligned with `fields`, used only to disambiguate `blocks`.
+ *   Omit for schema-only navigation.
+ * @returns A {@link FieldPathResult}.
+ * @public
+ */
+export declare function findFieldByPath(fields: Field[], segments: string[], data?: unknown): FieldPathResult;