@braze/sanity-plugin-ai-translation 0.2.33 → 0.2.37

package/dist/index.d.ts

@@ -38,6 +38,30 @@ export declare const aiTranslationPlugin: Plugin_2<PluginConfig>;
  */
 export declare type AnyFieldTransform = FieldTransform<any, any>;
 
+/**
+ * Common enum field names that are typically excluded from translation
+ * @internal
+ */
+export declare const COMMON_ENUM_FIELDS: readonly [
+  "status",
+  "state",
+  "type",
+  "category",
+  "priority",
+  "visibility",
+  "role",
+  "permission",
+  "level",
+  "mode",
+  "format",
+  "variant",
+  "size",
+  "theme",
+  "kind",
+  "phase",
+  "stage",
+];
+
 /**
  * Criteria for matching fields that should be transformed.
  * @public
@@ -169,6 +193,36 @@ export declare interface FieldTransform<
   ) => TOriginal;
 }
 
+/**
+ * Result of filtering excluded fields from a document
+ * @internal
+ */
+export declare interface FilteredDocument<T = any> {
+  /** Document with excluded fields removed */
+  filteredDocument: T;
+  /** Excluded field values that were removed */
+  excludedValues: Record<string, any>;
+}
+
+/**
+ * Recursively filters out excluded fields from a document
+ * @param document - The document to filter
+ * @param excludeFields - Array of field patterns to exclude. Supports:
+ *   - Field names: 'status' (matches any field named 'status' anywhere)
+ *   - Exact paths: 'meta.category' (matches only 'category' under 'meta')
+ *   - Array paths: 'body[0].imageType' (matches 'imageType' in first array item)
+ *   - Wildcard arrays: 'body[*].imageType' (matches 'imageType' in any array item)
+ *   - Hierarchical: '**.status' (explicitly matches 'status' anywhere - same as just 'status')
+ * @param currentPath - Current path in the document (used internally)
+ * @returns Filtered document and excluded values
+ * @internal
+ */
+export declare function filterExcludedFields<T extends Record<string, any>>(
+  document: T,
+  excludeFields?: string[],
+  currentPath?: string,
+): FilteredDocument<T>;
+
 /**
  * Helper type to infer the original type from a FieldTransform.
  * Useful for type checking and creating wrapper functions.
@@ -247,8 +301,91 @@ export declare interface PluginConfig {
     defaultMode?: TranslationMode;
   };
   fieldTransforms?: AnyFieldTransform[];
+  /**
+   * Fields to exclude from translation. These fields will be preserved as-is in the translated document.
+   * Supports field names (e.g., 'status') and nested field paths (e.g., 'meta.category').
+   * Useful for enum fields, IDs, technical values, and other non-translatable content.
+   *
+   * @example
+   * ```typescript
+   * excludeFields: ['status', 'category', 'type', 'meta.priority', 'config.mode']
+   * ```
+   */
+  excludeFields?: string[];
 }
 
