@braze/sanity-plugin-ai-translation 0.2.74 → 0.2.76

package/dist/index.d.ts

@@ -340,12 +340,18 @@ export declare interface PluginConfig {
    * nested paths (e.g., 'meta.internalId'), wildcard arrays (e.g., 'sections[*].legacyId'),
    * and hierarchical matches (e.g., '**.tmpField').
    *
+   * Each entry can be a plain string (always unset) or an object with `preserveExisting: true`
+   * to retain the field's value from the published target document during re-translation.
+   *
    * @example
    * ```typescript
-   * unsetFields: ['courseId', 'meta.internalId', 'sections[*].legacyId']
+   * unsetFields: [
+   *   'legacyId',
+   *   { field: 'skilljarCourseId', preserveExisting: true }
+   * ]
    * ```
    */
-  unsetFields?: string[];
+  unsetFields?: UnsetFieldEntry[];
   /**
    * Optional telemetry configuration for monitoring translation operations.
    * Provides callbacks for lightweight events and detailed error bundles.
@@ -717,6 +723,28 @@ declare interface TranslationJobFailedEvent extends TelemetryEventBase {
 
 declare type TranslationMode = "sanity-only" | "openai-only";
 
+/**
+ * Configuration for a field that should be unset with additional options.
+ * @public
+ */
+declare interface UnsetFieldConfig {
+  /** Field pattern to unset (same syntax as `excludeFields`) */
+  field: string;
+  /**
+   * When true, preserves the field's value from the published target document
+   * during re-translation. Has no effect on first translation (no existing target).
+   * Defaults to false.
+   */
+  preserveExisting?: boolean;
+}
+
+/**
+ * An entry in the `unsetFields` array: either a plain field pattern string
+ * or an object with additional configuration.
+ * @public
+ */
+declare type UnsetFieldEntry = string | UnsetFieldConfig;
+
 /**
  * Represents a VTT caption cue with timing and text content.
  */

package/dist/index.js

@@ -870,14 +870,11 @@ const fetchTranslationPrompts = async ({
   languageFieldName
 }) => {
   try {
-    const doc = await retryWithBackoff(
-      () => client.fetch("*[_id == $documentId][0]", { documentId }),
-      {
-        maxAttempts: 3,
-        initialDelayMs: 1e3,
-        context: { operation: "localizeReferences.fetchDocument", documentId }
-      }
-    );
+    const doc = await retryWithBackoff(() => client.fetch("*[_id == $documentId][0]", { documentId }), {
+      maxAttempts: 3,
+      initialDelayMs: 1e3,
+      context: { operation: "localizeReferences.fetchDocument", documentId }
+    });
     if (!doc) {
       devLog.error("Document not found", new Error("Document not found"), {
         documentId,
@@ -904,20 +901,19 @@ const fetchTranslationPrompts = async ({
       component: "localizeReferences"
     });
   }
-}, updateReferences = async (documentId, client, refs, sourceLanguage, targetLanguage) => {
+}, updateReferences = async (documentId, client, refs, _sourceLanguage, targetLanguage) => {
   if (!refs?.length)
     return [];
   const refIds = refs.map((r) => getPublishedId(r.value)), translations = await retryWithBackoff(
     () => client.fetch(
       `*[_type == $translationMetadataSchemaType && array::intersects(translations[].value._ref, $refIds)] {
-      "sourceId": translations[_key == $sourceLanguage][0].value._ref,
+      "allSourceRefs": translations[_key != $targetLanguage][].value._ref,
       "targetId": translations[_key == $targetLanguage][0].value._ref,
-      "targetType": translations[_key == $sourceLanguage][0].value -> _type
+      "targetType": translations[_key == $targetLanguage][0].value -> _type
     }`,
       {
         translationMetadataSchemaType: TRANSLATION_METADATA_TYPE,
         refIds,
-        sourceLanguage,
         targetLanguage
       }
     ),
@@ -928,16 +924,21 @@ const fetchTranslationPrompts = async ({
     }
   ), translationMap = /* @__PURE__ */ new Map();
   for (const t of translations)
-    t.sourceId && t.targetId && translationMap.set(t.sourceId, t.targetId);
+    if (t.targetId)
+      for (const sourceRef of t.allSourceRefs ?? [])
+        sourceRef && translationMap.set(sourceRef, { targetId: t.targetId, targetType: t.targetType });
   const patch = client.patch(documentId);
   let hasChanges = !1;
   for (const ref of refs) {
-    const sourceId = getPublishedId(ref.value), newId = translationMap.get(sourceId);
-    newId && (patch.set({ [pathToString(ref.path)]: getPublishedId(newId) }), patch.set({
+    const sourceId = getPublishedId(ref.value), match = translationMap.get(sourceId);
+    if (!match)
+      continue;
+    const newId = getPublishedId(match.targetId);
+    patch.set({ [pathToString(ref.path)]: newId }), patch.set({
       [`${pathToString(ref.path.slice(0, -1))}._strengthenOnPublish`]: {
-        type: translations.find((t) => t.targetId === getPublishedId(newId))?.targetType || void 0
+        type: match.targetType || void 0
       }
-    }), hasChanges = !0);
+    }), hasChanges = !0;
   }
   hasChanges && (await retryWithBackoff(
     async () => {
@@ -1360,10 +1361,16 @@ const COMMON_ENUM_FIELDS = [
   /** SEO and URL-related fields that often shouldn't be translated */
   seo: ["slug", "handle", "permalink", "canonical", "redirect", "robots", "sitemap"]
 };
+function normalizeUnsetFields(entries) {
+  const allFieldPatterns = [], preserveFieldPatterns = [];
+  for (const entry of entries)
+    typeof entry == "string" ? allFieldPatterns.push(entry) : (allFieldPatterns.push(entry.field), entry.preserveExisting && preserveFieldPatterns.push(entry.field));
+  return { allFieldPatterns, preserveFieldPatterns };
+}
 function unsetDocumentFields(document, unsetFields) {
   if (!unsetFields.length)
     return document;
-  const { filteredDocument, excludedValues } = filterExcludedFields(document, unsetFields);
+  const { allFieldPatterns } = normalizeUnsetFields(unsetFields), { filteredDocument, excludedValues } = filterExcludedFields(document, allFieldPatterns);
   return Object.keys(excludedValues).length > 0 && devLog.info("Unset fields from document (permanently removed)", {
     documentId: document._id || "unknown",
     unsetFieldCount: Object.keys(excludedValues).length,
@@ -2645,12 +2652,39 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
   mainSourceDocumentId,
   telemetryConfig
 }) => {
-  const startTime = Date.now(), sourceLanguage = sourceDocument[languageFieldName], safeUnsetFields = unsetFields.filter((field) => field !== languageFieldName);
+  const startTime = Date.now(), sourceLanguage = sourceDocument[languageFieldName], safeUnsetFields = unsetFields.filter((entry) => (typeof entry == "string" ? entry : entry.field) !== languageFieldName);
   unsetFields.length !== safeUnsetFields.length && devLog.warn("Language field was in unsetFields - removing it to prevent translation errors", {
     documentId: sourceDocument._id,
     languageFieldName
   });
-  const documentAfterUnset = unsetDocumentFields(sourceDocument, safeUnsetFields), safeExcludeFields = excludeFields.filter((field) => field !== languageFieldName);
+  const documentAfterUnset = unsetDocumentFields(sourceDocument, safeUnsetFields), { preserveFieldPatterns } = normalizeUnsetFields(safeUnsetFields);
+  let documentWithPreserved = documentAfterUnset;
+  if (preserveFieldPatterns.length > 0 && existingTranslationId)
+    try {
+      const publishedTarget = await client.getDocument(existingTranslationId);
+      if (publishedTarget) {
+        const { excludedValues: preserveValues } = filterExcludedFields(
+          publishedTarget,
+          preserveFieldPatterns
+        );
+        Object.keys(preserveValues).length > 0 && (documentWithPreserved = restoreExcludedFields(documentAfterUnset, preserveValues), devLog.info("Preserved fields from published target during re-translation", {
+          documentId: sourceDocument._id,
+          existingTranslationId,
+          preservedFields: Object.keys(preserveValues)
+        }));
+      } else
+        devLog.debug("Published target not found for preserveExisting fields", {
+          documentId: sourceDocument._id,
+          existingTranslationId
+        });
+    } catch (error) {
+      devLog.warn("Failed to fetch published target for preserveExisting fields", {
+        documentId: sourceDocument._id,
+        existingTranslationId,
+        error: error instanceof Error ? error.message : String(error)
+      });
+    }
+  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,
@@ -2661,10 +2695,10 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
     documentType: sourceDocument._type,
     excludeFields: safeExcludeFields,
     excludeFieldsLength: safeExcludeFields?.length ?? 0,
-    sourceHasTitle: "title" in documentAfterUnset,
-    sourceTitleValue: documentAfterUnset.title
+    sourceHasTitle: "title" in documentWithPreserved,
+    sourceTitleValue: documentWithPreserved.title
   });
-  const { filteredDocument, excludedValues } = filterExcludedFields(documentAfterUnset, safeExcludeFields);
+  const { filteredDocument, excludedValues } = filterExcludedFields(documentWithPreserved, safeExcludeFields);
   devLog.info("After filtering excluded fields", {
     documentId: sourceDocument._id,
     filteredHasTitle: "title" in filteredDocument,
@@ -3078,7 +3112,7 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
           metadata: {
             title: releaseTitle,
             description: releaseDescription,
-            releaseType: "undecided"
+            releaseType: "asap"
           }
         }),
         {