@purposeinplay/payload-ai-translate 0.1.0

package/dist/lib/field-resolver.js

@@ -0,0 +1,164 @@
+const TRANSLATABLE_LEAF_TYPES = new Set([
+    'text',
+    'textarea',
+    'richText',
+    'json'
+]);
+const CONTAINER_TYPES = new Set([
+    'group',
+    'array',
+    'blocks'
+]);
+const TRANSPARENT_TYPES = new Set([
+    'row',
+    'collapsible'
+]);
+function buildPath(parent, segment) {
+    return parent ? `${parent}.${segment}` : segment;
+}
+function isNamedTab(tab) {
+    return 'name' in tab && typeof tab.name === 'string';
+}
+function hasFieldsProperty(field) {
+    return 'fields' in field && Array.isArray(field.fields);
+}
+function hasBlocksProperty(field) {
+    return 'blocks' in field && Array.isArray(field.blocks);
+}
+function hasTabsProperty(field) {
+    return 'tabs' in field && Array.isArray(field.tabs);
+}
+function getFieldName(field) {
+    return 'name' in field ? field.name : undefined;
+}
+function isLocalized(field) {
+    return 'localized' in field && field.localized === true;
+}
+export function resolveTranslatableFields(fields, parentPath = '', inheritedLocalized = false) {
+    const result = [];
+    for (const field of fields){
+        const { type } = field;
+        // Transparent layout containers — recurse without adding a path segment
+        if (TRANSPARENT_TYPES.has(type)) {
+            if (hasFieldsProperty(field)) {
+                result.push(...resolveTranslatableFields(field.fields, parentPath, inheritedLocalized));
+            }
+            continue;
+        }
+        // Tabs — each tab's fields are traversed; named tabs add a path segment
+        if (type === 'tabs' && hasTabsProperty(field)) {
+            for (const tab of field.tabs){
+                const tabPath = isNamedTab(tab) ? buildPath(parentPath, tab.name) : parentPath;
+                result.push(...resolveTranslatableFields(tab.fields, tabPath, inheritedLocalized));
+            }
+            continue;
+        }
+        // From here, only named fields matter
+        const name = getFieldName(field);
+        if (!name) continue;
+        // Payload auto-injects an `id` text field onto every array item at runtime.
+        // It carries the row's UUID and must never be sent through translation —
+        // the locale-update would also reject the write since `id` is read-only on
+        // partial updates.
+        if (name === 'id' && type === 'text') continue;
+        const fieldPath = buildPath(parentPath, name);
+        // A field is translatable if it's marked localized OR an ancestor
+        // container (array/blocks/group) is localized. Payload localizes the
+        // entire container per locale, so descendants implicitly need translation
+        // even when not individually flagged `localized: true`.
+        const localized = isLocalized(field) || inheritedLocalized;
+        // Translatable leaf types
+        if (TRANSLATABLE_LEAF_TYPES.has(type)) {
+            if (localized) {
+                result.push({
+                    path: fieldPath,
+                    type: type,
+                    localized: true
+                });
+            }
+            continue;
+        }
+        // Group
+        if (type === 'group' && hasFieldsProperty(field)) {
+            if (localized) {
+                result.push({
+                    path: fieldPath,
+                    type: 'group',
+                    localized: true
+                });
+                result.push(...resolveTranslatableFields(field.fields, fieldPath, true));
+            } else {
+                result.push(...resolveTranslatableFields(field.fields, fieldPath, false));
+            }
+            continue;
+        }
+        // Array
+        if (type === 'array' && hasFieldsProperty(field)) {
+            if (localized) {
+                result.push({
+                    path: fieldPath,
+                    type: 'array',
+                    localized: true
+                });
+                // Recurse so descendant leaves are discoverable by the extractor.
+                // All descendants inherit localization from this array.
+                result.push(...resolveTranslatableFields(field.fields, fieldPath, true));
+            } else {
+                // Items are indexed at runtime; recurse with arrayName prefix so
+                // individual localized fields inside the array are discovered.
+                const children = resolveTranslatableFields(field.fields, fieldPath, false);
+                // If any descendant is localized (e.g. a navigation `label` field
+                // marked `localized: true` while the parent array is shared across
+                // locales — the canonical Payload pattern for "structure shared,
+                // labels per-locale"), we still need to emit the array entry so
+                // `extractTranslationUnits` calls `extractArrayUnits` and iterates
+                // items by index. Without this, leaf paths like
+                // `items.label` are emitted but never resolved — `getValueAtPath`
+                // bails at the array because `'label'` isn't a numeric segment.
+                if (children.some((c)=>c.localized)) {
+                    result.push({
+                        path: fieldPath,
+                        type: 'array',
+                        localized: false
+                    });
+                }
+                result.push(...children);
+            }
+            continue;
+        }
+        // Blocks
+        if (type === 'blocks' && hasBlocksProperty(field)) {
+            if (localized) {
+                result.push({
+                    path: fieldPath,
+                    type: 'blocks',
+                    localized: true
+                });
+                for (const block of field.blocks){
+                    result.push(...resolveTranslatableFields(block.fields, fieldPath, true));
+                }
+            } else {
+                // Same rationale as the array branch above: when any block's
+                // descendant is individually localized, emit the blocks entry so
+                // `extractBlocksUnits` runs and resolves leaves through runtime
+                // indexing. Without it, paths inside blocks-children are emitted
+                // but never resolved by the extractor.
+                const children = [];
+                for (const block of field.blocks){
+                    children.push(...resolveTranslatableFields(block.fields, fieldPath, false));
+                }
+                if (children.some((c)=>c.localized)) {
+                    result.push({
+                        path: fieldPath,
+                        type: 'blocks',
+                        localized: false
+                    });
+                }
+                result.push(...children);
+            }
+        }
+    // All other types (number, email, date, select, radio, checkbox,
+    // json, code, point, relationship, upload, ui, join) — skip
+    }
+    return result;
+}

