@focus-reactive/payload-plugin-translator 0.5.1 → 0.6.1

package/dist/server/modules/translation-levels/fieldLevel.d.ts

@@ -0,0 +1,23 @@
+import type { TranslationLevel } from "./types";
+/**
+ * Field-level translation surface: a synchronous `POST {basePath}/field` endpoint that translates
+ * a single declared field **from a chosen source locale** — it reads the field's value from the
+ * saved document in that locale and translates it into the active locale. No runner, no queue, no
+ * persistence. Unlike `documentLevel` / `collectionLevel`, it contributes no admin component: the
+ * per-field control UI is wired separately at field-declaration time via `withFieldTranslation(field)`.
+ *
+ * Not part of the default `levels`, so it stays strictly opt-in.
+ *
+ * @returns an opaque {@link TranslationLevel} to list in `translatorPlugin({ levels })`
+ * @since 0.6.0
+ * @example
+ * ```ts
+ * translatorPlugin({
+ *   collections: [Posts],
+ *   translationProvider: createOpenAIProvider({ apiKey: process.env.OPENAI_API_KEY }),
+ *   runner: createPayloadJobsRunner(),
+ *   levels: [documentLevel(), fieldLevel()],
+ * });
+ * ```
+ */
+export declare function fieldLevel(): TranslationLevel;

package/dist/server/modules/translation-levels/fieldLevel.js

@@ -0,0 +1,37 @@
+import { createFieldRoute } from "../../features/translate-field";
+/**
+ * Field-level translation surface: a synchronous `POST {basePath}/field` endpoint that translates
+ * a single declared field **from a chosen source locale** — it reads the field's value from the
+ * saved document in that locale and translates it into the active locale. No runner, no queue, no
+ * persistence. Unlike `documentLevel` / `collectionLevel`, it contributes no admin component: the
+ * per-field control UI is wired separately at field-declaration time via `withFieldTranslation(field)`.
+ *
+ * Not part of the default `levels`, so it stays strictly opt-in.
+ *
+ * @returns an opaque {@link TranslationLevel} to list in `translatorPlugin({ levels })`
+ * @since 0.6.0
+ * @example
+ * ```ts
+ * translatorPlugin({
+ *   collections: [Posts],
+ *   translationProvider: createOpenAIProvider({ apiKey: process.env.OPENAI_API_KEY }),
+ *   runner: createPayloadJobsRunner(),
+ *   levels: [documentLevel(), fieldLevel()],
+ * });
+ * ```
+ */ export function fieldLevel() {
+    return {
+        extend (ctx) {
+            ctx.addEndpoints([
+                createFieldRoute({
+                    schemaMap: ctx.schemaMap,
+                    translationProvider: ctx.translationProvider,
+                    access: ctx.access,
+                    basePath: ctx.basePath
+                })
+            ]);
+        }
+    };
+}
+
+//# sourceMappingURL=fieldLevel.js.map

package/dist/server/modules/translation-levels/index.d.ts

@@ -1,3 +1,4 @@
 export type { TranslationLevel } from "./types";
 export { documentLevel } from "./documentLevel";
 export { collectionLevel } from "./collectionLevel";
+export { fieldLevel } from "./fieldLevel";

package/dist/server/modules/translation-levels/index.js

@@ -1,4 +1,5 @@
 export { documentLevel } from "./documentLevel";
 export { collectionLevel } from "./collectionLevel";
+export { fieldLevel } from "./fieldLevel";
 
 //# sourceMappingURL=index.js.map

package/dist/server/modules/translation-levels/types.d.ts

@@ -1,6 +1,8 @@
 import type { CollectionConfig, Endpoint } from "payload";
 import type { AccessGuard } from "../../../types/AccessGuard";
 import type { RawPayloadComponentExport } from "../../../client/shared/types/PayloadComponentExport";
