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

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

@@ -1360,10 +1360,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 +2651,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 +2694,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 +3111,7 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
           metadata: {
             title: releaseTitle,
             description: releaseDescription,
-            releaseType: "undecided"
+            releaseType: "asap"
           }
         }),
         {