@braze/sanity-plugin-ai-translation 0.2.3 → 0.2.4

package/dist/index.js

@@ -1409,11 +1409,21 @@ const fetchTranslationPrompts = async ({
   const sourceDocumentString = documentToPlainText(sourceDocument), translationSettings2 = await client.fetch(
     `*[_id == "translation-settings"][0] {
       globalPrompt,
-      localePrompts[locale in $targetLanguages],
+      localePrompts[_key in $targetLanguages],
       protectedPhrases
     }`,
     { targetLanguages }
-  ), translationGlossaryTerms = await client.fetch(
+  );
+  devLog.debug("Fetched translation settings", {
+    hasSettings: !!translationSettings2,
+    hasGlobalPrompt: !!translationSettings2?.globalPrompt,
+    globalPromptLength: translationSettings2?.globalPrompt?.length,
+    localePromptsCount: translationSettings2?.localePrompts?.length,
+    localePrompts: translationSettings2?.localePrompts,
+    protectedPhrasesCount: translationSettings2?.protectedPhrases?.length,
+    targetLanguages
+  });
+  const translationGlossaryTerms = await client.fetch(
     `*[
         _type == "translationGlossaryTerm"
         && count(translations[_key in $targetLanguages]) > 0
@@ -1433,9 +1443,21 @@ const fetchTranslationPrompts = async ({
     )), glossaryTermsByLocale[targetLanguage] = relevantTranslations;
   }
   let filteredProtectedPhrases = translationSettings2?.protectedPhrases;
-  return sourceDocument && filteredProtectedPhrases && (filteredProtectedPhrases = filteredProtectedPhrases.filter(
-    (phrase) => protectedPhraseAppearsInDocument(phrase, sourceDocumentString)
-  )), {
+  return sourceDocument && filteredProtectedPhrases && (devLog.debug("Filtering protected phrases", {
+    totalPhrases: filteredProtectedPhrases.length,
+    phrases: filteredProtectedPhrases,
+    sourceDocumentStringLength: sourceDocumentString.length,
+    sourceDocumentPreview: sourceDocumentString.substring(0, 500)
+  }), filteredProtectedPhrases = filteredProtectedPhrases.filter((phrase) => {
+    const appears = protectedPhraseAppearsInDocument(phrase, sourceDocumentString);
+    return devLog.debug("Protected phrase match result", {
+      phrase,
+      appears
+    }), appears;
+  }), devLog.debug("Filtered protected phrases result", {
+    remainingCount: filteredProtectedPhrases.length,
+    remainingPhrases: filteredProtectedPhrases
+  })), {
     globalPrompt: translationSettings2?.globalPrompt,
     protectedPhrases: filteredProtectedPhrases,
     localeInstructions: Object.fromEntries(
@@ -1583,7 +1605,109 @@ const fetchTranslationPrompts = async ({
         payload
       });
     }
-}, getExistingTranslationId = (translationMetadata, targetLanguage) => translationMetadata?.translations?.length && translationMetadata.translations.find(
+}, DEFAULT_OPTIONS = {
+  maxRetries: 3,
+  initialDelayMs: 1e3,
+  maxDelayMs: 3e4,
+  backoffMultiplier: 2,
+  jitter: !0
+};
+function isRetryableError(error) {
+  if (error instanceof Error) {
+    const message = error.message.toLowerCase(), name = error.name.toLowerCase(), nonRetryablePatterns = [
+      "schema not found",
+      "invalid schema",
+      "not found",
+      "unauthorized",
+      "forbidden",
+      "invalid api key",
+      "missing api key",
+      "validation failed",
+      "invalid document",
+      "source language not found",
+      "invalid configuration",
+      "type mismatch"
+    ];
+    for (const pattern of nonRetryablePatterns)
+      if (message.includes(pattern) || name.includes(pattern))
+        return !1;
+    const retryablePatterns = [
+      "failed to fetch",
+      "network",
+      "timeout",
+      "econnreset",
+      "econnrefused",
+      "enotfound",
+      "socket",
+      "rate limit",
+      "too many requests",
+      "429",
+      "500",
+      "502",
+      "503",
+      "504",
+      "internal server error",
+      "bad gateway",
+      "service unavailable",
+      "gateway timeout",
+      "temporarily unavailable",
+      "try again"
+    ];
+    for (const pattern of retryablePatterns)
+      if (message.includes(pattern) || name.includes(pattern))
+        return !0;
+  }
+  if (typeof error == "object" && error !== null) {
+    const statusCode = error.statusCode || error.status;
+    if (statusCode) {
+      if (statusCode === 429 || statusCode >= 500 && statusCode < 600)
+        return !0;
+      if (statusCode >= 400 && statusCode < 500)
+        return !1;
+    }
+  }
+  return !0;
+}
+function calculateBackoffDelay(attempt, options) {
+  const { initialDelayMs, maxDelayMs, backoffMultiplier, jitter } = options;
+  let delay = initialDelayMs * backoffMultiplier ** attempt;
+  if (delay = Math.min(delay, maxDelayMs), jitter) {
+    const jitterFactor = 0.75 + Math.random() * 0.5;
+    delay = Math.round(delay * jitterFactor);
+  }
+  return delay;
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function withRetry(fn, options = {}) {
+  const opts = { ...DEFAULT_OPTIONS, ...options }, shouldRetry = opts.isRetryable ?? isRetryableError;
+  let lastError, attempts = 0;
+  for (let attempt = 0; attempt <= opts.maxRetries; attempt++) {
+    attempts = attempt + 1;
+    try {
+      return { success: !0, result: await fn(), attempts };
+    } catch (error) {
+      if (lastError = error, attempt >= opts.maxRetries) {
+        devLog.debug("Max retries exhausted", { attempt: attempts, error });
+        break;
+      }
+      if (!shouldRetry(error)) {
+        devLog.debug("Error is not retryable", { attempt: attempts, error });
+        break;
+      }
+      const delay = calculateBackoffDelay(attempt, opts);
+      devLog.debug("Scheduling retry", {
+        attempt: attempts,
+        nextAttempt: attempt + 2,
+        delayMs: delay,
+        error: error instanceof Error ? error.message : String(error)
+      }), opts.onRetry && opts.onRetry(attempt + 1, error, delay), await sleep(delay);
+    }
+  }
+  return { success: !1, error: lastError, attempts };
+}
+const getExistingTranslationId = (translationMetadata, targetLanguage) => translationMetadata?.translations?.length && translationMetadata.translations.find(
   (translation) => translation._key === targetLanguage
 )?.value._ref || null, getTranslationMetadata = async ({
   client,
@@ -1675,6 +1799,146 @@ const fetchTranslationPrompts = async ({
     })
   });
 };
+function shouldExcludeField(fieldPath, excludeFields) {
+  for (const pattern of excludeFields) {
+    if (fieldPath === pattern)
+      return !0;
+    if (pattern.startsWith("**.")) {
+      const fieldName = pattern.substring(3), segments = fieldPath.split(".");
+      if (segments[segments.length - 1]?.split("[")[0] === fieldName)
+        return !0;
+    } else if (!pattern.includes(".") && !pattern.includes("[")) {
+      const segments = fieldPath.split(".");
+      if (segments[segments.length - 1]?.split("[")[0] === pattern)
+        return !0;
+    } else if (pattern.includes("[*]")) {
+      const regexPattern = pattern.replace(/\[/g, "\\[").replace(/\]/g, "\\]").replace(/\\\[\*\\\]/g, "\\[\\d+\\]");
+      if (new RegExp(`^${regexPattern}$`).test(fieldPath))
+        return !0;
+    }
+  }
+  return !1;
+}
+function filterExcludedFields(document, excludeFields = [], currentPath = "") {
+  if (!excludeFields.length)
+    return {
+      filteredDocument: document,
+      excludedValues: {}
+    };
+  const filteredDocument = {}, excludedValues = {};
+  let hasExclusions = !1;
+  for (const [key, value] of Object.entries(document)) {
+    const fieldPath = currentPath ? `${currentPath}.${key}` : key;
+    if (shouldExcludeField(fieldPath, excludeFields)) {
+      excludedValues[fieldPath] = value, hasExclusions = !0, devLog.debug("Excluding field from translation", {
+        fieldPath,
+        fieldType: typeof value,
+        value: typeof value == "string" ? value : "[object]"
+      });
+      continue;
+    }
+    if (value && typeof value == "object" && !Array.isArray(value) && value._type !== "reference") {
+      const nested = filterExcludedFields(value, excludeFields, fieldPath);
+      filteredDocument[key] = nested.filteredDocument, Object.assign(excludedValues, nested.excludedValues), Object.keys(nested.excludedValues).length > 0 && (hasExclusions = !0);
+    } else if (Array.isArray(value)) {
+      const filteredArray = [];
+      let arrayHasExclusions = !1;
+      for (let i = 0; i < value.length; i++) {
+        const arrayItem = value[i], itemPath = `${fieldPath}[${i}]`;
+        if (arrayItem && typeof arrayItem == "object" && !Array.isArray(arrayItem) && arrayItem._type !== "reference") {
+          const nested = filterExcludedFields(arrayItem, excludeFields, itemPath);
+          filteredArray[i] = nested.filteredDocument, Object.assign(excludedValues, nested.excludedValues), Object.keys(nested.excludedValues).length > 0 && (arrayHasExclusions = !0);
+        } else
+          filteredArray[i] = arrayItem;
+      }
+      filteredDocument[key] = filteredArray, arrayHasExclusions && (hasExclusions = !0);
+    } else
+      filteredDocument[key] = value;
+  }
+  return hasExclusions && devLog.info("Filtered excluded fields from document", {
+    documentId: document._id || "unknown",
+    excludedFieldCount: Object.keys(excludedValues).length,
+    excludedFields: Object.keys(excludedValues)
+  }), {
+    filteredDocument,
+    excludedValues
+  };
+}
+function restoreExcludedFields(translatedDocument, excludedValues) {
+  if (!Object.keys(excludedValues).length)
+    return translatedDocument;
+  const result = { ...translatedDocument };
+  for (const [fieldPath, value] of Object.entries(excludedValues))
+    setNestedValue(result, fieldPath, value);
+  return devLog.debug("Restored excluded fields to translated document", {
+    documentId: result._id || "unknown",
+    restoredFieldCount: Object.keys(excludedValues).length,
+    restoredFields: Object.keys(excludedValues)
+  }), result;
+}
+function setNestedValue(obj, path, value) {
+  const segments = path.split(".");
+  let current = obj;
+  for (let i = 0; i < segments.length - 1; i++) {
+    const segment = segments[i], arrayMatch2 = segment.match(/^(.+)\[(\d+)\]$/);
+    if (arrayMatch2) {
+      const [, fieldName, indexStr] = arrayMatch2, index = Number.parseInt(indexStr, 10);
+      for ((!(fieldName in current) || !Array.isArray(current[fieldName])) && (current[fieldName] = []); current[fieldName].length <= index; )
+        current[fieldName].push({});
+      current = current[fieldName][index];
+    } else
+      (!(segment in current) || typeof current[segment] != "object") && (current[segment] = {}), current = current[segment];
+  }
+  const finalSegment = segments[segments.length - 1], arrayMatch = finalSegment.match(/^(.+)\[(\d+)\]$/);
+  if (arrayMatch) {
+    const [, fieldName, indexStr] = arrayMatch, index = Number.parseInt(indexStr, 10);
+    for ((!(fieldName in current) || !Array.isArray(current[fieldName])) && (current[fieldName] = []); current[fieldName].length <= index; )
+      current[fieldName].push(null);
+    current[fieldName][index] = value;
+  } else
+    current[finalSegment] = value;
+}
+const COMMON_ENUM_FIELDS = [
+  "status",
+  "state",
+  "type",
+  "category",
+  "priority",
+  "visibility",
+  "role",
+  "permission",
+  "level",
+  "mode",
+  "format",
+  "variant",
+  "size",
+  "theme",
+  "kind",
+  "phase",
+  "stage"
+], PREDEFINED_EXCLUSIONS = {
+  /** Common enum and status fields */
+  enums: [...COMMON_ENUM_FIELDS],
+  /** All metadata and system fields (starting with _) */
+  metadata: ["_id", "_type", "_rev", "_createdAt", "_updatedAt"],
+  /** Common technical and configuration fields */
+  technical: [
+    "slug",
+    "handle",
+    "key",
+    "code",
+    "id",
+    "uuid",
+    "token",
+    "hash",
+    "checksum",
+    "version",
+    "config",
+    "settings"
+  ],
+  /** SEO and URL-related fields that often shouldn't be translated */
+  seo: ["slug", "handle", "permalink", "canonical", "redirect", "robots", "sitemap"]
+};
 function applyTransforms({
   document,
   registry,
@@ -1837,9 +2101,10 @@ class TransformRegistry {
     }), matches[0];
   }
 }
-const globalTransformRegistry = new TransformRegistry(), callGPT5 = async (apiKey, request) => (request.model || "gpt-5") === "gpt-5" ? await callGPT5ResponsesAPI(apiKey, request) : await callChatCompletionsAPI(apiKey, request), callGPT5ResponsesAPI = async (apiKey, request) => {
+const globalTransformRegistry = new TransformRegistry(), callGPT5 = async (apiKey, request) => (request.model || "gpt-5").startsWith("gpt-5") ? await callGPT5ResponsesAPI(apiKey, request) : await callChatCompletionsAPI(apiKey, request), callGPT5ResponsesAPI = async (apiKey, request) => {
   const model = request.model || "gpt-5", requestBody = {
-    model: "gpt-5.1",
+    model: model === "gpt-5" ? "gpt-5.1" : model,
+    // Map gpt-5 to gpt-5.1, use others as-is
     input: request.messages
     // Uses 'input' instead of 'messages'
   };
@@ -1847,6 +2112,16 @@ const globalTransformRegistry = new TransformRegistry(), callGPT5 = async (apiKe
     effort: request.reasoningEffort,
     summary: "auto"
     // Enable automatic reasoning summaries
+  }), devLog.debug("OpenAI GPT-5 Request", {
+    model: requestBody.model,
+    reasoningEffort: request.reasoningEffort,
+    messages: request.messages.map((m) => ({
+      role: m.role,
+      contentLength: m.content.length,
+      contentPreview: m.content.substring(0, 500) + (m.content.length > 500 ? "..." : "")
+    }))
+  }), devLog.debug("OpenAI GPT-5 Full Prompt", {
+    messages: request.messages
   });
   const response = await fetch("https://api.openai.com/v1/responses", {
     method: "POST",
@@ -1864,7 +2139,8 @@ const globalTransformRegistry = new TransformRegistry(), callGPT5 = async (apiKe
     prompt: result.usage?.input_tokens || 0,
     completion: result.usage?.output_tokens || 0,
     reasoning: result.usage?.output_tokens_details?.reasoning_tokens || 0,
-    total: result.usage?.total_tokens || 0
+    total: result.usage?.total_tokens || 0,
+    cached: result.usage?.input_tokens_details?.cached_tokens || 0
   }, cost = calculateCost(tokensUsed, model);
   let content = "";
   if (result.output && Array.isArray(result.output)) {
@@ -1881,7 +2157,19 @@ const globalTransformRegistry = new TransformRegistry(), callGPT5 = async (apiKe
     model,
     messages: request.messages,
     temperature: request.temperature ?? 0.3
-  }, response = await fetch("https://api.openai.com/v1/chat/completions", {
+  };
+  devLog.debug("OpenAI Chat Completions Request", {
+    model,
+    temperature: request.temperature ?? 0.3,
+    messages: request.messages.map((m) => ({
+      role: m.role,
+      contentLength: m.content.length,
+      contentPreview: m.content.substring(0, 500) + (m.content.length > 500 ? "..." : "")
+    }))
+  }), devLog.debug("OpenAI Chat Completions Full Prompt", {
+    messages: request.messages
+  });
+  const response = await fetch("https://api.openai.com/v1/chat/completions", {
     method: "POST",
     headers: {
       "Content-Type": "application/json",
@@ -1897,7 +2185,8 @@ const globalTransformRegistry = new TransformRegistry(), callGPT5 = async (apiKe
     prompt: usage.prompt_tokens || 0,
     completion: usage.completion_tokens || 0,
     reasoning: usage.reasoning_tokens || 0,
-    total: usage.total_tokens || 0
+    total: usage.total_tokens || 0,
+    cached: usage.prompt_tokens_details?.cached_tokens || 0
   }, cost = calculateCost(tokensUsed, model);
   return {
     content: result.choices[0].message.content || "",
@@ -1907,27 +2196,47 @@ const globalTransformRegistry = new TransformRegistry(), callGPT5 = async (apiKe
 }, calculateCost = (tokens, model) => {
   const pricing = {
     "gpt-5": {
-      input: 2e-6,
+      input: 125e-8,
       output: 1e-5,
-      reasoning: 5e-6
+      reasoning: 0
+    },
+    "gpt-5.1": {
+      input: 125e-8,
+      output: 1e-5,
+      reasoning: 0
+    },
+    "gpt-5-mini": {
+      input: 25e-8,
+      output: 2e-6,
+      reasoning: 0
+    },
+    "gpt-5-nano": {
+      input: 50000000000000004e-24,
+      output: 40000000000000003e-23,
+      reasoning: 0
+    },
+    "gpt-5-pro": {
+      input: 15e-6,
+      output: 12e-5,
+      reasoning: 0
     },
     "gpt-4o": {
-      input: 5e-6,
-      output: 14999999999999999e-21,
+      input: 25e-7,
+      output: 1e-5,
       reasoning: 0
     },
     "gpt-4-turbo": {
       input: 1e-5,
-      output: 29999999999999997e-21,
+      output: 3e-5,
       reasoning: 0
     },
     "gpt-4": {
-      input: 29999999999999997e-21,
-      output: 59999999999999995e-21,
+      input: 3e-5,
+      output: 6e-5,
       reasoning: 0
     }
-  }, modelPricing = pricing[model] || pricing["gpt-5"];
-  return tokens.prompt * modelPricing.input + tokens.completion * modelPricing.output + tokens.reasoning * modelPricing.reasoning;
+  }, modelPricing = pricing[model] || pricing["gpt-5"], cachedInputRate = model === "gpt-5.1" ? 0.125 / 1e6 : modelPricing.input;
+  return Math.max(0, tokens.prompt - tokens.cached) * modelPricing.input + tokens.cached * cachedInputRate + tokens.completion * modelPricing.output + tokens.reasoning * modelPricing.reasoning;
 }, deserializeDocument = (originalDoc, reviewedText) => {
   const parsed = parseReviewFormat(reviewedText), result = cloneDeep(originalDoc);
   return applyTextChanges(result, parsed), result;
@@ -1943,7 +2252,7 @@ const globalTransformRegistry = new TransformRegistry(), callGPT5 = async (apiKe
         type: "field",
         name: fieldName,
         text: unescapeXml(text2),
-        attributes: {},
+        attributes: { type: "string" },
         children: []
       };
       if (stack.length > 0) {
@@ -2016,7 +2325,13 @@ const globalTransformRegistry = new TransformRegistry(), callGPT5 = async (apiKe
           parent && parent.children.push(node);
         } else
           root.push(node);
-      } else
+      } else if (attributes.type === "string" && content && content.includes(closingTag))
+        if (node.text = unescapeXml(content.replace(closingTag, "")), stack.length > 0) {
+          const parent = stack[stack.length - 1];
+          parent && parent.children.push(node);
+        } else
+          root.push(node);
+      else
         stack.push(node);
       continue;
     }
@@ -2072,7 +2387,10 @@ const globalTransformRegistry = new TransformRegistry(), callGPT5 = async (apiKe
     });
     return;
   }
-  node.text !== void 0 && !node.attributes.readonly && set(doc, path, node.text);
+  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
+  }));
 }, applyBlockChanges = (block, blockNode) => {
   if (blockNode.attributes._key && block._key !== blockNode.attributes._key) {
     devLog.warn("Block key mismatch, skipping", {
@@ -2103,7 +2421,10 @@ const globalTransformRegistry = new TransformRegistry(), callGPT5 = async (apiKe
     });
     return;
   }
-  fieldNode.text !== void 0 && !fieldNode.attributes.readonly && (block[fieldName] = fieldNode.text);
+  fieldNode.text !== void 0 && !fieldNode.attributes.readonly && (fieldName in block ? block[fieldName] = fieldNode.text : devLog.debug("Skipping block field not present in original", {
+    fieldName,
+    attemptedValue: fieldNode.text
+  }));
 }, applySpanChanges = (span, spanNode) => {
   if (spanNode.attributes._key && span._key !== spanNode.attributes._key) {
     devLog.warn("Span key mismatch, skipping", {
@@ -2148,7 +2469,7 @@ const globalTransformRegistry = new TransformRegistry(), callGPT5 = async (apiKe
       return;
     }
     if (typeof value == "string") {
-      value.length > 0 && lines.push(`${fieldName}: ${escapeXml(value)}`);
+      value.length > 0 && lines.push(`${indentStr}<field name="${fieldName}" type="string">${escapeXml(value)}</field>`);
       return;
     }
     (typeof value == "number" || typeof value == "boolean") && lines.push(`${indentStr}<field name="${fieldName}" type="${typeof value}" readonly="true">${value}</field>`);
@@ -2185,7 +2506,7 @@ const globalTransformRegistry = new TransformRegistry(), callGPT5 = async (apiKe
     return;
   }
   if (typeof value == "string" && value.length > 0) {
-    lines.push(`${indentStr}<field name="${fieldName}">${escapeXml(value)}</field>`);
+    lines.push(`${indentStr}<field name="${fieldName}" type="string">${escapeXml(value)}</field>`);
     return;
   }
   (typeof value == "number" || typeof value == "boolean") && lines.push(`${indentStr}<field name="${fieldName}" type="${typeof value}" readonly="true">${value}</field>`);
@@ -2327,7 +2648,19 @@ const globalTransformRegistry = new TransformRegistry(), callGPT5 = async (apiKe
           `Structure validation failed: ${unexpectedErrors.length} errors. First: ${unexpectedErrors[0].type} at ${unexpectedErrors[0].path.join(".")}`
         );
     }
-    return setJobStatus(dispatch, sourceDocument._id, targetLanguage, "translating_with_openai", {
+    const translationValidation = validateTranslationCompleteness(sourceDocument, result, languageFieldName);
+    return translationValidation.valid || (devLog.warn("Translation completeness warning", {
+      ...logContext,
+      skippedFields: translationValidation.skippedFields,
+      warning: "GPT-5 may have skipped some important fields"
+    }), devLog.info("Skipped field details", {
+      ...logContext,
+      skippedFields: translationValidation.skippedFields.map((field) => ({
+        path: field.path,
+        originalValue: field.originalValue,
+        translatedValue: field.translatedValue
+      }))
+    })), setJobStatus(dispatch, sourceDocument._id, targetLanguage, "translating_with_openai", {
       tokensUsed: response.tokensUsed.total,
       estimatedCost: response.cost
     }), result;
@@ -2368,12 +2701,19 @@ ${sourceText}
 
 ## Instructions
 
-1. Translate all text content into ${targetLanguage}
-2. Follow the guidelines and terminology requirements above
-3. Preserve protected phrases exactly as they appear
-4. Return the document in THE EXACT SAME FORMAT
-5. **CRITICAL**: Only modify text content between tags
-6. Never add, remove, or change any tags, attributes, or structure
+1. **TRANSLATE ALL TEXT FIELDS**: Every field marked with type="string" or containing text must be translated
+2. **DO NOT SKIP SIMPLE FIELDS**: Pay special attention to simple fields like "title", "name", "description" - these are often the most important
+3. Follow the guidelines and terminology requirements above
+4. Preserve protected phrases exactly as they appear
+5. Return the document in THE EXACT SAME FORMAT
+6. **CRITICAL**: Only modify text content between tags
+7. Never add, remove, or change any tags, attributes, or structure
+
+**Common fields that must always be translated:**
+- title, name, heading, label
+- description, caption, alt text
+- All text within <field> tags
+- All text within <span> tags
 
 If you used significant reasoning to make translation decisions, you may include a brief summary:
 <reasoning>
@@ -2381,6 +2721,43 @@ Brief summary of key translation decisions and reasoning
 </reasoning>
 
 Then return the translated document:`;
+}, validateTranslationCompleteness = (sourceDoc, translatedDoc, languageFieldName) => {
+  const skippedFields = [], checkField = (source, translated, path = []) => {
+    if (path.length > 0) {
+      const fieldName = path[path.length - 1];
+      if (fieldName.startsWith("_") || fieldName === languageFieldName)
+        return;
+    }
+    if (typeof source == "string" && typeof translated == "string") {
+      if (source.length > 0 && source === translated) {
+        const fieldName = path[path.length - 1] || "unknown";
+        (["title", "name", "heading", "label", "description", "caption", "alt"].includes(
+          fieldName
+        ) || source.length > 10) && skippedFields.push({
+          path: path.join("."),
+          originalValue: source,
+          translatedValue: translated
+        });
+      }
+      return;
+    }
+    if (source && translated && typeof source == "object" && typeof translated == "object") {
+      if (Array.isArray(source) && Array.isArray(translated)) {
+        const maxLength = Math.min(source.length, translated.length);
+        for (let i = 0; i < maxLength; i++)
+          checkField(source[i], translated[i], [...path, String(i)]);
+      } else if (!Array.isArray(source) && !Array.isArray(translated))
+        for (const key of Object.keys(source))
+          !key.startsWith("_") && key !== languageFieldName && checkField(source[key], translated[key], [
+            ...path,
+            key
+          ]);
+    }
+  };
+  return checkField(sourceDoc, translatedDoc), {
+    valid: skippedFields.length === 0,
+    skippedFields
+  };
 }, assembleLanguageSpecs = ({
   sourceDocument,
   languageFieldName,
@@ -2501,14 +2878,36 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
   translationPrompts,
   translationMode,
   openaiConfig,
-  releaseId
+  releaseId,
+  excludeFields = []
 }) => {
-  devLog.debug("Applying field transforms before translation", {
+  const 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,
+    originalExcludeFields: excludeFields,
+    safeExcludeFields
+  }), devLog.info("Filtering excluded fields before translation", {
+    documentId: sourceDocument._id,
+    documentType: sourceDocument._type,
+    excludeFields: safeExcludeFields,
+    excludeFieldsLength: safeExcludeFields?.length ?? 0,
+    sourceHasTitle: "title" in sourceDocument,
+    sourceTitleValue: sourceDocument.title
+  });
+  const { filteredDocument, excludedValues } = filterExcludedFields(sourceDocument, safeExcludeFields);
+  devLog.info("After filtering excluded fields", {
+    documentId: sourceDocument._id,
+    filteredHasTitle: "title" in filteredDocument,
+    filteredTitleValue: filteredDocument.title,
+    excludedValuesKeys: Object.keys(excludedValues),
+    excludedValues
+  }), devLog.debug("Applying field transforms before translation", {
     documentId: sourceDocument._id,
     documentType: sourceDocument._type
   });
   const { transformedDocument, originalStructure } = applyTransforms({
-    document: sourceDocument,
+    document: filteredDocument,
     registry: globalTransformRegistry,
     schemaType: sourceDocument._type
   });
@@ -2549,12 +2948,27 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
     documentId: sourceDocument._id,
     documentType: sourceDocument._type
   });
-  const finalDoc = restoreTransforms({
+  const transformedResult = restoreTransforms({
     translatedDocument: translatedDoc,
     originalStructure,
     registry: globalTransformRegistry,
     schemaType: sourceDocument._type
-  }), targetDocumentPublishedId = existingTranslationId || uuid(), targetDocumentVersionId = `versions.${releaseId}.${targetDocumentPublishedId}`, newDoc = {
+  }), excludedValuesToRestore = { ...excludedValues };
+  delete excludedValuesToRestore[languageFieldName], devLog.info("Before restoring excluded fields", {
+    documentId: sourceDocument._id,
+    excludedFieldCount: Object.keys(excludedValues).length,
+    excludedValuesKeys: Object.keys(excludedValues),
+    languageFieldExcluded: languageFieldName in excludedValues,
+    transformedResultHasTitle: "title" in transformedResult,
+    transformedResultTitle: transformedResult.title
+  });
+  const finalDoc = restoreExcludedFields(transformedResult, excludedValuesToRestore);
+  devLog.info("After restoring excluded fields", {
+    documentId: sourceDocument._id,
+    finalDocHasTitle: "title" in finalDoc,
+    finalDocTitle: finalDoc.title
+  });
+  const targetDocumentPublishedId = existingTranslationId || uuid(), targetDocumentVersionId = `versions.${releaseId}.${targetDocumentPublishedId}`, newDoc = {
     ...finalDoc,
     _id: targetDocumentVersionId
   };
@@ -2575,7 +2989,8 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
   translationPrompts,
   translationMode,
   openaiConfig,
-  releaseId
+  releaseId,
+  excludeFields
 }) => {
   const logContext = {
     documentId: sourceDocument._id,
@@ -2599,23 +3014,51 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
       });
       return;
     }