+import type { CollectionSchemaMap } from "../../features/translate-document";
+import type { TranslationProvider } from "../translation-providers";
 import type { TaskRunnerFactory } from "../task-runner";
 export type CollectionAdminSlot = "beforeDocumentControls" | "beforeListTable";
 /**
@@ -27,7 +29,6 @@ export interface TranslationLevel {
  *
  * A level contributes via these generic primitives; it never mutates the raw
  * Payload config. The plugin deduplicates endpoints by method + path on apply.
- * (fieldLevel — Phase 2 — will also read `schemaMap` + `translationProvider`.)
  * @internal
  */
 export interface LevelContext {
@@ -35,6 +36,10 @@ export interface LevelContext {
     readonly basePath: string;
     readonly access?: AccessGuard;
     readonly taskRunnerFactory: TaskRunnerFactory;
+    /** Deep-cloned localized field schema per managed collection slug. */
+    readonly schemaMap: CollectionSchemaMap;
+    /** The configured translation backend (used by the synchronous field level). */
+    readonly translationProvider: TranslationProvider;
     /** Register endpoints. Deduplicated by method + path when applied. */
     addEndpoints(endpoints: Endpoint[]): void;
     /** Attach an admin component to a slot on every managed collection. */

package/dist/server/modules/translation-levels/types.js

@@ -3,7 +3,6 @@
  *
  * A level contributes via these generic primitives; it never mutates the raw
  * Payload config. The plugin deduplicates endpoints by method + path on apply.
- * (fieldLevel — Phase 2 — will also read `schemaMap` + `translationProvider`.)
  * @internal
  */ export { };
 

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

@@ -1,5 +1,5 @@
 import { isEmpty, isObject } from "../../../../shared";
-import { resolveBlockFields, walkFields } from "../../../../shared/field-traversal";
+import { matchElementById, resolveBlockFields, walkFields } from "../../../../shared/field-traversal";
 const asObject = (value)=>isObject(value) ? value : {};
 /**
  * Reconcile walker: produces the full document shape from source + target, with target
@@ -7,6 +7,9 @@ const asObject = (value)=>isObject(value) ? value : {};
  * 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.
+ *
+ * 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];
@@ -21,15 +24,17 @@ const asObject = (value)=>isObject(value) ? value : {};
         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 = field.type === "blocks" ? resolveBlockFields(field, item) : field.fields;
+            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: asObject(targetArr[index])
+                    target: matchElementById(targetArr, item, isBlocks)
                 },
                 fields,
                 key: index
@@ -45,7 +50,8 @@ const asObject = (value)=>isObject(value) ? value : {};
     },
     combine (container, children, cursor) {
         if (container.kind === "list") {
-            // Rebuild the full array: reconciled objects where present (by index), raw source items otherwise.
+            // 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,

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

@@ -8,6 +8,11 @@ import type { FieldChunk } from "../../types";
  * mutable reference to its parent object (for later write-back). Collect-only — `combine` is a
  * no-op; results accumulate in a closure.
  *
+ * 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.
  */

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

@@ -1,5 +1,5 @@
 import { isFieldExcludedFromTranslation, isLocalizedField, isObject, isTranslatableField } from "../../../../shared";
-import { resolveBlockFields, walkFields } from "../../../../shared/field-traversal";
+import { matchElementById, resolveBlockFields, walkFields } from "../../../../shared/field-traversal";
 const asObject = (value)=>isObject(value) ? value : {};
 /**
  * Collects FieldChunks by walking schema + data with the shared {@link walkFields} engine.
@@ -8,6 +8,11 @@ const asObject = (value)=>isObject(value) ? value : {};
  * mutable reference to its parent object (for later write-back). Collect-only — `combine` is a
  * no-op; results accumulate in a closure.
  *
+ * 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.
  */ export class FieldChunkCollector {
@@ -47,16 +52,20 @@ const asObject = (value)=>isObject(value) ? value : {};
                 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)) return;
-                    const fields = field.type === "blocks" ? resolveBlockFields(field, item) : field.fields;
+                    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: asObject(sourceArr[index]),
-                            target: asObject(targetArr[index]),
+                            source: sourceItem,
+                            target: matchElementById(targetArr, sourceItem, isBlocks),
                             path: [
                                 ...cursor.path,
                                 field.name,

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

@@ -4,10 +4,15 @@ 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 or a named tab (a container,
- *   not a leaf).
- * - `inside-blocks` — the path descends THROUGH a `blocks` field, which can't be resolved from the
- *   schema alone (the block's `blockType` lives in the data, not the schema).
+ * - `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
@@ -19,6 +24,8 @@ export type FieldPathResult = {
     status: "container";
 } | {
     status: "inside-blocks";
+} | {
+    status: "localized-list-ancestor";
 } | {
     status: "not-found";
 };
@@ -26,15 +33,23 @@ export type FieldPathResult = {
  * 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} so the structural dispatch lives
- * in one place.
+ * path scope. Built on {@link classifyField} / {@link tabScopes} / {@link resolveBlockFields} so
+ * the structural dispatch lives in one place.
  *
- * The caller supplies already-prepared name segments (split, trimmed, with array indices dropped —
- * a field's config is shared across array items, so indices never appear in the schema).
+ * **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 (names) to match, head-first.
+ * @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[]): FieldPathResult;
+export declare function findFieldByPath(fields: Field[], segments: string[], data?: unknown): FieldPathResult;

package/dist/server/shared/field-traversal/findFieldByPath.js

@@ -1,19 +1,29 @@
-import { classifyField, tabScopes } from "./kernel";
+import { classifyField, resolveBlockFields, tabScopes } from "./kernel";
+const isIndexSegment = (segment)=>/^\d+$/u.test(segment);
+/** Safely read `key` off an object/array; `undefined` for non-objects (arrays index by string key). */ const childData = (data, key)=>data != null && typeof data === "object" ? data[key] : undefined;
 /**
  * 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} so the structural dispatch lives
- * in one place.
+ * path scope. Built on {@link classifyField} / {@link tabScopes} / {@link resolveBlockFields} so
+ * the structural dispatch lives in one place.
  *
- * The caller supplies already-prepared name segments (split, trimmed, with array indices dropped —
- * a field's config is shared across array items, so indices never appear in the schema).
+ * **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 (names) to match, head-first.
+ * @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 function findFieldByPath(fields, segments) {
+ */ export function findFieldByPath(fields, segments, data) {
     const [head, ...rest] = segments;
     if (head === undefined) return {
         status: "not-found"
@@ -28,10 +38,10 @@ import { classifyField, tabScopes } from "./kernel";
                             if (scope.tab.name === head) {
                                 return rest.length === 0 ? {
                                     status: "container"
-                                } : findFieldByPath(scope.tab.fields, rest);
+                                } : findFieldByPath(scope.tab.fields, rest, childData(data, head));
                             }
                         } else {
-                            const found = findFieldByPath(scope.fields, segments); // unnamed tab → same path scope
+                            const found = findFieldByPath(scope.fields, segments, data); // unnamed tab → same path + data scope
                             if (found.status !== "not-found") return found;
                         }
                     }
@@ -39,28 +49,63 @@ import { classifyField, tabScopes } from "./kernel";
                 }
             case "transparent":
                 {
-                    const found = findFieldByPath(structure.fields, segments); // row/collapsible/unnamed group → same scope
+                    const found = findFieldByPath(structure.fields, segments, data); // row/collapsible/unnamed group → same scope
                     if (found.status !== "not-found") return found;
                     break;
                 }
             case "presentational":
                 break;
             case "group":
-            case "array":
                 {
                     if (structure.name !== head) break;
                     return rest.length === 0 ? {
                         status: "container"
-                    } : findFieldByPath(structure.fields, rest);
+                    } : findFieldByPath(structure.fields, rest, childData(data, head));
+                }
+            case "array":
+                {
+                    if (structure.name !== head) break;
+                    if (rest.length === 0) return {
+                        status: "container"
+                    };
+                    // A localized array is an independent per-locale structure — its element index is not a
+                    // stable identity across locales, so refuse to navigate THROUGH it by path.
+                    if (structure.field.localized) return {
+                        status: "localized-list-ancestor"
+                    };
+                    // A numeric segment selects the data element; the schema is shared across elements.
+                    const [next, ...tail] = rest;
+                    if (isIndexSegment(next)) {
+                        return tail.length === 0 ? {
+                            status: "container"
+                        } : findFieldByPath(structure.fields, tail, childData(childData(data, head), next));
+                    }
+                    return findFieldByPath(structure.fields, rest, childData(data, head));
                 }
             case "blocks":
                 {
                     if (structure.name !== head) break;
-                    return rest.length === 0 ? {
+                    if (rest.length === 0) return {
                         status: "container"
-                    } : {
+                    };
+                    // A localized blocks field is an independent per-locale structure — its element index is
+                    // not a stable identity across locales, so refuse to navigate THROUGH it by path.
+                    if (structure.field.localized) return {
+                        status: "localized-list-ancestor"
+                    };
+                    // Polymorphic: need the element index + its data to pick the block schema by `blockType`.
+                    const [next, ...tail] = rest;
+                    if (!isIndexSegment(next)) return {
+                        status: "inside-blocks"
+                    };
+                    const item = childData(childData(data, head), next);
+                    const blockFields = resolveBlockFields(structure.field, item);
+                    if (!blockFields) return {
                         status: "inside-blocks"
                     };
+                    return tail.length === 0 ? {
+                        status: "container"
+                    } : findFieldByPath(blockFields, tail, item);
                 }
             case "leaf":
                 {

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

@@ -1,5 +1,5 @@
 export { findFieldByPath } from "./findFieldByPath";
 export type { FieldPathResult } from "./findFieldByPath";
-export { classifyField, resolveBlockFields, tabScopes } from "./kernel";
+export { classifyField, matchElementById, resolveBlockFields, tabScopes } from "./kernel";
 export type { ChildCursor, ChildOutput, ContainerInfo, FieldStructure, FieldWalker, LeafField, TabScope, WalkSignal } from "./types";
 export { walkFields } from "./walkFields";

package/dist/server/shared/field-traversal/index.js

@@ -1,5 +1,5 @@
 export { findFieldByPath } from "./findFieldByPath";
-export { classifyField, resolveBlockFields, tabScopes } from "./kernel";
+export { classifyField, matchElementById, resolveBlockFields, tabScopes } from "./kernel";
 export { walkFields } from "./walkFields";
 
 //# sourceMappingURL=index.js.map

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

@@ -83,3 +83,25 @@ export declare function tabScopes(field: TabsField): TabScope[];
  * @public
  */
 export declare function resolveBlockFields(field: BlocksField, item: unknown): Field[] | null;
+/**
+ * Find the element of a parallel data array that corresponds to `refItem` by `id` — not by
+ * position.
+ *
+ * Localized `blocks`/`array` fields are stored independently per locale, so the locales can be
+ * reordered or differ entirely; pairing two parallel trees by position then cross-contaminates
+ * unrelated elements ("blocks don't line up across locales"). Matching by `id` is correct in both
+ * regimes: a non-localized field is one shared row with the same `id` across locales (so id-match
+ * equals the old positional match), while independent localized content has diverging ids (no
+ * match → the caller falls back to `refItem`'s own values, never another element's). For blocks the
+ * `blockType` must also match, so an id collision across types can't graft mismatched fields.
+ *
+ * Shared by the translation pipeline's two multi-tree walkers — reconcile and collect — to pair
+ * their `target` array against the source/reference element currently being visited.
+ *
+ * @param arr - The array to search (e.g. the target-locale elements).
+ * @param refItem - The element being matched, carrying the canonical `id` (and `blockType`).
+ * @param isBlocks - Whether the field is a `blocks` field (then `blockType` must also match).
+ * @returns The matched element, or `{}` when there is no counterpart (or `refItem` carries no `id`).
+ * @public
+ */
+export declare function matchElementById(arr: unknown[], refItem: Record<string, unknown>, isBlocks: boolean): Record<string, unknown>;

package/dist/server/shared/field-traversal/kernel.js

@@ -1,5 +1,6 @@
 import { fieldAffectsData, fieldIsArrayType, fieldIsBlockType, fieldIsGroupType, tabHasName } from "payload/shared";
 import { hasFields, isBlockItem, isTabsField } from "../guards";
+import { isObject } from "../utils";
 /**
  * Classify a single Payload {@link Field} into a discriminated {@link FieldStructure} — the
  * one place that encodes how Payload field types map onto data boundaries.
@@ -141,5 +142,31 @@ import { hasFields, isBlockItem, isTabsField } from "../guards";
     const block = field.blocks.find((candidate)=>candidate.slug === item.blockType);
     return block ? block.fields : null;
 }
+/**
+ * Find the element of a parallel data array that corresponds to `refItem` by `id` — not by
+ * position.
+ *
+ * Localized `blocks`/`array` fields are stored independently per locale, so the locales can be
+ * reordered or differ entirely; pairing two parallel trees by position then cross-contaminates
+ * unrelated elements ("blocks don't line up across locales"). Matching by `id` is correct in both
+ * regimes: a non-localized field is one shared row with the same `id` across locales (so id-match
+ * equals the old positional match), while independent localized content has diverging ids (no
+ * match → the caller falls back to `refItem`'s own values, never another element's). For blocks the
+ * `blockType` must also match, so an id collision across types can't graft mismatched fields.
+ *
+ * Shared by the translation pipeline's two multi-tree walkers — reconcile and collect — to pair
+ * their `target` array against the source/reference element currently being visited.
+ *
+ * @param arr - The array to search (e.g. the target-locale elements).
+ * @param refItem - The element being matched, carrying the canonical `id` (and `blockType`).
+ * @param isBlocks - Whether the field is a `blocks` field (then `blockType` must also match).
+ * @returns The matched element, or `{}` when there is no counterpart (or `refItem` carries no `id`).
+ * @public
+ */ export function matchElementById(arr, refItem, isBlocks) {
+    const id = refItem.id;
+    if (id === undefined || id === null) return {};
+    const match = arr.find((candidate)=>isObject(candidate) && candidate.id === id && (!isBlocks || candidate.blockType === refItem.blockType));
+    return isObject(match) ? match : {};
+}
 
 //# sourceMappingURL=kernel.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@focus-reactive/payload-plugin-translator",
-  "version": "0.5.1",
+  "version": "0.6.1",
   "description": "Translation plugin for Payload CMS 3.x. Automatically translate your localized content using any translation provider.",
   "type": "module",
   "license": "MIT",
@@ -50,7 +50,7 @@
     "build:types": "tsc --emitDeclarationOnly --declaration --outDir dist",
     "copyfiles": "copyfiles -u 1 \"src/**/*.scss\" dist",
     "clean": "rm -rf dist",
-    "dev": "bun run build:swc -- --watch",
+    "dev": "bun run build:swc -- --watch --copy-files",
     "lint": "ultracite check",
     "lint:fix": "ultracite fix",
     "test": "vitest run",