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

package/dist/index.d.ts

@@ -332,6 +332,26 @@ export declare interface PluginConfig {
    * ```
    */
   excludeFields?: string[];
+  /**
+   * Fields to completely remove from the translated document.
+   * Unlike `excludeFields` (which preserves fields with their original values),
+   * `unsetFields` strips matched fields entirely so they are absent from the output.
+   * Supports the same pattern syntax as `excludeFields`: field names (e.g., 'courseId'),
+   * 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: [
+   *   'legacyId',
+   *   { field: 'skilljarCourseId', preserveExisting: true }
+   * ]
+   * ```
+   */
+  unsetFields?: UnsetFieldEntry[];
   /**
    * Optional telemetry configuration for monitoring translation operations.
    * Provides callbacks for lightweight events and detailed error bundles.
@@ -703,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,6 +1360,22 @@ 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 { 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,
+    unsetFields: Object.keys(excludedValues)
+  }), filteredDocument;
+}
 function applyTransforms({
   document,
   registry,
@@ -2630,11 +2646,44 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
   openaiConfig,
   releaseId,
   excludeFields = [],
+  unsetFields = [],
   replaceExisting = !1,
   mainSourceDocumentId,
   telemetryConfig
 }) => {
-  const startTime = Date.now(), sourceLanguage = sourceDocument[languageFieldName], safeExcludeFields = excludeFields.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), { 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,
@@ -2645,10 +2694,10 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
     documentType: sourceDocument._type,
     excludeFields: safeExcludeFields,
     excludeFieldsLength: safeExcludeFields?.length ?? 0,
-    sourceHasTitle: "title" in sourceDocument,
-    sourceTitleValue: sourceDocument.title
+    sourceHasTitle: "title" in documentWithPreserved,
+    sourceTitleValue: documentWithPreserved.title
   });
-  const { filteredDocument, excludedValues } = filterExcludedFields(sourceDocument, safeExcludeFields);
+  const { filteredDocument, excludedValues } = filterExcludedFields(documentWithPreserved, safeExcludeFields);
   devLog.info("After filtering excluded fields", {
     documentId: sourceDocument._id,
     filteredHasTitle: "title" in filteredDocument,
@@ -2871,6 +2920,7 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
   openaiConfig,
   releaseId,
   excludeFields,
+  unsetFields,
   replaceExisting,
   mainSourceDocumentId,
   telemetryConfig
@@ -2900,6 +2950,7 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
       openaiConfig,
       releaseId,
       excludeFields,
+      unsetFields,
       replaceExisting,
       mainSourceDocumentId,
       telemetryConfig
@@ -3015,6 +3066,7 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
   translationMode,
   openaiConfig,
   excludeFields,
+  unsetFields,
   releaseConfig,
   telemetryConfig
 }) => {
@@ -3059,7 +3111,7 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
           metadata: {
             title: releaseTitle,
             description: releaseDescription,
-            releaseType: "undecided"
+            releaseType: "asap"
           }
         }),
         {
@@ -3135,6 +3187,7 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
                 openaiConfig,
                 releaseId,
                 excludeFields,
+                unsetFields,
                 replaceExisting: releaseConfig.replaceExisting,
                 // Pass main source document ID for active translations tracking
                 mainSourceDocumentId: sourceDocument._id,
@@ -3319,6 +3372,7 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
         translationMode,
         openaiConfig: config.openai,
         excludeFields: config.excludeFields,
+        unsetFields: config.unsetFields,
         releaseConfig: {
           ...releaseConfig,
           replaceExisting,
@@ -3341,6 +3395,7 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
       config.maxReferenceDepth,
       config.openai,
       config.excludeFields,
+      config.unsetFields,
       config.telemetry,
       filteredReferences,
       translationMode,