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

package/README.md

@@ -5,12 +5,11 @@
 ## Features
 
 - 🤖 **AI-Powered Translation** - Uses Sanity Agent Actions to translate documents between languages
-- 🔄 **Smart Translation Strategies** - Automatically detects translation freshness (fresh/stale/drifted) and applies appropriate strategy
+- 📦 **Content Releases** - Translations are created in Content Releases for staged publishing
 - 🔗 **Reference Translation** - Optionally translate referenced documents recursively with configurable depth
 - 🎯 **Custom Translation Prompts** - Configure global and locale-specific translation instructions
 - 📚 **Translation Glossary** - Define term-specific translations to ensure consistency
 - 🛡️ **Protected Phrases** - Specify terms that should never be translated (e.g., brand names, product names)
-- 💬 **Feedback System** - AI-powered feedback analysis that automatically improves translation settings
 - ⚙️ **Flexible Configuration** - Control concurrent translation jobs, reference depth, and translation behavior
 - 🔍 **Debug Mode** - Comprehensive logging for troubleshooting translation issues
 
@@ -90,7 +89,7 @@ export default defineConfig({
 
 ### OpenAI Integration (Optional)
 
-The plugin supports optional OpenAI integration for enhanced translation capabilities, including review of Sanity translations and direct GPT-5 translation with no character limits.
+The plugin supports optional OpenAI integration for enhanced translation capabilities, including direct OpenAI translation with no character limits.
 
 #### Setup
 
@@ -103,7 +102,7 @@ aiTranslationPlugin({
     reasoningEffort: 'medium',             // Optional: 'minimal' | 'low' | 'medium' | 'high'
     verbosity: 'medium',                   // Optional: 'low' | 'medium' | 'high'
     enabled: true,                         // Optional, defaults to false
-    defaultMode: 'sanity-with-review',     // Optional, defaults to 'sanity-only'
+    defaultMode: 'openai-only',             // Optional, defaults to 'sanity-only'
   }
 })
 ```
@@ -117,7 +116,7 @@ OPENAI_API_KEY=sk-...your-key-here...
 
 #### Translation Modes
 
-When OpenAI is enabled, users can select from three translation modes:
+When OpenAI is enabled, users can select from two translation modes:
 
 1. **Sanity Agent Only** (Default)
    - Uses Sanity's built-in translation agent
@@ -125,21 +124,15 @@ When OpenAI is enabled, users can select from three translation modes:
    - No additional API costs
    - 2000 character style guide limit
 
-2. **GPT-5 Only** (Beta)
-   - Direct translation via GPT-5
+2. **OpenAI Only** (Beta)
+   - Direct translation via OpenAI
    - 1 million token context window
    - Full style guide capacity
    - Incurs OpenAI API costs
 
-3. **Sanity + GPT-5 Review** (Highest Quality)
-   - Sanity translation reviewed and refined by GPT-5
-   - Best quality results
-   - Approximately 2x processing time
-   - Incurs OpenAI API costs
-
-#### GPT-5 Features
+#### OpenAI Features
 
-GPT-5 (released August 2025) provides:
+OpenAI models provide:
 - **1M token context window** - Handle very large documents and style guides
 - **Advanced reasoning** - Configurable reasoning effort for quality vs. speed tradeoff
 - **Verbosity control** - Adjust response length to optimize token usage
@@ -148,7 +141,7 @@ GPT-5 (released August 2025) provides:
 #### Cost Considerations
 
 OpenAI modes incur API costs based on token usage:
-- **GPT-5**: ~$0.002 per 1k input tokens, ~$0.010 per 1k output tokens, ~$0.005 per 1k reasoning tokens
+- **OpenAI**: ~$0.002 per 1k input tokens, ~$0.010 per 1k output tokens, ~$0.005 per 1k reasoning tokens
 - **Typical article** (2000 words): ~$0.05-0.15 per translation
 - The plugin shows real-time cost estimates and usage summaries
 
@@ -158,8 +151,8 @@ OpenAI modes incur API costs based on token usage:
 |--------|------|---------|-------------|
 | `apiKey` | `string` | - | OpenAI API key (required if OpenAI enabled) |
 | `model` | `'gpt-5' \| 'gpt-4o' \| 'gpt-4-turbo' \| 'gpt-4'` | `'gpt-5'` | Model to use for translation/review |
-| `reasoningEffort` | `'minimal' \| 'low' \| 'medium' \| 'high'` | `'medium'` | GPT-5 reasoning effort (affects speed and quality) |
-| `verbosity` | `'low' \| 'medium' \| 'high'` | `'medium'` | GPT-5 response verbosity |
+| `reasoningEffort` | `'minimal' \| 'low' \| 'medium' \| 'high'` | `'medium'` | OpenAI reasoning effort (affects speed and quality) |
+| `verbosity` | `'low' \| 'medium' \| 'high'` | `'medium'` | OpenAI response verbosity |
 | `enabled` | `boolean` | `false` | Enable OpenAI features |
 | `defaultMode` | `TranslationMode` | `'sanity-only'` | Default translation mode when dialog opens |
 
@@ -205,19 +198,6 @@ Once configured, a "Translate" action will appear on all documents of types list
    - **Max reference depth** - How deep to traverse references (if enabled)
 5. Click "Translate" to start
 
-### Translation States
-
-The plugin tracks three translation states:
-
-- **Fresh** ✅ - Translation is up-to-date with source
-- **Stale** ⚠️ - Source document revision changed (trivial changes)
-- **Drifted** 🔴 - Source document content changed significantly
-
-Based on state:
-- **Fresh** translations are skipped (unless "Overwrite fresh" is enabled)
-- **Stale** translations can use diff-based translation (if "Translate only diffs" is enabled)
-- **Drifted** translations are fully re-translated
-
 ### Translation Settings
 
 Create a `translationSettings` document to customize translation behavior:
@@ -263,34 +243,16 @@ Create `translationGlossaryTerm` documents for specific term mappings:
 }
 ```
 
-### Give Translation Feedback
-
-The plugin includes an AI-powered feedback system that learns from corrections:
-
-1. Open a translated document
-2. Click "Give Translation Feedback" action
-3. Provide feedback and/or enable "Include edits" to analyze changes
-4. Review AI-generated suggestions:
-   - Global prompt updates
-   - Locale-specific prompt updates
-   - Protected phrases to add
-   - Glossary terms to add
-5. Approve suggestions to apply
-
-The AI analyzes your feedback and automatically updates translation settings to improve future translations.
-
 ## Translation Workflow
 
 ### How It Works
 
-1. **Fetch Metadata** - Retrieves translation history and existing translations
-2. **Determine Strategy** - Checks freshness state (fresh/stale/drifted)
-3. **Prepare Translation**:
-   - For **drifted** or **fresh (overwrite)**: Full document translation
-   - For **stale (translate diffs)**: Diff-based translation of changed fields only
-4. **Translate** - Uses Sanity Agent Actions with configured prompts
+1. **Select Release** - Choose to create a new Content Release or add to an existing one
+2. **Prepare Translation** - Assemble translation prompts and prepare source document
+3. **Translate** - Uses Sanity Agent Actions (or OpenAI) with configured prompts
+4. **Create Versions** - Translations are created as versioned documents in the release
 5. **Localize References** - Optionally translates referenced documents
-6. **Update Metadata** - Stores translation history with snapshots
+6. **Update Metadata** - Stores translation history
 
 ### Reference Translation
 

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
@@ -314,10 +459,7 @@ export declare const translationHistorySchema: {
   WidenValidation &
   WidenInitialValue;
 
-declare type TranslationMode =
-  | "sanity-only"
-  | "openai-only"
-  | "sanity-with-review";
+declare type TranslationMode = "sanity-only" | "openai-only";
 
 /**
  * Represents a VTT caption cue with timing and text content.