@braze/sanity-plugin-ai-translation 0.2.6 → 0.2.7

package/dist/index.js

@@ -1,6 +1,6 @@
 import { getPublishedId, pathToString, useClient, defineType, defineField, definePlugin } from "sanity";
 import { jsx, jsxs, Fragment } from "react/jsx-runtime";
-import { WarningOutlineIcon, SearchIcon, CheckmarkIcon, ErrorOutlineIcon, CircleIcon, ArrowRightIcon, ResetIcon, PanelRightIcon, TranslateIcon } from "@sanity/icons";
+import { WarningOutlineIcon, SyncIcon, SearchIcon, CheckmarkIcon, ErrorOutlineIcon, CircleIcon, ArrowRightIcon, ResetIcon, PanelRightIcon, TranslateIcon } from "@sanity/icons";
 import { createContext, useReducer, useRef, useEffect, useContext, useMemo, useState, useCallback } from "react";
 import defaults from "lodash.defaults";
 import { Card, Stack, Flex, Text, Box, Heading, Button, Spinner, Inline, Checkbox, Grid, Radio, TextInput, Badge, Select, Label, Code, Tooltip } from "@sanity/ui";
@@ -122,6 +122,8 @@ const isLoggingEnabled = () => process.env.NEXT_PUBLIC_SANITY_STUDIO_AI_TRANSLAT
     mode: "new",
     newReleaseTitle: ""
   },
+  reconcilingStatus: "idle",
+  reconciliationProgress: void 0,
   dispatch: () => {
   }
 }), translationReducer = (context, action) => {
@@ -207,8 +209,24 @@ const isLoggingEnabled = () => process.env.NEXT_PUBLIC_SANITY_STUDIO_AI_TRANSLAT
         releaseConfig: {
           ...context.releaseConfig,
           conflicts: void 0,
-          replaceExisting: void 0
-        }
+          replaceExisting: void 0,
+          skipConflicts: void 0
+        },
+        // Reset reconciliation state
+        reconcilingStatus: "idle",
+        reconciliationProgress: void 0
+      };
+    case "SET_RECONCILING_STATUS":
+      return {
+        ...context,
+        reconcilingStatus: action.payload,
+        // Clear progress when returning to idle or on error
+        reconciliationProgress: action.payload === "idle" || action.payload === "error" ? void 0 : context.reconciliationProgress
+      };
+    case "SET_RECONCILIATION_PROGRESS":
+      return {
+        ...context,
+        reconciliationProgress: action.payload
       };
     default:
       return context;
