@braze/sanity-plugin-ai-translation 0.2.3 → 0.2.4

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.
@@ -233,14 +287,105 @@ export declare interface PluginConfig {
   maxReferenceDepth?: number;
   openai?: {
     apiKey: string;
-    model?: "gpt-5.1" | "gpt-5" | "gpt-4o" | "gpt-4-turbo" | "gpt-4";
+    model?:
+      | "gpt-5.1"
+      | "gpt-5"
+      | "gpt-5-mini"
+      | "gpt-5-nano"
+      | "gpt-5-pro"
+      | "gpt-4o"
+      | "gpt-4-turbo"
+      | "gpt-4";
     reasoningEffort?: "low" | "medium" | "high";
     enabled?: boolean;
     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