package/dist/lib/group-soft-skips.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Group soft-skipped fields across locales by their source value.
+ *
+ * The Translation Hub renders these for editors who want to understand
+ * which source strings the AI declined to translate. Today the AI may
+ * echo a brand name ("Wheel Of") across every locale — surfacing that
+ * once per (field × locale) drowns the editor in repetition. Grouping
+ * by value collapses the noise:
+ *
+ *   "Wheel Of"
+ *     used in: sidebar.featured_sidebar_items.3.label
+ *     kept in: de, es, fr (3 locales)
+ *
+ * Falls back to grouping by path for legacy rows where `sourceValue`
+ * was never persisted (pre-1.2.8) — those entries display the path
+ * alone, same as the pre-grouping rendering.
+ */
+export type SoftSkipEntry = {
+    path: string;
+    locale: string;
+    reason?: string | null;
+    reasonCode?: string | null;
+    sourceValue?: string | null;
+};
+export type SoftSkipGroup = {
+    /** Source-locale text. Null when the entry is a legacy row with no value. */
+    sourceValue: string | null;
+    /** All field paths this value appears in (deduped, original order). */
+    paths: string[];
+    /** All locales the AI kept this value verbatim in (deduped, original order). */
+    locales: string[];
+    /** The first non-empty reason code in the group — used for the editor message. */
+    reasonCode: string | null;
+    /** First raw reason string seen in the group — used as the technical-details fallback. */
+    reason: string | null;
+    /** Total number of (path × locale) entries collapsed into this group. */
+    count: number;
+};
+export declare function groupSoftSkipsByValue(entries: ReadonlyArray<SoftSkipEntry>): SoftSkipGroup[];

package/dist/lib/group-soft-skips.js