@@ -238,7 +256,10 @@ const isLoggingEnabled = () => process.env.NEXT_PUBLIC_SANITY_STUDIO_AI_TRANSLAT
     releaseConfig: {
       mode: "new",
       newReleaseTitle: defaultReleaseTitle
-    }
+    },
+    // Reconciliation state for existing releases
+    reconcilingStatus: "idle",
+    reconciliationProgress: void 0
   };
   activeTranslation && devLog.info("Reconnecting to active translation", {
     documentId: document._id,
@@ -505,7 +526,7 @@ const DEFAULT_RETRY_OPTIONS = {
   logRetries: !0
 };
 function calculateDelay(attempt, options) {
-  const delay = options.initialDelayMs * Math.pow(options.backoffMultiplier, attempt);
+  const delay = options.initialDelayMs * options.backoffMultiplier ** attempt;
   return Math.min(delay, options.maxDelayMs);
 }
 function sleep(ms) {
@@ -924,6 +945,85 @@ const fetchTranslationPrompts = async ({
     translatedCount: translationMap.size,
     component: "updateReferences"
   }));
+}, updateBackwardReferences = async ({
+  client,
+  releaseId,
+  sourceDocumentIds,
+  targetLanguages,
+  sourceLanguage,
+  languageFieldName,
+  excludeDocumentIds
+}) => {
+  if (!sourceDocumentIds.length || !targetLanguages.length)
+    return;
+  const normalizedSourceIds = sourceDocumentIds.map((id) => getPublishedId(id));
+  devLog.debug("Starting backward reference update", {
+    releaseId,
+    sourceDocumentCount: normalizedSourceIds.length,
+    targetLanguages,
+    excludeCount: excludeDocumentIds.length,
+    component: "updateBackwardReferences"
+  });
+  try {
+    for (const targetLanguage of targetLanguages) {
+      const existingDocsWithStaleRefs = await client.fetch(
+        `*[
+          _id match "versions." + $releaseId + ".*" &&
+          @[$languageFieldName] == $targetLanguage &&
+          !(_id in $excludeIds)
+        ] {
+          _id,
+          "hasStaleRefs": count(*[
+            _id in $sourceDocumentIds && 
+            ^references(@._id)
+          ]) > 0
+        }[hasStaleRefs == true]`,
+        {
+          releaseId,
+          targetLanguage,
+          languageFieldName,
+          excludeIds: excludeDocumentIds,
+          sourceDocumentIds: normalizedSourceIds
+        }
+      );
+      if (existingDocsWithStaleRefs.length === 0) {
+        devLog.debug("No existing documents with stale references found", {
+          releaseId,
+          targetLanguage,
+          component: "updateBackwardReferences"
+        });
+        continue;
+      }
+      devLog.info("Found existing documents with stale references", {
+        releaseId,
+        targetLanguage,
+        count: existingDocsWithStaleRefs.length,
+        documentIds: existingDocsWithStaleRefs.map((d) => d._id),
+        component: "updateBackwardReferences"
+      }), await Promise.all(
+        existingDocsWithStaleRefs.map(async ({ _id }) => {
+          await localizeReferences({
+            client,
+            documentId: _id,
+            sourceLanguage,
+            languageFieldName
+          });
+        })
+      ), devLog.info("Updated backward references", {
+        releaseId,
+        targetLanguage,
+        updatedCount: existingDocsWithStaleRefs.length,
+        component: "updateBackwardReferences"
+      });
+    }
+  } catch (error) {
+    devLog.error("Error updating backward references", error instanceof Error ? error : new Error(String(error)), {
+      releaseId,
+      sourceDocumentIds: normalizedSourceIds,
+      targetLanguages,
+      component: "updateBackwardReferences"
+    });
+  }
 }, setupTranslationJobStatuses = (dispatch, sourceDocuments, targetLanguages, mainSourceDocumentId) => {
   for (const sourceDocument of sourceDocuments)
     for (const lang of targetLanguages) {
@@ -939,6 +1039,57 @@ const fetchTranslationPrompts = async ({
         payload
       }), mainSourceDocumentId && updateActiveTranslationJob(mainSourceDocumentId, payload);
     }
+}, emitTelemetryEvent = (config, event) => {
+  if (config?.onEvent)
+    try {
+      config.onEvent(event), devLog.debug("Telemetry event emitted", { eventName: event.name });
+    } catch (error) {
+      devLog.warn("Failed to emit telemetry event", {
+        eventName: event.name,
+        error: error instanceof Error ? error.message : String(error)
+      });
+    }
+}, emitTelemetryError = (config, bundle) => {
+  if (config?.onError)
+    try {
+      config.onError(bundle), devLog.debug("Telemetry error emitted", {
+        documentId: bundle.documentId,
+        errorType: bundle.error.type
+      });
+    } catch (error) {
+      devLog.warn("Failed to emit telemetry error", {
+        documentId: bundle.documentId,
+        error: error instanceof Error ? error.message : String(error)
+      });
+    }
+}, buildErrorBundle = (params) => {
+  const durationMs = Date.now() - params.startTime;
+  return {
+    documentId: params.documentId,
+    documentType: params.documentType,
+    targetLanguage: params.targetLanguage,
+    sourceLanguage: params.sourceLanguage,
+    translationMode: params.translationMode,
+    error: {
+      message: params.error.message,
+      stack: params.error.stack,
+      type: params.errorType
+    },
+    debug: {
+      originalDocument: params.originalDocument,
+      serializedDocument: params.serializedDocument,
+      openaiResponse: params.openaiResponse,
+      translationPrompts: params.translationPrompts,
+      validationErrors: params.validationErrors
+    },
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    durationMs
+  };
+}, createTimestamp = () => (/* @__PURE__ */ new Date()).toISOString(), classifyError = (error, context) => {
+  if (context)
+    return context;
+  const message = error.message.toLowerCase();
+  return message.includes("network") || message.includes("fetch") || message.includes("timeout") || message.includes("econnrefused") || message.includes("enotfound") ? "network" : message.includes("openai") || message.includes("gpt") || message.includes("api error") ? "openai_api" : message.includes("validation") || message.includes("structure") || message.includes("invalid") ? "validation" : message.includes("deserialize") || message.includes("parse") ? "deserialization" : message.includes("serialize") || message.includes("xml") ? "serialization" : message.includes("agent") || message.includes("sanity") ? "sanity_agent" : "unknown";
 }, updateTranslationMetadata = async ({
   client,
   targetLanguage,
@@ -1649,25 +1800,27 @@ const globalTransformRegistry = new TransformRegistry(), callGPT5 = async (apiKe
         attributes,
         children: []
       }, closingTag = `</${tagName}>`;
-      if (content.endsWith(closingTag.replace(/[<>]/g, ""))) {
-        const textContent = content.substring(0, content.lastIndexOf("<"));
-        if (node.text = unescapeXml(textContent), stack.length > 0) {
-          const parent = stack[stack.length - 1];
-          parent && parent.children.push(node);
-        } else
-          root.push(node);
-      } else if (content.includes(closingTag))
-        if (node.text = unescapeXml(content.replace(closingTag, "")), stack.length > 0) {
+      if (content.includes(closingTag)) {
+        const closeIdx = content.indexOf(closingTag);
+        node.text = unescapeXml(content.substring(0, closeIdx));
+        const remainder = content.substring(closeIdx + closingTag.length).trim();
+        if (stack.length > 0) {
           const parent = stack[stack.length - 1];
           parent && parent.children.push(node);
         } else
           root.push(node);
-      else if (attributes.type && typeof attributes.type == "string" && attributes.type.startsWith("translatable.")) {
+        remainder && (lines[i] = remainder, i--);
+      } else if (attributes.type && typeof attributes.type == "string" && attributes.type.startsWith("translatable.")) {
         const contentLines = [];
         for (i++; i < lines.length; ) {
           const currentLine = lines[i];
-          if (currentLine.trim().match(/^<\/field>$/))
+          if (currentLine.includes("</field>")) {
+            const idx = currentLine.indexOf("</field>"), before = currentLine.substring(0, idx).trimEnd();
+            before.trim() && contentLines.push(before);
+            const after = currentLine.substring(idx + 8).trim();
+            after && (lines[i] = after, i--);
             break;
+          }
           contentLines.push(currentLine), i++;
         }
         if (node.text = contentLines.join(`
@@ -1676,18 +1829,36 @@ const globalTransformRegistry = new TransformRegistry(), callGPT5 = async (apiKe
           parent && parent.children.push(node);
         } else
           root.push(node);
-      } else if (attributes.type === "string" && content && content.includes(closingTag))
-        if (node.text = unescapeXml(content.replace(closingTag, "")), stack.length > 0) {
+      } else if (attributes.type === "string" && content && !content.includes(closingTag)) {
+        const contentLines = [content];
+        for (i++; i < lines.length; ) {
+          const currentLine = lines[i];
+          if (currentLine.includes(closingTag)) {
+            const closingIndex = currentLine.indexOf(closingTag), remainingContent = currentLine.substring(0, closingIndex).trimEnd();
+            remainingContent && contentLines.push(remainingContent);
+            const after = currentLine.substring(closingIndex + closingTag.length).trim();
+            after && (lines[i] = after, i--);
+            break;
+          }
+          contentLines.push(currentLine), i++;
+        }
+        if (node.text = unescapeXml(contentLines.join(`
+`)), stack.length > 0) {
           const parent = stack[stack.length - 1];
           parent && parent.children.push(node);
         } else
           root.push(node);
-      else if (attributes.type === "string" && !content) {
+      } else if (attributes.type === "string" && !content) {
         const contentLines = [];
         for (i++; i < lines.length; ) {
           const currentLine = lines[i];
-          if (currentLine.trim() === "</field>")
+          if (currentLine.includes("</field>")) {
+            const idx = currentLine.indexOf("</field>"), before = currentLine.substring(0, idx).trimEnd();
+            before.trim() && contentLines.push(before);
+            const after = currentLine.substring(idx + 8).trim();
+            after && (lines[i] = after, i--);
             break;
+          }
           contentLines.push(currentLine), i++;
         }
         if (node.text = contentLines.join(`
@@ -1700,25 +1871,122 @@ const globalTransformRegistry = new TransformRegistry(), callGPT5 = async (apiKe
         stack.push(node);
       continue;
     }
-    if (trimmed.match(/^<\/(field|block|span)>$/) && stack.length > 0) {
-      matchedPatternCount++;
-      const node = stack.pop();
-      if (node)
-        if (stack.length > 0) {
-          const parent = stack[stack.length - 1];
-          parent && parent.children.push(node);
+    if (trimmed.match(/^<\/(field|block|span)>/)) {
+      let afterClosingTag = trimmed;
+      for (; ; ) {
+        const match = afterClosingTag.match(/^<\/(field|block|span)>/);
+        if (!match) break;
+        if (stack.length === 0) {
+          devLog.warn("Closing tag found but stack is empty", {
+            line: i,
+            tagName: match[1],
+            trimmed: afterClosingTag
+          }), afterClosingTag = afterClosingTag.substring(match[0].length).trim(), afterClosingTag = afterClosingTag.replace(/<!--[\s\S]*?-->/g, "").trim();
+          continue;
+        }
+        matchedPatternCount++, devLog.debug("Matched closing tag", {
+          line: i,
+          tagName: match[1],
+          trimmed: afterClosingTag,
+          stackLength: stack.length,
+          stackTopName: stack[stack.length - 1]?.name
+        });
+        const node = stack.pop();
+        if (node)
+          if (stack.length > 0) {
+            const parent = stack[stack.length - 1];
+            parent && parent.children.push(node);
+          } else
+            root.push(node);
+        afterClosingTag = afterClosingTag.substring(match[0].length).trim(), afterClosingTag = afterClosingTag.replace(/<!--[\s\S]*?-->/g, "").trim();
+      }
+      if (afterClosingTag) {
+        const remainingOpenMatch = afterClosingTag.match(/^<(field|block|span)([^>]*)>(.*)$/);
+        if (remainingOpenMatch) {
+          const [, tagName, attrsStr, content] = remainingOpenMatch, attributes = parseAttributes(attrsStr), remainingNode = {
+            type: tagName,
+            name: attributes.name,
+            text: content ? unescapeXml(content) : void 0,
+            attributes,
+            children: []
+          }, remainingClosingTag = `</${tagName}>`;
+          if (content.includes(remainingClosingTag)) {
+            const closeIdx = content.indexOf(remainingClosingTag);
+            remainingNode.text = unescapeXml(content.substring(0, closeIdx));
+            const remainder = content.substring(closeIdx + remainingClosingTag.length).trim();
+            if (stack.length > 0) {
+              const parent = stack[stack.length - 1];
+              parent && parent.children.push(remainingNode);
+            } else
+              root.push(remainingNode);
+            remainder && (lines[i] = remainder, i--);
+          } else if (attributes.type === "string" && content)
+            if (remainingNode.text = unescapeXml(content), stack.length > 0) {
+              const parent = stack[stack.length - 1];
+              parent && parent.children.push(remainingNode);
+            } else
+              root.push(remainingNode);
+          else if (attributes.type === "string" && !content) {
+            const contentLines = [];
+            for (i++; i < lines.length; ) {
+              const currentLine = lines[i];
+              if (currentLine.includes(`</${tagName}>`)) {
+                const idx = currentLine.indexOf(`</${tagName}>`), before = currentLine.substring(0, idx).trimEnd();
+                before.trim() && contentLines.push(before);
+                const after = currentLine.substring(idx + `</${tagName}>`.length).trim();
+                after && (lines[i] = after, i--);
+                break;
+              }
+              contentLines.push(currentLine), i++;
+            }
+            if (remainingNode.text = contentLines.join(`
+`).trim(), stack.length > 0) {
+              const parent = stack[stack.length - 1];
+              parent && parent.children.push(remainingNode);
+            } else
+              root.push(remainingNode);
+          } else
+            stack.push(remainingNode);
         } else
-          root.push(node);
+          lines[i] = afterClosingTag, i--;
+      }
       continue;
     }
+    if (trimmed.startsWith("</")) {
+      const attemptedCloseMatch = trimmed.match(/^<\/(field|block|span)>/);
+      attemptedCloseMatch ? stack.length === 0 && devLog.warn("Closing tag matched but stack is empty (unmatched closing tag)", {
+        line: i,
+        tagName: attemptedCloseMatch[1],
+        trimmed
+      }) : devLog.warn("Line starts with </ but did not match closing tag pattern", {
+        line: i,
+        trimmed,
+        stackLength: stack.length,
+        stackTopName: stack[stack.length - 1]?.name,
+        stackTopType: stack[stack.length - 1]?.type
+      });
+    }
     processedLineCount <= 20 && devLog.debug("Line did not match any pattern", {
       line: i,
       trimmed,
       startsWithLessThan: trimmed.startsWith("<"),
       startsWithField: trimmed.startsWith("<field"),
-      startsWithBacktick: trimmed.startsWith("`")
+      startsWithBacktick: trimmed.startsWith("`"),
+      startsWithClosingTag: trimmed.startsWith("</")
     });
   }
+  if (stack.length > 0)
+    for (devLog.warn("Nodes remaining in stack after parsing complete", {
+      stackLength: stack.length,
+      remainingNodes: stack.map((n) => ({
+        type: n.type,
+        name: n.name,
+        attributes: n.attributes
+      }))
+    }); stack.length > 0; ) {
+      const node = stack.pop();
+      node && root.push(node);
+    }
   return devLog.debug("Parse complete", {
     totalLines: lines.length,
     processedLines: processedLineCount,
@@ -1766,8 +2034,28 @@ const globalTransformRegistry = new TransformRegistry(), callGPT5 = async (apiKe
     return;
   }
   if (node.attributes.type === "object") {
-    for (const child of node.children)
-      child.name && applyFieldChanges(doc, [...path, child.name], child);
+    const currentValue = get(doc, path);
+    if (currentValue && typeof currentValue == "object" && !Array.isArray(currentValue)) {
+      const currentValueObj = currentValue;
+      for (const child of node.children)
+        if (child.name) {
+          const childValue = currentValueObj[child.name];
+          if (/^\d+$/.test(child.name) && childValue === void 0) {
+            devLog.warn("Skipping numeric child name in object field - field does not exist (likely parsing error)", {
+              path: path.join("."),
+              childName: child.name,
+              availableKeys: Object.keys(currentValueObj),
+              childType: child.attributes.type
+            });
+            continue;
+          }
+          applyFieldChanges(doc, [...path, child.name], child);
+        }
+    } else
+      devLog.warn("Object field type but value is not an object", {
+        path: path.join("."),
+        actualType: Array.isArray(currentValue) ? "array" : typeof currentValue
+      });
     return;
   }
   if (node.children.some((c) => c.type === "block")) {
@@ -1777,10 +2065,17 @@ const globalTransformRegistry = new TransformRegistry(), callGPT5 = async (apiKe
     });
     return;
   }
-  node.text !== void 0 && !node.attributes.readonly && (get(doc, path) !== void 0 ? set(doc, path, node.text) : devLog.debug("Skipping field not present in original document", {
-    path: path.join("."),
-    attemptedValue: node.text
-  }));
+  if (node.text !== void 0 && !node.attributes.readonly) {
+    const existingValue = get(doc, path);
+    existingValue !== void 0 && typeof existingValue == "string" ? set(doc, path, node.text) : existingValue !== void 0 ? devLog.debug("Skipping field - existing value is not a string (would corrupt structure)", {
+      path: path.join("."),
+      existingType: typeof existingValue,
+      attemptedValue: node.text?.substring(0, 50)
+    }) : devLog.debug("Skipping field not present in original document", {
+      path: path.join("."),
+      attemptedValue: node.text
+    });
+  }
 }, applyBlockChanges = (block, blockNode) => {
   if (blockNode.attributes._key && block._key !== blockNode.attributes._key) {
     devLog.warn("Block key mismatch, skipping", {
@@ -1811,7 +2106,11 @@ const globalTransformRegistry = new TransformRegistry(), callGPT5 = async (apiKe
     });
     return;
   }
-  fieldNode.text !== void 0 && !fieldNode.attributes.readonly && (fieldName in block ? block[fieldName] = fieldNode.text : devLog.debug("Skipping block field not present in original", {
+  fieldNode.text !== void 0 && !fieldNode.attributes.readonly && (fieldName in block && typeof block[fieldName] == "string" ? block[fieldName] = fieldNode.text : fieldName in block ? devLog.debug("Skipping block field - existing value is not a string (would corrupt structure)", {
+    fieldName,
+    existingType: typeof block[fieldName],
+    attemptedValue: fieldNode.text?.substring(0, 50)
+  }) : devLog.debug("Skipping block field not present in original", {
     fieldName,
     attemptedValue: fieldNode.text
   }));
@@ -1983,16 +2282,18 @@ const globalTransformRegistry = new TransformRegistry(), callGPT5 = async (apiKe
   translationPrompts,
   targetLanguage,
   openaiConfig,
-  previousError,
-  errorContext
+  previousError: _previousError,
+  errorContext,
+  telemetryConfig
 }) => {
-  const sourceLanguage = sourceDocument[languageFieldName], logContext = {
+  const startTime = Date.now(), sourceLanguage = sourceDocument[languageFieldName], logContext = {
     sourceId: sourceDocument._id,
     sourceLanguage
   };
+  let serializedDocument, openaiResponseContent;
   try {
     const sourceText = serializeDocument(sourceDocument);
-    devLog.info("Serialized document for OpenAI", {
+    serializedDocument = sourceText, devLog.info("Serialized document for OpenAI", {
       ...logContext,
       characterCount: sourceText.length,
       estimatedTokens: Math.ceil(sourceText.length / 4),
@@ -2015,7 +2316,7 @@ const globalTransformRegistry = new TransformRegistry(), callGPT5 = async (apiKe
       model: openaiConfig.model,
       reasoningEffort: openaiConfig.reasoningEffort
     });
-    devLog.info("OpenAI translation response received", {
+    openaiResponseContent = response.content, devLog.info("OpenAI translation response received", {
       ...logContext,
       tokensUsed: response.tokensUsed,
       cost: response.cost,
@@ -2053,9 +2354,35 @@ const globalTransformRegistry = new TransformRegistry(), callGPT5 = async (apiKe
     })), setJobStatus(dispatch, sourceDocument._id, targetLanguage, "translating_with_openai", {
       tokensUsed: response.tokensUsed.total,
       estimatedCost: response.cost
-    }), result;
+    }), {
+      document: result,
+      tokensUsed: response.tokensUsed.total,
+      cost: response.cost
+    };
   } catch (error) {
-    throw devLog.error("OpenAI translation failed", error instanceof Error ? error : new Error(String(error)), logContext), error;
+    const err = error instanceof Error ? error : new Error(String(error));
+    throw devLog.error("OpenAI translation failed", err, logContext), emitTelemetryError(
+      telemetryConfig,
+      buildErrorBundle({
+        documentId: sourceDocument._id,
+        documentType: sourceDocument._type,
+        targetLanguage,
+        sourceLanguage,
+        translationMode: "openai-only",
+        error: err,
+        errorType: classifyError(err, "openai_api"),
+        startTime,
+        originalDocument: sourceDocument,
+        serializedDocument,
+        openaiResponse: openaiResponseContent,
+        translationPrompts: {
+          globalPrompt: translationPrompts.globalPrompt,
+          localePrompt: translationPrompts.localeInstructions[targetLanguage]?.prompt,
+          protectedPhrases: translationPrompts.protectedPhrases,
+          glossaryTerms: translationPrompts.localeInstructions[targetLanguage]?.glossaryTerms ? [translationPrompts.localeInstructions[targetLanguage].glossaryTerms] : void 0
+        }
+      })
+    ), error;
   }
 }, buildTranslationPrompt$1 = ({
   sourceText,
@@ -2291,9 +2618,10 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
   releaseId,
   excludeFields = [],
   replaceExisting = !1,
-  mainSourceDocumentId
+  mainSourceDocumentId,
+  telemetryConfig
 }) => {
-  const safeExcludeFields = excludeFields.filter((field) => field !== languageFieldName);
+  const startTime = Date.now(), sourceLanguage = sourceDocument[languageFieldName], safeExcludeFields = excludeFields.filter((field) => field !== languageFieldName);
   excludeFields.length !== safeExcludeFields.length && devLog.warn("Language field was in excludeFields - removing it to prevent translation errors", {
     documentId: sourceDocument._id,
     languageFieldName,
@@ -2332,29 +2660,55 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
       documentId: sourceDocument._id,
       documentType: sourceDocument._type
     }), documentToTranslate = filteredDocument;
-  let translatedDoc, previousError = null;
+  let translatedDoc, translationMetrics = {}, previousError = null;
   const performTranslation = async (errorContext) => {
     switch (translationMode) {
-      case "sanity-only":
-        return setJobStatus(dispatch, sourceDocument._id, targetLanguage, "translating", void 0, mainSourceDocumentId), await getSanityAgentTranslation({
-          sourceDocument: documentToTranslate,
-          targetLanguage,
-          languageFieldName,
-          schemaId,
-          client,
-          translationPrompts
-        });
+      case "sanity-only": {
+        setJobStatus(dispatch, sourceDocument._id, targetLanguage, "translating", void 0, mainSourceDocumentId);
+        try {
+          return { document: await getSanityAgentTranslation({
+            sourceDocument: documentToTranslate,
+            targetLanguage,
+            languageFieldName,
+            schemaId,
+            client,
+            translationPrompts
+          }) };
+        } catch (error) {
+          const err = error instanceof Error ? error : new Error(String(error));
+          throw emitTelemetryError(
+            telemetryConfig,
+            buildErrorBundle({
+              documentId: sourceDocument._id,
+              documentType: sourceDocument._type,
+              targetLanguage,
+              sourceLanguage,
+              translationMode: "sanity-only",
+              error: err,
+              errorType: classifyError(err, "sanity_agent"),
+              startTime,
+              originalDocument: sourceDocument,
+              translationPrompts: {
+                globalPrompt: translationPrompts.globalPrompt,
+                localePrompt: translationPrompts.localeInstructions[targetLanguage]?.prompt,
+                protectedPhrases: translationPrompts.protectedPhrases
+              }
+            })
+          ), error;
+        }
+      }
       case "openai-only": {
         if (!openaiConfig?.enabled || !openaiConfig?.apiKey)
           throw new Error("OpenAI is not configured but openai-only mode was selected");
-        return setJobStatus(
+        setJobStatus(
           dispatch,
           sourceDocument._id,
           targetLanguage,
           "translating_with_openai",
           void 0,
           mainSourceDocumentId
-        ), await getOpenAITranslation({
+        );
+        const result = await getOpenAITranslation({
           dispatch,
           sourceDocument: documentToTranslate,
           targetLanguage,
@@ -2362,14 +2716,23 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
           translationPrompts,
           openaiConfig,
           previousError: errorContext && previousError ? previousError : void 0,
-          errorContext
+          errorContext,
+          telemetryConfig
         });
+        return result ? {
+          document: result.document,
+          tokensUsed: result.tokensUsed,
+          cost: result.cost
+        } : { document: null };
       }
       default:
         throw new Error(`Invalid translation mode: ${translationMode}`);
     }
-  };
-  if (translatedDoc = await performTranslation(), !translatedDoc)
+  }, translationResult = await performTranslation();
+  if (translatedDoc = translationResult.document, translationMetrics = {
+    tokensUsed: translationResult.tokensUsed,
+    cost: translationResult.cost
+  }, !translatedDoc)
     return null;
   let transformedResult;
   Object.keys(originalStructure).length > 0 ? (devLog.debug("Restoring field transforms after translation", {
@@ -2432,9 +2795,13 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
         targetLanguage,
         error: error instanceof Error ? error.message : String(error)
       }), previousError = error instanceof Error ? error : new Error(String(error));
-      const errorContext = `Previous translation attempt failed with Sanity validation error: ${previousError.message}. Please ensure the translated document structure exactly matches the source document structure.`;
-      if (translatedDoc = await performTranslation(errorContext), !translatedDoc)
+      const errorContext = `Previous translation attempt failed with Sanity validation error: ${previousError.message}. Please ensure the translated document structure exactly matches the source document structure.`, retryResult = await performTranslation(errorContext);
+      if (translatedDoc = retryResult.document, !translatedDoc)
         throw new Error("Translation retry failed: no document returned");
+      translationMetrics = {
+        tokensUsed: retryResult.tokensUsed,
+        cost: retryResult.cost
+      };
       let retryTransformedResult;
       Object.keys(originalStructure).length > 0 ? retryTransformedResult = restoreTransforms({
         translatedDocument: translatedDoc,
@@ -2465,11 +2832,19 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
             isRetry: !0
           }
         }
-      ), retryNewDoc;
+      ), {
+        document: retryNewDoc,
+        tokensUsed: translationMetrics.tokensUsed,
+        cost: translationMetrics.cost
+      };
     }
     throw error;
   }
-  return newDoc;
+  return {
+    document: newDoc,
+    tokensUsed: translationMetrics.tokensUsed,
+    cost: translationMetrics.cost
+  };
 }, translateDocument = async ({
   dispatch,
   client,
@@ -2484,9 +2859,10 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
   releaseId,
   excludeFields,
   replaceExisting,
-  mainSourceDocumentId
+  mainSourceDocumentId,
+  telemetryConfig
 }) => {
-  const logContext = {
+  const jobStartTime = Date.now(), logContext = {
     documentId: sourceDocument._id,
     targetLanguage,
     schemaId,
@@ -2498,7 +2874,7 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
       client,
       sourceDocument,
       sourceLanguage
-    }), existingTranslationId = getExistingTranslationId(translationMetadata, targetLanguage), newDocument = await handleTranslation({
+    }), existingTranslationId = getExistingTranslationId(translationMetadata, targetLanguage), translationResult = await handleTranslation({
       dispatch,
       client,
       schemaId,
@@ -2512,8 +2888,9 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
       releaseId,
       excludeFields,
       replaceExisting,
-      mainSourceDocumentId
-    });
+      mainSourceDocumentId,
+      telemetryConfig
+    }), newDocument = translationResult?.document;
     if (!newDocument) {
       devLog.error("Translation failed: no document returned", new Error("Translation returned null"), logContext), setJobStatus(
         dispatch,
@@ -2550,12 +2927,27 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
       targetLanguage,
       "completed",
       {
-        targetId: newDocument._id
+        targetId: newDocument._id,
+        tokensUsed: translationResult?.tokensUsed,
+        estimatedCost: translationResult?.cost
       },
       mainSourceDocumentId
     ), devLog.info("Translation completed successfully", {
       ...logContext,
       newDocumentId: newDocument._id
+    }), emitTelemetryEvent(telemetryConfig, {
+      name: "translation.job_completed",
+      timestamp: createTimestamp(),
+      data: {
+        documentId: sourceDocument._id,
+        documentType: sourceDocument._type,
+        sourceLanguage,
+        targetLanguage,
+        translationMode,
+        durationMs: Date.now() - jobStartTime,
+        tokensUsed: translationResult?.tokensUsed,
+        estimatedCost: translationResult?.cost
+      }
     }), devLog.timeEnd("translateDocument"), devLog.groupEnd(), newDocument._id;
   } catch (error) {
     const errorMessage = error instanceof Error ? error.message : String(error);
@@ -2583,9 +2975,10 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
   translationMode,
   openaiConfig,
   excludeFields,
-  releaseConfig
+  releaseConfig,
+  telemetryConfig
 }) => {
-  const logContext = {
+  const batchStartTime = Date.now(), logContext = {
     documentId: sourceDocument._id,
     documentRev: sourceDocument._rev,
     targetLanguages,
@@ -2599,7 +2992,19 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
     const sourceLanguage = sourceDocument[languageFieldName];
     if (!sourceLanguage)
       throw devLog.error("Source language not found"), new Error("Source language not found");
-    if (maxConcurrentTranslationJobs && translationSemaphore.updatePermits(maxConcurrentTranslationJobs), dispatch({
+    if (emitTelemetryEvent(telemetryConfig, {
+      name: "translation.batch_started",
+      timestamp: createTimestamp(),
+      data: {
+        documentId: sourceDocument._id,
+        documentType: sourceDocument._type,
+        sourceLanguage,
+        targetLanguages,
+        translationMode,
+        referenceCount: references.length,
+        releaseMode: releaseConfig.mode
+      }
+    }), maxConcurrentTranslationJobs && translationSemaphore.updatePermits(maxConcurrentTranslationJobs), dispatch({
       type: "SET_OVERALL_STATUS",
       payload: "translating"
     }), releaseConfig.mode === "existing" && releaseConfig.existingReleaseId)
@@ -2649,8 +3054,28 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
       sourceDocument
     });
     setupTranslationJobStatuses(dispatch, sourceDocuments, targetLanguages, sourceDocument._id);
-    const translationTasks = sourceDocumentIds.flatMap(
+    const shouldSkipConflict = (documentId, targetLanguage) => !releaseConfig.skipConflicts || releaseConfig.skipConflicts.length === 0 ? !1 : releaseConfig.skipConflicts.some(
+      (conflict) => conflict.sourceDocumentId === documentId && conflict.targetLanguage === targetLanguage
+    ), skippedCount = sourceDocumentIds.reduce((count, documentId) => count + targetLanguages.filter((lang) => shouldSkipConflict(documentId, lang)).length, 0), translationTasks = sourceDocumentIds.flatMap(
       (documentId) => targetLanguages.map(async (targetLanguage) => {
+        if (shouldSkipConflict(documentId, targetLanguage)) {
+          const docInfo = sourceDocuments.find((d) => d._id === documentId);
+          devLog.info("Skipping conflicting translation", {
+            documentId,
+            targetLanguage,
+            reason: "User chose to skip conflicts"
+          }), dispatch({
+            type: "SET_TRANSLATION_JOB_STATUS",
+            payload: {
+              _id: documentId,
+              _type: docInfo?._type,
+              language: targetLanguage,
+              status: "skipped",
+              title: docInfo?.title
+            }
+          });
+          return;
+        }
         try {
           await translationSemaphore.withPermit(async () => {
             const document = await client.withConfig({
@@ -2672,7 +3097,8 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
                 excludeFields,
                 replaceExisting: releaseConfig.replaceExisting,
                 // Pass main source document ID for active translations tracking
-                mainSourceDocumentId: sourceDocument._id
+                mainSourceDocumentId: sourceDocument._id,
+                telemetryConfig
               });
               versionedTargetDocumentId && versionedTargetDocumentIds.push(versionedTargetDocumentId);
             }
@@ -2689,13 +3115,28 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
           );
         }
       })
-    ), results = await Promise.allSettled(translationTasks), succeeded = results.filter((r) => r.status === "fulfilled").length, failed = results.filter((r) => r.status === "rejected").length;
+    ), results = await Promise.allSettled(translationTasks), succeeded = results.filter((r) => r.status === "fulfilled").length - skippedCount, failed = results.filter((r) => r.status === "rejected").length;
     devLog.info("Translation tasks completed", {
       ...logContext,
       total: results.length,
       succeeded,
       failed,
+      skipped: skippedCount,
       targetDocuments: versionedTargetDocumentIds.length
+    }), emitTelemetryEvent(telemetryConfig, {
+      name: "translation.batch_completed",
+      timestamp: createTimestamp(),
+      data: {
+        documentId: sourceDocument._id,
+        documentType: sourceDocument._type,
+        sourceLanguage,
+        targetLanguages,
+        translationMode,
+        succeeded,
+        failed,
+        skipped: skippedCount,
+        durationMs: Date.now() - batchStartTime
+      }
     }), dispatch({
       type: "SET_OVERALL_STATUS",
       payload: "linking_references"
@@ -2708,7 +3149,15 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
           languageFieldName
         });
       })
-    );
+    ), releaseConfig.mode === "existing" && releaseId && await updateBackwardReferences({
+      client,
+      releaseId,
+      sourceDocumentIds,
+      targetLanguages,
+      sourceLanguage,
+      languageFieldName,
+      excludeDocumentIds: versionedTargetDocumentIds
+    });
     const hasAnyFailures = failed > 0;
     hasAnyFailures && succeeded === 0 ? (devLog.error("All translation tasks failed", void 0, logContext), dispatch({ type: "SET_OVERALL_STATUS", payload: "error" }), updateActiveTranslationStatus(sourceDocument._id, "error"), cleanupActiveTranslation(sourceDocument._id)) : hasAnyFailures ? (devLog.warn("Translation completed with some failures", {
       ...logContext,
@@ -2735,8 +3184,14 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
       }
     throw devLog.timeEnd("translateDocumentSet"), devLog.groupEnd(), dispatch({ type: "SET_OVERALL_STATUS", payload: "error" }), updateActiveTranslationStatus(sourceDocument._id, "error"), cleanupActiveTranslation(sourceDocument._id), error;
   }
-}, ReleaseConflictWarning = ({ conflicts, onCancel, onReplace }) => {
-  const uniqueDocuments = useMemo(() => new Set(conflicts.map((c) => c.sourceDocumentId)).size, [conflicts]), summaryText = useMemo(() => conflicts.length === 1 ? "1 translation" : uniqueDocuments === 1 ? `${conflicts.length} translations` : `${conflicts.length} translations across ${uniqueDocuments} documents`, [conflicts.length, uniqueDocuments]);
+}, ReleaseConflictWarning = ({
+  conflicts,
+  totalTranslations,
+  onCancel,
+  onReplace,
+  onSkipConflicts
+}) => {
+  const uniqueDocuments = useMemo(() => new Set(conflicts.map((c) => c.sourceDocumentId)).size, [conflicts]), nonConflictingCount = totalTranslations - conflicts.length, hasNonConflicting = nonConflictingCount > 0, summaryText = useMemo(() => conflicts.length === 1 ? "1 translation" : uniqueDocuments === 1 ? `${conflicts.length} translations` : `${conflicts.length} translations across ${uniqueDocuments} documents`, [conflicts.length, uniqueDocuments]);
   return /* @__PURE__ */ jsx(Card, { tone: "caution", padding: 4, border: !0, radius: 2, children: /* @__PURE__ */ jsxs(Stack, { space: 4, children: [
     /* @__PURE__ */ jsxs(Flex, { align: "center", gap: 2, children: [
       /* @__PURE__ */ jsx(Text, { size: 2, children: /* @__PURE__ */ jsx(WarningOutlineIcon, {}) }),
@@ -2760,13 +3215,34 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
         " \u2014 Go back and select a different release, or create a new one."
       ] }),
       /* @__PURE__ */ jsxs(Text, { size: 1, children: [
-        /* @__PURE__ */ jsx("strong", { children: "Replace" }),
+        /* @__PURE__ */ jsx("strong", { children: "Replace All" }),
         " \u2014 Delete the existing translations in this release and create new ones."
+      ] }),
+      /* @__PURE__ */ jsxs(Text, { size: 1, children: [
+        /* @__PURE__ */ jsx("strong", { children: "Skip Conflicts" }),
+        " \u2014 Translate only the ",
+        nonConflictingCount,
+        " non-conflicting translation",
+        nonConflictingCount !== 1 ? "s" : "",
+        ", leaving existing ones unchanged.",
+        !hasNonConflicting && " (All translations have conflicts)"
       ] })
     ] }),
-    /* @__PURE__ */ jsxs(Flex, { gap: 2, justify: "flex-end", children: [
+    /* @__PURE__ */ jsxs(Flex, { gap: 2, justify: "space-between", children: [
       /* @__PURE__ */ jsx(Button, { mode: "ghost", text: "Cancel", onClick: onCancel }),
-      /* @__PURE__ */ jsx(Button, { mode: "ghost", tone: "caution", text: "Replace Existing", onClick: onReplace })
+      /* @__PURE__ */ jsxs(Flex, { gap: 2, justify: "flex-end", children: [
+        /* @__PURE__ */ jsx(Button, { mode: "bleed", tone: "caution", text: "Replace All", onClick: onReplace }),
+        /* @__PURE__ */ jsx(
+          Button,
+          {
+            mode: "ghost",
+            tone: "caution",
+            text: "Skip Conflicts",
+            onClick: onSkipConflicts,
+            disabled: !hasNonConflicting
+          }
+        )
+      ] })
     ] })
   ] }) });
 }, ActionButtonBar = ({ setIsDialogOpen }) => {
@@ -2780,12 +3256,12 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
     selectedTargetLanguages,
     translationMode,
     releaseConfig
-  } = useTranslationContext(), client = useClient({ apiVersion: "vX" }), [conflictContext, setConflictContext] = useState(null), [isCheckingConflicts, setIsCheckingConflicts] = useState(!1), filteredReferences = references.filter((ref) => selectedReferenceIds.has(ref._id));
+  } = useTranslationContext(), client = useClient({ apiVersion: "vX" }), [conflictContext, setConflictContext] = useState(null), [isCheckingConflicts, setIsCheckingConflicts] = useState(!1), filteredReferences = references.filter((ref) => selectedReferenceIds.has(ref._id)), totalTranslations = useMemo(() => (1 + filteredReferences.length) * selectedTargetLanguages.length, [filteredReferences.length, selectedTargetLanguages.length]);
   useEffect(() => {
     releaseConfig.mode === "new" && conflictContext && setConflictContext(null);
   }, [releaseConfig.mode, conflictContext]);
   const startTranslation = useCallback(
-    (replaceExisting, overrideReleaseId) => {
+    (replaceExisting, overrideReleaseId, skipConflicts) => {
       setConflictContext(null), translateDocumentSet({
         sourceDocument: document,
         targetLanguages: selectedTargetLanguages,
@@ -2802,6 +3278,7 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
         releaseConfig: {
           ...releaseConfig,
           replaceExisting,
+          skipConflicts,
           // Use the override release ID if provided (from conflict context),
           // otherwise use the current releaseConfig value
           existingReleaseId: overrideReleaseId ?? releaseConfig.existingReleaseId
@@ -2848,10 +3325,20 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
       }
     }
     startTranslation(!1);
-  }, [releaseConfig, client, document, selectedTargetLanguages, config.languageFieldName, startTranslation, filteredReferences]), handleCancelConflict = useCallback(() => {
+  }, [
+    releaseConfig,
+    client,
+    document,
+    selectedTargetLanguages,
+    config.languageFieldName,
+    startTranslation,
+    filteredReferences
+  ]), handleCancelConflict = useCallback(() => {
     setConflictContext(null);
   }, []), handleReplaceConflict = useCallback(() => {
     conflictContext && startTranslation(!0, conflictContext.releaseId);
+  }, [startTranslation, conflictContext]), handleSkipConflicts = useCallback(() => {
+    conflictContext && startTranslation(!1, conflictContext.releaseId, conflictContext.conflicts);
   }, [startTranslation, conflictContext]), handleSelectAll = useCallback(() => {
     dispatch({
       type: "SET_SELECTED_TARGET_LANGUAGES",
@@ -2867,8 +3354,10 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
     ReleaseConflictWarning,
     {
       conflicts: conflictContext.conflicts,
+      totalTranslations,
       onCancel: handleCancelConflict,
-      onReplace: handleReplaceConflict
+      onReplace: handleReplaceConflict,
+      onSkipConflicts: handleSkipConflicts
     }
   ) }) : /* @__PURE__ */ jsxs(Flex, { justify: "space-between", gap: 2, children: [
     /* @__PURE__ */ jsxs(Flex, { justify: "flex-start", gap: 2, children: [
@@ -2950,8 +3439,183 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
     documentId: document._id
   });
   return /* @__PURE__ */ jsx(Card, { padding: 4, muted: !0, border: !0, children: /* @__PURE__ */ jsx(Grid, { columns: [1, 2], gap: 3, children: config?.supportedLanguages.map((lang) => /* @__PURE__ */ jsx(LanguageCheckbox, { lang, isLoading: loading }, lang.id)) }) });
+}, reconcileReleaseReferences = async ({
+  client,
+  releaseId,
+  sourceLanguage,
+  languageFieldName,
+  onProgress
+}) => {
+  devLog.info("Starting release reference reconciliation", {
+    releaseId,
+    sourceLanguage,
+    component: "reconcileReleaseReferences"
+  });
+  try {
+    const docsInRelease = await client.fetch(
+      `*[_id match "versions." + $releaseId + ".*"] {
+        _id,
+        "language": @[$languageFieldName]
+      }`,
+      { releaseId, languageFieldName }
+    );
+    if (docsInRelease.length === 0)
+      return devLog.info("No documents found in release", {
+        releaseId,
+        component: "reconcileReleaseReferences"
+      }), { total: 0, updated: 0, errors: 0 };
+    devLog.info("Found documents in release", {
+      releaseId,
+      count: docsInRelease.length,
+      component: "reconcileReleaseReferences"
+    });
+    let updated = 0, errors = 0;
+    for (let i = 0; i < docsInRelease.length; i++) {
+      const doc = docsInRelease[i];
+      onProgress && onProgress(i + 1, docsInRelease.length);
+      try {
+        if (!doc.language) {
+          devLog.warn("Document missing language field, skipping", {
+            documentId: doc._id,
+            component: "reconcileReleaseReferences"
+          });
+          continue;
+        }
+        await localizeReferences({
+          client,
+          documentId: doc._id,
+          sourceLanguage,
+          languageFieldName
+        }), updated++;
+      } catch (error) {
+        errors++, devLog.error(
+          "Failed to reconcile references for document",
+          error instanceof Error ? error : new Error(String(error)),
+          {
+            documentId: doc._id,
+            component: "reconcileReleaseReferences"
+          }
+        );
+      }
+    }
+    const result = {
+      total: docsInRelease.length,
+      updated,
+      errors
+    };
+    return devLog.info("Release reference reconciliation complete", {
+      releaseId,
+      ...result,
+      component: "reconcileReleaseReferences"
+    }), result;
+  } catch (error) {
+    throw devLog.error("Failed to reconcile release references", error instanceof Error ? error : new Error(String(error)), {
+      releaseId,
+      component: "reconcileReleaseReferences"
+    }), error;
+  }
+}, ReconcileReferencesButton = ({ sourceLanguage }) => {
+  const { releaseConfig, overallStatus, config } = useTranslationContext(), client = useClient({ apiVersion: "vX" }), [documentCount, setDocumentCount] = useState(null), [isLoadingCount, setIsLoadingCount] = useState(!1), [reconcilingStatus, setReconcilingStatus] = useState("idle"), [reconciliationProgress, setReconciliationProgress] = useState(
+    void 0
+  ), releaseId = releaseConfig.existingReleaseId, languageFieldName = config?.languageFieldName ?? "language";
+  useEffect(() => {
+    if (!releaseId || releaseConfig.mode !== "existing") {
+      setDocumentCount(null);
+      return;
+    }
+    (async () => {
+      setIsLoadingCount(!0);
+      try {
+        const count = await client.fetch('count(*[_id match "versions." + $releaseId + ".*"])', { releaseId });
+        setDocumentCount(count), devLog.debug("Fetched release document count", {
+          releaseId,
+          count,
+          component: "ReconcileReferencesButton"
+        });
+      } catch (error) {
+        devLog.error(
+          "Failed to fetch release document count",
+          error instanceof Error ? error : new Error(String(error)),
+          {
+            releaseId,
+            component: "ReconcileReferencesButton"
+          }
+        ), setDocumentCount(null);
+      } finally {
+        setIsLoadingCount(!1);
+      }
+    })();
+  }, [releaseId, releaseConfig.mode, client]);
+  const handleReconcile = useCallback(async () => {
+    if (releaseId) {
+      devLog.info("Starting reference reconciliation", {
+        releaseId,
+        sourceLanguage,
+        component: "ReconcileReferencesButton"
+      }), setReconcilingStatus("reconciling");
+      try {
+        const result = await reconcileReleaseReferences({
+          client,
+          releaseId,
+          sourceLanguage,
+          languageFieldName,
+          onProgress: (current, total) => {
+            setReconciliationProgress({ current, total });
+          }
+        });
+        devLog.info("Reference reconciliation completed", {
+          releaseId,
+          ...result,
+          component: "ReconcileReferencesButton"
+        }), setReconcilingStatus("completed"), setTimeout(() => {
+          setReconcilingStatus("idle"), setReconciliationProgress(void 0);
+        }, 2e3);
+      } catch (error) {
+        devLog.error("Reference reconciliation failed", error instanceof Error ? error : new Error(String(error)), {
+          releaseId,
+          component: "ReconcileReferencesButton"
+        }), setReconcilingStatus("error"), setReconciliationProgress(void 0);
+      }
+    }
+  }, [releaseId, sourceLanguage, languageFieldName, client]);
+  if (releaseConfig.mode !== "existing" || !releaseId)
+    return null;
+  const isTranslating = overallStatus === "translating" || overallStatus === "linking_references", isReconciling = reconcilingStatus === "reconciling";
+  return /* @__PURE__ */ jsx(Card, { padding: 3, border: !0, radius: 2, tone: reconcilingStatus === "error" ? "critical" : "default", children: /* @__PURE__ */ jsxs(Stack, { space: 3, children: [
+    /* @__PURE__ */ jsxs(Flex, { align: "center", justify: "space-between", gap: 3, children: [
+      /* @__PURE__ */ jsxs(Stack, { space: 2, children: [
+        /* @__PURE__ */ jsx(Text, { size: 1, weight: "medium", children: "Reconcile References" }),
+        /* @__PURE__ */ jsx(Text, { size: 1, muted: !0, children: isLoadingCount ? "Loading..." : documentCount === null ? "Unable to load document count" : documentCount === 0 ? "No documents in release" : /* @__PURE__ */ jsxs(Fragment, { children: [
+          documentCount,
+          " document",
+          documentCount !== 1 ? "s" : "",
+          " in release"
+        ] }) })
+      ] }),
+      /* @__PURE__ */ jsx(
+        Button,
+        {
+          icon: isReconciling ? Spinner : SyncIcon,
+          text: reconcilingStatus === "completed" ? "Done!" : reconcilingStatus === "error" ? "Retry" : isReconciling ? "Reconciling..." : "Reconcile",
+          tone: reconcilingStatus === "completed" ? "positive" : reconcilingStatus === "error" ? "critical" : "default",
+          mode: "ghost",
+          onClick: handleReconcile,
+          disabled: (isTranslating || isReconciling || isLoadingCount || documentCount === 0) && reconcilingStatus !== "error"
+        }
+      )
+    ] }),
+    isReconciling && reconciliationProgress && /* @__PURE__ */ jsx(Flex, { align: "center", gap: 2, children: /* @__PURE__ */ jsxs(Text, { size: 1, muted: !0, children: [
+      "Processing ",
+      reconciliationProgress.current,
+      " of ",
+      reconciliationProgress.total,
+      "..."
+    ] }) }),
+    reconcilingStatus === "error" && /* @__PURE__ */ jsx(Text, { size: 1, muted: !0, children: "Reconciliation failed. Click Retry to try again." }),
+    reconcilingStatus === "idle" && documentCount !== null && documentCount > 0 && /* @__PURE__ */ jsx(Text, { size: 1, muted: !0, children: "Updates all document references to point to their translated versions in this release." })
+  ] }) });
 }, ReleaseSelectionPanel = () => {
-  const { dispatch, releaseConfig } = useTranslationContext(), client = useClient({ apiVersion: "vX" }), [releases, setReleases] = useState([]), [isLoading, setIsLoading] = useState(!1), [error, setError] = useState(null), [searchQuery, setSearchQuery] = useState("");
+  const { dispatch, releaseConfig, document, config } = useTranslationContext(), client = useClient({ apiVersion: "vX" }), languageFieldName = config?.languageFieldName ?? "language", sourceLanguage = document?.[languageFieldName], [releases, setReleases] = useState([]), [isLoading, setIsLoading] = useState(!1), [error, setError] = useState(null), [searchQuery, setSearchQuery] = useState(""), [showReconcileUI, setShowReconcileUI] = useState(!1);
   useEffect(() => {
     (async () => {
       setIsLoading(!0), setError(null);
@@ -3064,12 +3728,33 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
               radius: 2,
               tone: isSelected ? "primary" : "default",
               style: { cursor: "pointer" },
-              onClick: () => handleSelectRelease(releaseName),
+              onClick: () => {
+                handleSelectRelease(releaseName), isSelected || setShowReconcileUI(!1);
+              },
               border: !0,
               muted: isSelected,
               children: /* @__PURE__ */ jsxs(Flex, { direction: "column", gap: 3, children: [
-                /* @__PURE__ */ jsx(Text, { size: 1, children: release.metadata.title }),
-                /* @__PURE__ */ jsx(Text, { size: 1, muted: !0, children: formatDate(release._createdAt) })
+                /* @__PURE__ */ jsxs(Flex, { justify: "space-between", align: "center", children: [
+                  /* @__PURE__ */ jsxs(Flex, { direction: "column", gap: 2, children: [
+                    /* @__PURE__ */ jsx(Text, { size: 1, children: release.metadata.title }),
+                    /* @__PURE__ */ jsx(Text, { size: 1, muted: !0, children: formatDate(release._createdAt) })
+                  ] }),
+                  isSelected && sourceLanguage && /* @__PURE__ */ jsx(
+                    Button,
+                    {
+                      icon: SyncIcon,
+                      text: showReconcileUI ? "Hide" : "Reconcile References",
+                      mode: "bleed",
+                      tone: "primary",
+                      fontSize: 0,
+                      padding: 2,
+                      onClick: (e) => {
+                        e.stopPropagation(), setShowReconcileUI(!showReconcileUI);
+                      }
+                    }
+                  )
+                ] }),
+                isSelected && sourceLanguage && showReconcileUI && /* @__PURE__ */ jsx(ReconcileReferencesButton, { sourceLanguage })
               ] })
             },
             release._id
@@ -3296,13 +3981,7 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
     /* @__PURE__ */ jsx(Box, { style: { maxHeight: "400px", overflowY: "auto" }, children: /* @__PURE__ */ jsx(Stack, { space: 2, children: filteredReferences.length === 0 ? /* @__PURE__ */ jsx(Text, { size: 1, muted: !0, children: "No references match the selected filter." }) : filteredReferences.map((reference) => {
       const isSelected = selectedReferenceIds.has(reference._id), displayTitle = reference.title || reference._id;
       return /* @__PURE__ */ jsx(Card, { padding: 3, border: !0, radius: 2, children: /* @__PURE__ */ jsxs(Flex, { align: "center", gap: 3, children: [
-        /* @__PURE__ */ jsx(
-          Checkbox,
-          {
-            checked: isSelected,
-            onChange: () => handleToggleReference(reference._id)
-          }
-        ),
+        /* @__PURE__ */ jsx(Checkbox, { checked: isSelected, onChange: () => handleToggleReference(reference._id) }),
         /* @__PURE__ */ jsxs(Flex, { flex: 1, align: "center", gap: 2, children: [
           /* @__PURE__ */ jsx(Text, { size: 1, children: displayTitle }),
           /* @__PURE__ */ jsx(Badge, { tone: "primary", fontSize: 0, children: reference._type })
@@ -3311,15 +3990,7 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
     }) }) })
   ] }) });
 }, ReferenceConfigPanel = () => {
-  const {
-    dispatch,
-    document,
-    shouldTranslateReferences,
-    maxReferenceDepth,
-    config,
-    references,
-    selectedReferenceIds
-  } = useTranslationContext(), client = useClient({ apiVersion: "vX" }), [isLoadingReferences, setIsLoadingReferences] = useState(!1), [showSelectionPanel, setShowSelectionPanel] = useState(!1), maxDepth = config.maxReferenceDepth || 3;
+  const { dispatch, document, shouldTranslateReferences, maxReferenceDepth, config, references, selectedReferenceIds } = useTranslationContext(), client = useClient({ apiVersion: "vX" }), [isLoadingReferences, setIsLoadingReferences] = useState(!1), [showSelectionPanel, setShowSelectionPanel] = useState(!1), maxDepth = config.maxReferenceDepth || 3;
   useEffect(() => {
     (async () => {
       if (setIsLoadingReferences(!0), !shouldTranslateReferences) {