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

package/dist/index.d.ts

@@ -332,6 +332,20 @@ 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').
+   *
+   * @example
+   * ```typescript
+   * unsetFields: ['courseId', 'meta.internalId', 'sections[*].legacyId']
+   * ```
+   */
+  unsetFields?: string[];
   /**
    * Optional telemetry configuration for monitoring translation operations.
    * Provides callbacks for lightweight events and detailed error bundles.

package/dist/index.js

@@ -482,8 +482,8 @@ function isNetworkError(error) {
       return response.status >= 500 || response.status === 429;
   }
   if (error instanceof Error) {
-    const message = error.message;
-    if (/\b(50[0-9]|429)\b/.test(message))
+    const message = error.message.toLowerCase();
+    if (/\b(50[0-9]|429)\b/.test(message) || message.includes("rate limit"))
       return !0;
   }
   return !1;
@@ -870,7 +870,14 @@ const fetchTranslationPrompts = async ({
   languageFieldName
 }) => {
   try {
-    const doc = await client.fetch("*[_id == $documentId][0]", { 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,
@@ -900,17 +907,24 @@ const fetchTranslationPrompts = async ({
 }, updateReferences = async (documentId, client, refs, sourceLanguage, targetLanguage) => {
   if (!refs?.length)
     return [];
-  const refIds = refs.map((r) => getPublishedId(r.value)), translations = await client.fetch(
-    `*[_type == $translationMetadataSchemaType && array::intersects(translations[].value._ref, $refIds)] {
+  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,
       "targetId": translations[_key == $targetLanguage][0].value._ref,
       "targetType": translations[_key == $sourceLanguage][0].value -> _type
     }`,
+      {
+        translationMetadataSchemaType: TRANSLATION_METADATA_TYPE,
+        refIds,
+        sourceLanguage,
+        targetLanguage
+      }
+    ),
     {
-      translationMetadataSchemaType: TRANSLATION_METADATA_TYPE,
-      refIds,
-      sourceLanguage,
-      targetLanguage
+      maxAttempts: 3,
+      initialDelayMs: 1e3,
+      context: { operation: "localizeReferences.fetchTranslations", refCount: refIds.length }
     }
   ), translationMap = /* @__PURE__ */ new Map();
   for (const t of translations)