+/**
+ * Predefined exclusion lists for common use cases
+ * @internal
+ */
+export declare const PREDEFINED_EXCLUSIONS: {
+  /** Common enum and status fields */
+  readonly enums: readonly [
+    "status",
+    "state",
+    "type",
+    "category",
+    "priority",
+    "visibility",
+    "role",
+    "permission",
+    "level",
+    "mode",
+    "format",
+    "variant",
+    "size",
+    "theme",
+    "kind",
+    "phase",
+    "stage",
+  ];
+  /** All metadata and system fields (starting with _) */
+  readonly metadata: readonly [
+    "_id",
+    "_type",
+    "_rev",
+    "_createdAt",
+    "_updatedAt",
+  ];
+  /** Common technical and configuration fields */
+  readonly technical: readonly [
+    "slug",
+    "handle",
+    "key",
+    "code",
+    "id",
+    "uuid",
+    "token",
+    "hash",
+    "checksum",
+    "version",
+    "config",
+    "settings",
+  ];
+  /** SEO and URL-related fields that often shouldn't be translated */
+  readonly seo: readonly [
+    "slug",
+    "handle",
+    "permalink",
+    "canonical",
+    "redirect",
+    "robots",
+    "sitemap",
+  ];
+};
+
+/**
+ * Restores previously excluded fields to a translated document
+ * @param translatedDocument - The translated document
+ * @param excludedValues - The excluded field values to restore
+ * @returns Document with excluded fields restored
+ * @internal
+ */
+export declare function restoreExcludedFields<T extends Record<string, any>>(
+  translatedDocument: T,
+  excludedValues: Record<string, any>,
+): T;
+
 /**
  * Transform for handling Portable Text (rich text) content using XML-like serialization.
  * This leverages the existing serialization utilities to convert complex rich text

package/dist/index.js

@@ -1799,6 +1799,146 @@ const getExistingTranslationId = (translationMetadata, targetLanguage) => transl
     })
   });
 };
+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,
@@ -1999,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)) {
@@ -2044,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 || "",
@@ -2054,47 +2196,47 @@ const globalTransformRegistry = new TransformRegistry(), callGPT5 = async (apiKe
 }, calculateCost = (tokens, model) => {
   const pricing = {
     "gpt-5": {
-      input: 125e-5,
-      output: 0.01,
+      input: 125e-8,
+      output: 1e-5,
       reasoning: 0
     },
     "gpt-5.1": {
-      input: 125e-5,
-      output: 0.01,
+      input: 125e-8,
+      output: 1e-5,
       reasoning: 0
     },
     "gpt-5-mini": {
-      input: 25e-5,
-      output: 2e-3,
+      input: 25e-8,
+      output: 2e-6,
       reasoning: 0
     },
     "gpt-5-nano": {
-      input: 5e-5,
-      output: 4e-4,
+      input: 50000000000000004e-24,
+      output: 40000000000000003e-23,
       reasoning: 0
     },
     "gpt-5-pro": {
-      input: 0.015,
-      output: 0.12,
+      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;
@@ -2245,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", {
@@ -2276,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", {
@@ -2444,6 +2592,7 @@ const globalTransformRegistry = new TransformRegistry(), callGPT5 = async (apiKe
 }, getOpenAITranslation = async ({
   dispatch,
   sourceDocument,
+  originalSourceDocument,
   languageFieldName,
   translationPrompts,
   targetLanguage,
@@ -2484,9 +2633,9 @@ const globalTransformRegistry = new TransformRegistry(), callGPT5 = async (apiKe
       responseLength: response.content.length,
       responsePreview: response.content.substring(0, 500)
     });
-    const result = deserializeDocument(sourceDocument, response.content);
+    const baseDocument = originalSourceDocument || sourceDocument, result = deserializeDocument(baseDocument, response.content);
     result[languageFieldName] = targetLanguage;
-    const validation = validateStructureIntegrity(sourceDocument, result);
+    const validation = validateStructureIntegrity(baseDocument, result);
     if (!validation.valid) {
       devLog.error("Structure validation failed", {
         ...logContext,
@@ -2730,14 +2879,30 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
   translationPrompts,
   translationMode,
   openaiConfig,
-  releaseId
+  releaseId,
+  excludeFields = []
 }) => {
-  devLog.debug("Applying field transforms before translation", {
+  devLog.info("Filtering excluded fields before translation", {
+    documentId: sourceDocument._id,
+    documentType: sourceDocument._type,
+    excludeFields,
+    excludeFieldsLength: excludeFields?.length ?? 0,
+    sourceHasTitle: "title" in sourceDocument,
+    sourceTitleValue: sourceDocument.title
+  });
+  const { filteredDocument, excludedValues } = filterExcludedFields(sourceDocument, excludeFields);
+  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
   });
@@ -2760,6 +2925,7 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
       setJobStatus(dispatch, sourceDocument._id, targetLanguage, "translating_with_openai"), translatedDoc = await getOpenAITranslation({
         dispatch,
         sourceDocument: transformedDocument,
+        originalSourceDocument: sourceDocument,
         targetLanguage,
         languageFieldName,
         translationPrompts,
@@ -2778,12 +2944,26 @@ ${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 = {
+  });
+  devLog.info("Before restoring excluded fields", {
+    documentId: sourceDocument._id,
+    excludedFieldCount: Object.keys(excludedValues).length,
+    excludedValuesKeys: Object.keys(excludedValues),
+    transformedResultHasTitle: "title" in transformedResult,
+    transformedResultTitle: transformedResult.title
+  });
+  const finalDoc = restoreExcludedFields(transformedResult, excludedValues);
+  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
   };
@@ -2804,7 +2984,8 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
   translationPrompts,
   translationMode,
   openaiConfig,
-  releaseId
+  releaseId,
+  excludeFields
 }) => {
   const logContext = {
     documentId: sourceDocument._id,
@@ -2840,7 +3021,8 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
         translationPrompts,
         translationMode,
         openaiConfig,
-        releaseId
+        releaseId,
+        excludeFields
       }),
       {
         maxRetries: 3,
@@ -2906,7 +3088,8 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
   references = [],
   maxConcurrentTranslationJobs,
   translationMode,
-  openaiConfig
+  openaiConfig,
+  excludeFields
 }) => {
   const logContext = {
     documentId: sourceDocument._id,
@@ -2972,7 +3155,8 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
                 translationPrompts,
                 translationMode,
                 openaiConfig,
-                releaseId: releaseId2
+                releaseId: releaseId2,
+                excludeFields
               });
               versionedTargetDocumentId && versionedTargetDocumentIds.push(versionedTargetDocumentId);
             }
@@ -3045,7 +3229,8 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
       maxConcurrentTranslationJobs: config.maxConcurrentTranslationJobs,
       maxReferenceDepth: config.maxReferenceDepth,
       translationMode,
-      openaiConfig: config.openai
+      openaiConfig: config.openai,
+      excludeFields: config.excludeFields
     });
   }, [
     document,
@@ -3057,6 +3242,7 @@ ${protectedPhrases.join(", ")}`, buildStyleGuideSection = (globalPrompt, localeP
     config.maxConcurrentTranslationJobs,
     config.maxReferenceDepth,
     config.openai,
+    config.excludeFields,
     references,
     shouldOverwriteFreshTranslations,
     translationMode
@@ -3439,7 +3625,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: [
@@ -4038,7 +4224,11 @@ const aiTranslationPlugin = definePlugin((config) => (config.fieldTransforms?.le
   }
 })), translationHistorySchema = translationHistory;
 export {
+  COMMON_ENUM_FIELDS,
+  PREDEFINED_EXCLUSIONS,
   aiTranslationPlugin,
+  filterExcludedFields,
+  restoreExcludedFields,
   richTextTransform,
   translationHistorySchema,
   vttCaptionTransform