-    const existingTranslationId = getExistingTranslationId(translationMetadata, targetLanguage), newDocument = await handleTranslation({
-      dispatch,
-      client,
-      schemaId,
-      sourceDocument,
-      targetLanguage,
-      existingTranslationId,
-      languageFieldName,
-      translationPrompts,
-      translationMode,
-      openaiConfig,
-      releaseId
-    });
-    if (!newDocument) {
-      setJobStatus(dispatch, sourceDocument._id, targetLanguage, "error"), devLog.timeEnd("translateDocument"), devLog.groupEnd();
+    const existingTranslationId = getExistingTranslationId(translationMetadata, targetLanguage), translationResult = await withRetry(
+      () => handleTranslation({
+        dispatch,
+        client,
+        schemaId,
+        sourceDocument,
+        targetLanguage,
+        existingTranslationId,
+        languageFieldName,
+        translationPrompts,
+        translationMode,
+        openaiConfig,
+        releaseId,
+        excludeFields
+      }),
+      {
+        maxRetries: 3,
+        initialDelayMs: 1e3,
+        isRetryable: isRetryableError,
+        onRetry: (attempt, error, delayMs) => {
+          devLog.warn("Translation failed, scheduling retry", {
+            ...logContext,
+            attempt,
+            delayMs,
+            error: error instanceof Error ? error.message : String(error)
+          }), setJobStatus(dispatch, sourceDocument._id, targetLanguage, "retrying", {
+            retryCount: attempt,
+            errorMessage: error instanceof Error ? error.message : String(error)
+          });
+        }
+      }
+    );
+    if (!translationResult.success || !translationResult.result) {
+      const errorMessage = translationResult.error instanceof Error ? translationResult.error.message : String(translationResult.error || "Translation failed");
+      devLog.error("Translation failed after retries", translationResult.error, {
+        ...logContext,
+        attempts: translationResult.attempts
+      }), setJobStatus(dispatch, sourceDocument._id, targetLanguage, "error", {
+        errorMessage,
+        retryCount: translationResult.attempts - 1
+        // -1 because attempts includes initial try
+      }), devLog.timeEnd("translateDocument"), devLog.groupEnd();
       return;
     }
+    const newDocument = translationResult.result;
     return setJobStatus(dispatch, sourceDocument._id, targetLanguage, "updating_metadata", {
       targetId: newDocument._id
     }), await updateTranslationMetadata({
@@ -2650,7 +3093,8 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
   references = [],
   maxConcurrentTranslationJobs,
   translationMode,
-  openaiConfig
+  openaiConfig,
+  excludeFields
 }) => {
   const logContext = {
     documentId: sourceDocument._id,
@@ -2716,7 +3160,8 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
                 translationPrompts,
                 translationMode,
                 openaiConfig,
-                releaseId: releaseId2
+                releaseId: releaseId2,
+                excludeFields
               });
               versionedTargetDocumentId && versionedTargetDocumentIds.push(versionedTargetDocumentId);
             }
