@braze/sanity-plugin-ai-translation 0.2.39 → 0.2.52

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

@@ -446,6 +446,21 @@ declare interface TranslatableVTTCaptions {
   _originalMetadata: VTTCaptionMetadata[];
 }
 
+/**
+ * Special type to track transformed Wistia captions.
+ * This combines metadata separation for token efficiency with compact text format for translation.
+ */
+declare interface TranslatableWistiaCaptions {
+  _type: "translatable.wistia.captions";
+  translationText: string;
+  _originalMetadata: WistiaCaptionsMetadata;
+  _srtCues: Array<{
+    index: number;
+    startTime: string;
+    endTime: string;
+  }>;
+}
+
 /**
  * Schema for translation history
  *
@@ -459,10 +474,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.
@@ -500,4 +512,40 @@ export declare const vttCaptionTransform: FieldTransform<
   TranslatableVTTCaptions
 >;
 
+/**
+ * Represents a Wistia captions object with SRT content and metadata.
+ */
+declare interface WistiaCaptions {
+  captionContent?: string;
+  captionFileName?: string;
+  isoLanguage?: string;
+  captionUploadStatus?: string;
+  captionUploadMessage?: string;
+  [key: string]: string | undefined;
+}
+
+/**
+ * Wistia captions metadata without captionContent, used for preservation during translation.
+ */
+declare interface WistiaCaptionsMetadata {
+  captionFileName?: string;
+  isoLanguage?: string;
+  captionUploadStatus?: string;
+  captionUploadMessage?: string;
+  _originalIndex: number;
+  [key: string]: string | number | undefined;
+}
+
+/**
+ * Transform for handling Wistia captions in documents using SRT format.
+ * This stores metadata separately for token efficiency while formatting
+ * text content in a compact indexed format for better translation results.
+ *
+ * @public
+ */
+export declare const wistiaCaptionTransform: FieldTransform<
+  WistiaCaptions,
+  TranslatableWistiaCaptions
+>;
+
 export {};