@@ -0,0 +1,45 @@
+/**
+ * Group soft-skipped fields across locales by their source value.
+ *
+ * The Translation Hub renders these for editors who want to understand
+ * which source strings the AI declined to translate. Today the AI may
+ * echo a brand name ("Wheel Of") across every locale — surfacing that
+ * once per (field × locale) drowns the editor in repetition. Grouping
+ * by value collapses the noise:
+ *
+ *   "Wheel Of"
+ *     used in: sidebar.featured_sidebar_items.3.label
+ *     kept in: de, es, fr (3 locales)
+ *
+ * Falls back to grouping by path for legacy rows where `sourceValue`
+ * was never persisted (pre-1.2.8) — those entries display the path
+ * alone, same as the pre-grouping rendering.
+ */ export function groupSoftSkipsByValue(entries) {
+    const buckets = new Map();
+    for (const e of entries){
+        // Bucket on source value when present; fall back to path so legacy
+        // rows (no sourceValue) still appear once per path rather than
+        // collapsing every legacy entry into a single noise bucket.
+        const bucketKey = e.sourceValue ? `v:${e.sourceValue}` : `p:${e.path}`;
+        let group = buckets.get(bucketKey);
+        if (!group) {
+            group = {
+                sourceValue: e.sourceValue ?? null,
+                paths: [],
+                locales: [],
+                reasonCode: e.reasonCode ?? null,
+                reason: e.reason ?? null,
+                count: 0
+            };
+            buckets.set(bucketKey, group);
+        }
+        if (!group.paths.includes(e.path)) group.paths.push(e.path);
+        if (!group.locales.includes(e.locale)) group.locales.push(e.locale);
+        if (!group.reasonCode && e.reasonCode) group.reasonCode = e.reasonCode;
+        if (!group.reason && e.reason) group.reason = e.reason;
+        group.count += 1;
+    }
+    return [
+        ...buckets.values()
+    ];
+}

package/dist/lib/locale-merge.d.ts

@@ -0,0 +1,44 @@
+import type { TranslatableField } from '../types.js';
+export type MergeParams = {
+    sourceDoc: Record<string, unknown>;
+    targetDoc: Record<string, unknown> | null | undefined;
+    translatedMap: Map<string, string>;
+    fields: TranslatableField[];
+    translatedTopFields: Set<string>;
+    /**
+     * When provided, overrides the union derived from `fields`. Used by callers
+     * that filter `fields` down to a subset (e.g. per-field translate) but
+     * still need the merge to include all localized top-level fields so
+     * required-localized siblings stay populated in the locale-write body.
+     */
+    allLocalizedTopFields?: Set<string>;
+    /**
+     * `'full'` (default): emit every localized top-level field, filling
+     * untranslated siblings from existing target / source fallback. Safe
+     * default — Payload's locale-write validation always passes.
+     *
+     * `'minimal'`: emit ONLY top-level fields that actually got translated.
+     * Caller accepts that Payload may reject the write when other localized
+     * required fields are empty in target. Useful when target is known to be
+     * fully populated and the caller doesn't want to touch siblings.
+     */
+    writeMode?: 'full' | 'minimal';
+};
+/**
+ * Build the writeData object for a locale-specific update.
+ *
+ * Strategy: for each top-level field that has at least one translated unit,
+ * start from the existing target-locale value (so we preserve any prior
+ * translations + required-localized siblings), fall back to the source value
+ * when target is empty/missing, then overlay the new translations via the
+ * existing patcher. Strip Payload internal columns recursively before
+ * returning.
+ *
+ * Why merge target-first: `payload.update({ locale, data })` validates the
+ * data against the full schema, so if a required-localized field is missing
+ * in the target locale Payload rejects the write. Reading the target locale
+ * (via `findByIdNoFallback`/`findGlobalNoFallback`) gives us the existing
+ * shape we can safely overlay. When the target is fresh (no rows yet) we
+ * fall back to the source clone — Payload generates ids on insert.
+ */
+export declare function mergeTranslationsIntoTargetDoc(params: MergeParams): Record<string, unknown>;

package/dist/lib/locale-merge.js