@@ -2789,7 +3234,8 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
       maxConcurrentTranslationJobs: config.maxConcurrentTranslationJobs,
       maxReferenceDepth: config.maxReferenceDepth,
       translationMode,
-      openaiConfig: config.openai
+      openaiConfig: config.openai,
+      excludeFields: config.excludeFields
     });
   }, [
     document,
@@ -2801,6 +3247,7 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
     config.maxConcurrentTranslationJobs,
     config.maxReferenceDepth,
     config.openai,
+    config.excludeFields,
     references,
     shouldOverwriteFreshTranslations,
     translationMode
@@ -3183,7 +3630,7 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
             /* @__PURE__ */ jsxs(Code, { size: 1, children: [
               job._type,
               " \u2014 ",
-              job._id.slice(-6)
+              job._id?.slice(-6) || "unknown"
             ] }),
             !["completed", "skipped", "error"].includes(job.status) && /* @__PURE__ */ jsx(Text, { size: 1, weight: "semibold", children: getStatusLabel(job.status) }),
             job.status === "completed" && job.tokensUsed ? /* @__PURE__ */ jsxs(Text, { size: 1, muted: !0, children: [
@@ -3195,12 +3642,17 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
             job.status === "error" && job.errorMessage ? /* @__PURE__ */ jsx(Card, { tone: "critical", padding: 2, radius: 2, children: /* @__PURE__ */ jsxs(Text, { size: 1, children: [
               "Error: ",
               job.errorMessage
+            ] }) }) : null,
+            job.status === "retrying" && job.errorMessage ? /* @__PURE__ */ jsx(Card, { tone: "caution", padding: 2, radius: 2, children: /* @__PURE__ */ jsxs(Text, { size: 1, children: [
+              "Retrying after: ",
+              job.errorMessage
             ] }) }) : null
           ] })
         ] }),
         /* @__PURE__ */ jsxs(Flex, { gap: 2, align: "center", children: [
           job.status === "skipped" ? /* @__PURE__ */ jsx(SkippedBadge, {}) : null,
-          job.status === "error" ? /* @__PURE__ */ jsx(ErrorBadge, {}) : null,
+          job.status === "error" ? /* @__PURE__ */ jsx(ErrorBadge, { retryCount: job.retryCount }) : null,
+          job.status === "retrying" ? /* @__PURE__ */ jsx(RetryingBadge, { retryCount: job.retryCount }) : null,
           job.targetId ? /* @__PURE__ */ jsx(
             TranslationOpenerButton,
             {
@@ -3280,12 +3732,25 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
     content: /* @__PURE__ */ jsx(Box, { padding: 1, children: /* @__PURE__ */ jsx(Text, { size: 1, muted: !0, children: "There was already a fresh translation for this document and language." }) }),
     children: /* @__PURE__ */ jsx(Badge, { tone: "neutral", children: "Skipped" })
   }
-), ErrorBadge = () => /* @__PURE__ */ jsx(
+), ErrorBadge = ({ retryCount }) => /* @__PURE__ */ jsx(
   Tooltip,
   {
     portal: !0,
-    content: /* @__PURE__ */ jsx(Box, { padding: 1, children: /* @__PURE__ */ jsx(Text, { size: 1, muted: !0, children: "This translation failed. Check the error message for details." }) }),
-    children: /* @__PURE__ */ jsx(Badge, { tone: "critical", children: "Failed" })
+    content: /* @__PURE__ */ jsx(Box, { padding: 1, children: /* @__PURE__ */ jsx(Text, { size: 1, muted: !0, children: retryCount && retryCount > 0 ? `This translation failed after ${retryCount} retry attempt${retryCount > 1 ? "s" : ""}.` : "This translation failed. Check the error message for details." }) }),
+    children: /* @__PURE__ */ jsxs(Badge, { tone: "critical", children: [
+      "Failed",
+      retryCount && retryCount > 0 ? ` (${retryCount} retries)` : ""
+    ] })
+  }
+), RetryingBadge = ({ retryCount }) => /* @__PURE__ */ jsx(
+  Tooltip,
+  {
+    portal: !0,
+    content: /* @__PURE__ */ jsx(Box, { padding: 1, children: /* @__PURE__ */ jsx(Text, { size: 1, muted: !0, children: "Retrying translation after a temporary failure." }) }),
+    children: /* @__PURE__ */ jsxs(Badge, { tone: "caution", children: [
+      "Retry ",
+      retryCount || 1
+    ] })
   }
 ), getStatusLabel = (status) => ({
   idle: "Idle",
@@ -3295,6 +3760,7 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
   translating_with_openai: "Translating with GPT-5...",
   reviewing_with_openai: "Reviewing translation with GPT-5...",
   updating_metadata: "Saving metadata...",
+  retrying: "Retrying...",
   error: "Error",
   skipped: "Skipped",
   completed: "Completed"
@@ -3763,7 +4229,11 @@ const aiTranslationPlugin = definePlugin((config) => (config.fieldTransforms?.le
   }
 })), translationHistorySchema = translationHistory;
 export {
+  COMMON_ENUM_FIELDS,
+  PREDEFINED_EXCLUSIONS,
   aiTranslationPlugin,
+  filterExcludedFields,
+  restoreExcludedFields,
   richTextTransform,
   translationHistorySchema,
   vttCaptionTransform