@@ -948,81 +962,80 @@ const fetchTranslationPrompts = async ({
 }, 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(
+  if (targetLanguages.length) {
+    devLog.debug("Starting backward reference update", {
+      releaseId,
+      targetLanguages,
+      excludeCount: excludeDocumentIds.length,
+      component: "updateBackwardReferences"
+    });
+    try {
+      const existingDocs = await client.fetch(
         `*[
-          _id match "versions." + $releaseId + ".*" &&
-          @[$languageFieldName] == $targetLanguage &&
-          !(_id in $excludeIds)
-        ] {
-          _id,
-          "hasStaleRefs": count(*[
-            _id in $sourceDocumentIds && 
-            ^references(@._id)
-          ]) > 0
-        }[hasStaleRefs == true]`,
+        sanity::partOfRelease($releaseId) &&
+        @[$languageFieldName] in $targetLanguages &&
+        !(_id in $excludeIds)
+      ]{
+        _id,
+        "language": @[$languageFieldName]
+      }`,
         {
           releaseId,
-          targetLanguage,
+          targetLanguages,
           languageFieldName,
-          excludeIds: excludeDocumentIds,
-          sourceDocumentIds: normalizedSourceIds
+          excludeIds: excludeDocumentIds
         }
       );
-      if (existingDocsWithStaleRefs.length === 0) {
-        devLog.debug("No existing documents with stale references found", {
+      if (existingDocs.length === 0) {
+        devLog.debug("No existing documents found in release for target languages", {
           releaseId,
-          targetLanguage,
+          targetLanguages,
           component: "updateBackwardReferences"
         });
-        continue;
+        return;
       }
-      devLog.info("Found existing documents with stale references", {
+      devLog.info("Processing existing documents for backward reference updates", {
         releaseId,
-        targetLanguage,
-        count: existingDocsWithStaleRefs.length,
-        documentIds: existingDocsWithStaleRefs.map((d) => d._id),
+        targetLanguages,
+        count: existingDocs.length,
         component: "updateBackwardReferences"
-      }), await Promise.all(
-        existingDocsWithStaleRefs.map(async ({ _id }) => {
+      });
+      let updated = 0, errors = 0;
+      for (const { _id } of existingDocs)
+        try {
           await localizeReferences({
             client,
             documentId: _id,
             sourceLanguage,
             languageFieldName
+          }), updated++;
+        } catch (error) {
+          errors++, devLog.warn("Failed to update references for document", {
+            documentId: _id,
+            error: error instanceof Error ? error.message : String(error),
+            component: "updateBackwardReferences"
           });
-        })
-      ), devLog.info("Updated backward references", {
+        }
+      devLog.info("Backward reference update complete", {
         releaseId,
-        targetLanguage,
-        updatedCount: existingDocsWithStaleRefs.length,
+        targetLanguages,
+        processed: existingDocs.length,
+        updated,
+        errors,
+        component: "updateBackwardReferences"
+      });
+    } catch (error) {
+      devLog.error("Error updating backward references", error instanceof Error ? error : new Error(String(error)), {
+        releaseId,
+        targetLanguages,
         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)
@@ -1347,6 +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 unsetDocumentFields(document, unsetFields) {
+  if (!unsetFields.length)
+    return document;
+  const { filteredDocument, excludedValues } = filterExcludedFields(document, unsetFields);
+  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,
@@ -2617,11 +2640,17 @@ ${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((field) => 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);
   excludeFields.length !== safeExcludeFields.length && devLog.warn("Language field was in excludeFields - removing it to prevent translation errors", {
     documentId: sourceDocument._id,
     languageFieldName,
@@ -2632,10 +2661,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 documentAfterUnset,
+    sourceTitleValue: documentAfterUnset.title
   });
-  const { filteredDocument, excludedValues } = filterExcludedFields(sourceDocument, safeExcludeFields);
+  const { filteredDocument, excludedValues } = filterExcludedFields(documentAfterUnset, safeExcludeFields);
   devLog.info("After filtering excluded fields", {
     documentId: sourceDocument._id,
     filteredHasTitle: "title" in filteredDocument,
@@ -2858,6 +2887,7 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
   openaiConfig,
   releaseId,
   excludeFields,
+  unsetFields,
   replaceExisting,
   mainSourceDocumentId,
   telemetryConfig
@@ -2887,6 +2917,7 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
       openaiConfig,
       releaseId,
       excludeFields,
+      unsetFields,
       replaceExisting,
       mainSourceDocumentId,
       telemetryConfig
@@ -3002,6 +3033,7 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
   translationMode,
   openaiConfig,
   excludeFields,
+  unsetFields,
   releaseConfig,
   telemetryConfig
 }) => {
@@ -3122,6 +3154,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,
@@ -3176,10 +3209,14 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
           languageFieldName
         });
       })
-    ), releaseConfig.mode === "existing" && releaseId && await updateBackwardReferences({
+    ), devLog.debug("Checking if backward reference update is needed", {
+      releaseMode: releaseConfig.mode,
+      releaseId,
+      willUpdate: releaseConfig.mode === "existing" && !!releaseId,
+      component: "translateDocumentSet"
+    }), releaseConfig.mode === "existing" && releaseId && await updateBackwardReferences({
       client,
       releaseId,
-      sourceDocumentIds,
       targetLanguages,
       sourceLanguage,
       languageFieldName,
@@ -3302,6 +3339,7 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
         translationMode,
         openaiConfig: config.openai,
         excludeFields: config.excludeFields,
+        unsetFields: config.unsetFields,
         releaseConfig: {
           ...releaseConfig,
           replaceExisting,
@@ -3324,6 +3362,7 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
       config.maxReferenceDepth,
       config.openai,
       config.excludeFields,
+      config.unsetFields,
       config.telemetry,
       filteredReferences,
       translationMode,