@@ -0,0 +1,357 @@
+import { patchTranslatedContent } from './content-patcher.js';
+// Fields Payload either auto-generates or rejects on update. Stripped
+// recursively from the merge output before write so the locale update body
+// never carries internals that round-tripped from a `findByID` read.
+//
+// `_locale`, `_parent_id`, `_uuid` are the row-level columns Payload exposes
+// for nested localized rows (arrays, blocks, groups). They surface in the
+// JSON shape returned by the local API but Payload's update validator
+// rejects them as invalid input.
+// Fields Payload either auto-generates or rejects on update. They CAN
+// surface in the source doc the merge is built from (relationship
+// hydration, nested upload metadata) but must never be sent back via
+// `payload.update` — Payload either generates them server-side or
+// rejects them as invalid input.
+//
+// Notably absent: `url`, `filename`, `thumbnailURL`. Those would catch
+// auto-generated media-doc fields IF a Media collection were translated
+// directly, but they're also legitimate text-field names users give to
+// regular content (link `url`, slug-like `filename`). Stripping them
+// blanket breaks normal writes. The locale-write only emits translated
+// top-level fields anyway, so a Media doc's auto-generated `url` never
+// enters writeData unless the consumer explicitly translates it.
+const STRIP_FIELDS = new Set([
+    // Doc-level system fields
+    'createdAt',
+    'updatedAt',
+    '_status',
+    // Localization internals
+    '_locale',
+    '_parent_id',
+    '_uuid',
+    // nestedDocs plugin
+    'slugLock',
+    'breadcrumbs'
+]);
+/**
+ * Build the writeData object for a locale-specific update.
+ *
+ * Strategy: for each top-level field that has at least one translated unit,
+ * start from the existing target-locale value (so we preserve any prior
+ * translations + required-localized siblings), fall back to the source value
+ * when target is empty/missing, then overlay the new translations via the
+ * existing patcher. Strip Payload internal columns recursively before
+ * returning.
+ *
+ * Why merge target-first: `payload.update({ locale, data })` validates the
+ * data against the full schema, so if a required-localized field is missing
+ * in the target locale Payload rejects the write. Reading the target locale
+ * (via `findByIdNoFallback`/`findGlobalNoFallback`) gives us the existing
+ * shape we can safely overlay. When the target is fresh (no rows yet) we
+ * fall back to the source clone — Payload generates ids on insert.
+ */ export function mergeTranslationsIntoTargetDoc(params) {
+    const { sourceDoc, targetDoc, translatedMap, fields, translatedTopFields, allLocalizedTopFields, writeMode = 'full' } = params;
+    // Top-level fields that are localized in the schema. The `'full'` mode
+    // (default) includes ALL of them in the write data — not just those with
+    // translated units — so Payload's required-localized-field validation
+    // passes when the target locale row is fresh. Each value still uses the
+    // target-first / source-fallback strategy below, so we never overwrite
+    // existing target content with source values.
+    //
+    // Why `'full'` matters: per-field translate restricts `translatedTopFields`
+    // to a single key (e.g. `{'title'}`). Without this expansion, writing to
+    // a locale that doesn't yet have a row would fail with
+    // "field is invalid: <other-required-localized-field>" because Payload
+    // validates the full schema on the locale-update body.
+    //
+    // `'minimal'` mode skips the expansion entirely — only translated top-
+    // fields are written. Caller is responsible for ensuring Payload accepts
+    // a partial write (target row already populated, no required-but-empty
+    // siblings).
+    const localizedTopFields = new Set(translatedTopFields);
+    if (writeMode === 'full') {
+        if (allLocalizedTopFields) {
+            for (const name of allLocalizedTopFields)localizedTopFields.add(name);
+        } else {
+            for (const f of fields){
+                if (f.localized) {
+                    localizedTopFields.add(f.path.split('.')[0]);
+                }
+            }
+        }
+    }
+    // Build the merge base: target value if present, else source value.
+    // For array-typed fields and any nested arrays we encounter while walking,
+    // align the base shape to the source shape (see `alignBaseShapeToSource`).
+    // For object-typed fields (groups, JSON containers), align recursively via
+    // `alignObjectArraysToSource` so target objects reshape to match source —
+    // dropped keys are pruned, nested arrays reshape, and new keys get seeded
+    // from source. The patcher walks paths derived from source extraction;
+    // when target shape diverges from source, path-keyed translations silently
+    // drop on the floor and stale data persists. Aligning shape recursively
+    // kills that bug class at every nesting level instead of only the top.
+    const base = {};
+    for (const topField of localizedTopFields){
+        const targetValue = targetDoc?.[topField];
+        if (targetValue !== undefined && targetValue !== null && !isEmpty(targetValue)) {
+            base[topField] = structuredClone(targetValue);
+            const sourceValue = sourceDoc[topField];
+            if (Array.isArray(base[topField]) && Array.isArray(sourceValue)) {
+                alignBaseShapeToSource(base[topField], sourceValue);
+            } else if (base[topField] && sourceValue && typeof base[topField] === 'object' && typeof sourceValue === 'object' && !Array.isArray(base[topField]) && !Array.isArray(sourceValue)) {
+                // Object reshape: drop target-only keys, propagate source nesting,
+                // align nested arrays. Skips Lexical roots (`root` key) — those have
+                // their own deserializer path via `patchTranslatedContent`.
+                alignObjectArraysToSource(base[topField], sourceValue);
+            }
+        } else if (topField in sourceDoc) {
+            // Fresh target locale (no prior translation data). Use source
+            // as the shape skeleton, but STRIP array-row `id` fields so
+            // Payload generates fresh ones for the target locale. If we
+            // kept the source ids, the locale write would try to insert
+            // rows into shared `<col>_blocks_*` / `<col>_*` parent tables
+            // with ids that ALREADY EXIST (those are the source-locale's
+            // rows) — Payload's drizzle `upsertRow` then throws
+            // "Value must be unique: id" and the whole locale write
+            // fails. Reproduced 2026-06-04 on `pages/34` for every
+            // non-EN locale that had no prior data; debug trail confirmed
+            // writeData carried source-locale block ids verbatim.
+            //
+            // We DON'T strip ids in the targetValue-present branch above
+            // because reusing existing target row ids is safe (and
+            // intentional — stripping ids on a row-present write forces a
+            // delete+recreate that cascades into other locales' `_locales`
+            // children, the 2026-06-04 nav-data-loss incident the v1.2.7
+            // STRIP_FIELDS comment warns about).
+            base[topField] = stripArrayItemIds(structuredClone(sourceDoc[topField]));
+        }
+    }
+    // Apply translations onto the base. The patcher mutates a clone of `base`
+    // and writes translated leaves into it. `sourceDoc` is passed separately
+    // so the patcher can recover structural skeletons (Lexical trees, etc.)
+    // from the TRUE source when the merge base has an empty / placeholder
+    // shape from a fresh target locale — without this, Lexical content gets
+    // flattened to a single empty paragraph.
+    const patched = patchTranslatedContent(base, translatedMap, fields, sourceDoc);
+    // Emit all localized top-level fields. System columns stripped recursively;
+    // array-item ids unconditionally stripped (see comment above STRIP_FIELDS).
+    const writeData = {};
+    for (const topField of localizedTopFields){
+        if (topField in patched) {
+            writeData[topField] = stripSystem(patched[topField]);
+        }
+    }
+    return writeData;
+}
+function isEmpty(value) {
+    if (value === null || value === undefined) return true;
+    if (Array.isArray(value)) return value.length === 0;
+    if (typeof value === 'object') {
+        return Object.keys(value).length === 0;
+    }
+    return false;
+}
+/**
+ * Mutates `base` so its array shape matches `source` at every nesting level.
+ * Truncates excess items, fills sparse/null slots from source, and replaces
+ * items where shape (array vs object vs primitive) or `blockType` diverges.
+ * Recurses into matching object slots and matching array slots so deletions,
+ * reorders, and type swaps inside nested arrays propagate too — not just at
+ * the top level.
+ *
+ * Why this exists: the patcher walks paths derived from the source. When
+ * target shape diverges from source, path-keyed translations land on stale
+ * shapes (or vanish silently). Aligning recursively kills that bug class at
+ * every nesting level instead of patching one boundary.
+ */ function alignBaseShapeToSource(base, source) {
+    base.length = source.length;
+    for(let i = 0; i < source.length; i++){
+        const baseItem = base[i];
+        const sourceItem = source[i];
+        if (baseItem === undefined || baseItem === null) {
+            // Gap fill: target has no counterpart at this index. The new row
+            // must NOT inherit source's array-row ids — `_parent_id` on nested
+            // child tables points at the source-locale's parent row, so writing
+            // these ids under the target locale fails with "field is invalid:
+            // id". Strip top-level + nested ids so Payload generates fresh ones.
+            base[i] = cloneSourceItemAsNewLocaleRow(sourceItem);
+            continue;
+        }
+        const baseIsArray = Array.isArray(baseItem);
+        const sourceIsArray = Array.isArray(sourceItem);
+        // Shape divergence: array-vs-not, object-vs-primitive — replace from source.
+        // Same id-strip reasoning as the gap-fill branch above.
+        if (baseIsArray !== sourceIsArray || typeof baseItem !== typeof sourceItem) {
+            base[i] = cloneSourceItemAsNewLocaleRow(sourceItem);
+            continue;
+        }
+        if (baseIsArray && sourceIsArray) {
+            alignBaseShapeToSource(baseItem, sourceItem);
+            continue;
+        }
+        if (baseItem && sourceItem && typeof baseItem === 'object' && !baseIsArray) {
+            const baseObj = baseItem;
+            const sourceObj = sourceItem;
+            const baseType = baseObj.blockType;
+            const sourceType = sourceObj.blockType;
+            if (baseType !== undefined && sourceType !== undefined && baseType !== sourceType) {
+                // Block type changed — base item's ids belong to the OLD blockType
+                // and can't be reused for the new shape. Strip and let Payload
+                // regenerate.
+                base[i] = cloneSourceItemAsNewLocaleRow(sourceItem);
+                continue;
+            }
+            alignObjectArraysToSource(baseObj, sourceObj);
+        }
+    }
+}
+/**
+ * Walks an object and recurses into any arrays/objects on the source side,
+ * aligning the base's matching array fields and pruning keys the source no
+ * longer has. Skips Lexical roots (`root` key) which have their own
+ * deserializer; flattening those would break rich text.
+ *
+ * Key pruning is required for free-shape fields (`type: 'json'`) where the
+ * source object's keys can change between publishes. Without pruning, target
+ * keeps stale keys removed from source. For schema-fixed fields (block sub-
+ * fields, group fields), pruning is harmless because Payload validates
+ * writes against the schema regardless.
+ */ function alignObjectArraysToSource(base, source) {
+    if ('root' in source) return; // Lexical — leave to deserializer
+    // Prune keys present in base but absent from source.
+    for (const key of Object.keys(base)){
+        if (!(key in source)) {
+            delete base[key];
+        }
+    }
+    for (const key of Object.keys(source)){
+        const baseVal = base[key];
+        const sourceVal = source[key];
+        if (Array.isArray(sourceVal)) {
+            if (Array.isArray(baseVal)) {
+                alignBaseShapeToSource(baseVal, sourceVal);
+            } else {
+                // Shape divergence at this key — base had something non-array,
+                // source has an array. Strip element ids on the source clone so
+                // Payload regenerates them for the new locale's rows.
+                base[key] = stripArrayItemIds(structuredClone(sourceVal));
+            }
+        } else if (sourceVal && baseVal && typeof sourceVal === 'object' && typeof baseVal === 'object' && !Array.isArray(sourceVal) && !Array.isArray(baseVal)) {
+            alignObjectArraysToSource(baseVal, sourceVal);
+        } else if (baseVal === undefined && sourceVal !== undefined) {
+            // Source has a key base doesn't (after the prune step this means base
+            // never had it). Seed from source so subsequent translation units land.
+            // Nested array ids stripped — same _parent_id reasoning as in
+            // `alignBaseShapeToSource`.
+            base[key] = walkAndStripArrayIds(structuredClone(sourceVal));
+        }
+    }
+}
+function stripSystem(value) {
+    if (value === null || value === undefined) return value;
+    if (typeof value !== 'object') return value;
+    if (Array.isArray(value)) {
+        // Recurse — each child is an array item. We PRESERVE the item's `id`
+        // (see comment on the id-handling branch below).
+        return value.map((item)=>stripSystem(item));
+    }
+    const obj = value;
+    // RichText (Lexical) values have a `root` key and shouldn't be flattened.
+    // Their internal structure is a separate concern handled by the lexical
+    // serializer/deserializer.
+    if ('root' in obj) {
+        return obj;
+    }
+    const out = {};
+    for (const [key, val] of Object.entries(obj)){
+        if (STRIP_FIELDS.has(key)) continue;
+        // v1.2.7 critical fix — DO NOT strip array-item `id`.
+        //
+        // Pre-v1.2.7 this function stripped `id` from every array item before
+        // a locale-scoped `updateGlobal` / `updateOne` write, on the (wrong)
+        // theory that Payload would regenerate fresh ids per locale. In
+        // Payload's Postgres adapter the array-row id is SHARED across
+        // locales — the `_locales` child tables key on (_parent_id, _locale)
+        // with `ON DELETE CASCADE` on _parent_id. When the incoming array
+        // items have no id, Payload cannot match them to existing rows and
+        // DELETE+RECREATE the parent rows, which cascades into the `_locales`
+        // children of EVERY locale (including the source). Result: writing
+        // the German translation wipes the English source labels of every
+        // localized array on the global. This was the cause of the
+        // wild-payload-cms / wolf nav-data-loss incident (2026-06-04).
+        //
+        // Preserve `id` whenever the array item already carries one — that
+        // tells Payload "match this existing row, just update the per-locale
+        // leaf values". Items with no id are genuinely new (rare on a
+        // translation write path) and Payload will create them.
+        out[key] = stripSystem(val);
+    }
+    return out;
+}
+/**
+ * Recursively strip the `id` field from every array item in `value`,
+ * leaving object-level ids and primitive values untouched. Used by the
+ * merge function when a fresh target locale falls back to cloning the
+ * source — keeping the source's array-row ids would collide with the
+ * existing source rows in Payload's shared `<col>_blocks_*` /
+ * `<col>_<array>` tables (Postgres PK conflict). Stripping them lets
+ * Payload generate fresh ids for the new locale.
+ *
+ * Only `id` on array elements is stripped — non-array object `id`
+ * fields (e.g. Lexical node fragments that may carry an id for
+ * downstream tooling) stay intact. This narrower scope avoids the
+ * cascading delete+recreate of `_locales` children that the
+ * unconditional `stripSystem` strip caused in pre-1.2.7.
+ */ function stripArrayItemIds(value) {
+    if (value === null || value === undefined || typeof value !== 'object') {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        return value.map((item)=>{
+            if (item !== null && typeof item === 'object' && !Array.isArray(item) && 'id' in item) {
+                const { id: _stripped, ...rest } = item;
+                // Recurse into the stripped item's own nested arrays so deep
+                // array structures (e.g. blocks → array of items → array of
+                // sub-items) all get their array-row ids stripped, not just
+                // the top level.
+                return walkAndStripArrayIds(rest);
+            }
+            return walkAndStripArrayIds(item);
+        });
+    }
+    return walkAndStripArrayIds(value);
+}
+function walkAndStripArrayIds(value) {
+    if (value === null || value === undefined || typeof value !== 'object') {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        return stripArrayItemIds(value);
+    }
+    const out = {};
+    for (const [key, val] of Object.entries(value)){
+        out[key] = walkAndStripArrayIds(val);
+    }
+    return out;
+}
+/**
+ * Clone an array element with its top-level `id` AND every nested
+ * array-row `id` stripped. Use when the alignment step fills a gap in
+ * the target array from a source item — Payload must generate fresh
+ * ids for the new locale's rows; carrying source ids forward causes
+ * "field is invalid: id" on locale-scoped writes whose nested arrays
+ * point at the wrong _parent_id.
+ *
+ * Symmetric to `stripArrayItemIds` but applied to a SINGLE item rather
+ * than mapping over an array. Preserves the v1.2.7 invariant that
+ * existing target-row ids are NOT stripped: callers only invoke this
+ * on items they are creating fresh, never on items already present in
+ * the target locale.
+ */ function cloneSourceItemAsNewLocaleRow(item) {
+    const cloned = structuredClone(item);
+    if (cloned !== null && typeof cloned === 'object' && !Array.isArray(cloned) && 'id' in cloned) {
+        const { id: _stripped, ...rest } = cloned;
+        return walkAndStripArrayIds(rest);
+    }
+    return walkAndStripArrayIds(cloned);
+}