@braze/sanity-plugin-ai-translation 0.2.0 → 0.2.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +76 -0
- package/dist/index.d.ts +13 -0
- package/dist/index.js +1903 -538
- package/dist/index.js.map +1 -1
- package/package.json +7 -1
package/README.md
CHANGED
|
@@ -86,6 +86,82 @@ export default defineConfig({
|
|
|
86
86
|
| `languageFieldName` | `string` | **Yes** | Field name containing the language identifier in documents |
|
|
87
87
|
| `schemaId` | `string` | **Yes** | Schema ID for Sanity Agent Actions (typically `'_.schemas.default'`) |
|
|
88
88
|
| `maxConcurrentTranslationJobs` | `number` | No | Maximum number of concurrent translations (default: 5) |
|
|
89
|
+
| `openai` | `OpenAIConfig` | No | Optional OpenAI integration configuration (see below) |
|
|
90
|
+
|
|
91
|
+
### OpenAI Integration (Optional)
|
|
92
|
+
|
|
93
|
+
The plugin supports optional OpenAI integration for enhanced translation capabilities, including review of Sanity translations and direct GPT-5 translation with no character limits.
|
|
94
|
+
|
|
95
|
+
#### Setup
|
|
96
|
+
|
|
97
|
+
```typescript
|
|
98
|
+
aiTranslationPlugin({
|
|
99
|
+
// ... other required config
|
|
100
|
+
openai: {
|
|
101
|
+
apiKey: process.env.OPENAI_API_KEY!, // Required
|
|
102
|
+
model: 'gpt-5', // Optional, defaults to 'gpt-5'
|
|
103
|
+
reasoningEffort: 'medium', // Optional: 'minimal' | 'low' | 'medium' | 'high'
|
|
104
|
+
verbosity: 'medium', // Optional: 'low' | 'medium' | 'high'
|
|
105
|
+
enabled: true, // Optional, defaults to false
|
|
106
|
+
defaultMode: 'sanity-with-review', // Optional, defaults to 'sanity-only'
|
|
107
|
+
}
|
|
108
|
+
})
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
**⚠️ Security Note:** Never commit API keys to version control. Always use environment variables:
|
|
112
|
+
|
|
113
|
+
```bash
|
|
114
|
+
# .env.local
|
|
115
|
+
OPENAI_API_KEY=sk-...your-key-here...
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
#### Translation Modes
|
|
119
|
+
|
|
120
|
+
When OpenAI is enabled, users can select from three translation modes:
|
|
121
|
+
|
|
122
|
+
1. **Sanity Agent Only** (Default)
|
|
123
|
+
- Uses Sanity's built-in translation agent
|
|
124
|
+
- Fast and reliable
|
|
125
|
+
- No additional API costs
|
|
126
|
+
- 2000 character style guide limit
|
|
127
|
+
|
|
128
|
+
2. **GPT-5 Only** (Beta)
|
|
129
|
+
- Direct translation via GPT-5
|
|
130
|
+
- 1 million token context window
|
|
131
|
+
- Full style guide capacity
|
|
132
|
+
- Incurs OpenAI API costs
|
|
133
|
+
|
|
134
|
+
3. **Sanity + GPT-5 Review** (Highest Quality)
|
|
135
|
+
- Sanity translation reviewed and refined by GPT-5
|
|
136
|
+
- Best quality results
|
|
137
|
+
- Approximately 2x processing time
|
|
138
|
+
- Incurs OpenAI API costs
|
|
139
|
+
|
|
140
|
+
#### GPT-5 Features
|
|
141
|
+
|
|
142
|
+
GPT-5 (released August 2025) provides:
|
|
143
|
+
- **1M token context window** - Handle very large documents and style guides
|
|
144
|
+
- **Advanced reasoning** - Configurable reasoning effort for quality vs. speed tradeoff
|
|
145
|
+
- **Verbosity control** - Adjust response length to optimize token usage
|
|
146
|
+
- **Structure preservation** - Deterministic serialization ensures all document metadata and structure is preserved
|
|
147
|
+
|
|
148
|
+
#### Cost Considerations
|
|
149
|
+
|
|
150
|
+
OpenAI modes incur API costs based on token usage:
|
|
151
|
+
- **GPT-5**: ~$0.002 per 1k input tokens, ~$0.010 per 1k output tokens, ~$0.005 per 1k reasoning tokens
|
|
152
|
+
- **Typical article** (2000 words): ~$0.05-0.15 per translation
|
|
153
|
+
- The plugin shows real-time cost estimates and usage summaries
|
|
154
|
+
|
|
155
|
+
#### OpenAI Configuration Options
|
|
156
|
+
|
|
157
|
+
| Option | Type | Default | Description |
|
|
158
|
+
|--------|------|---------|-------------|
|
|
159
|
+
| `apiKey` | `string` | - | OpenAI API key (required if OpenAI enabled) |
|
|
160
|
+
| `model` | `'gpt-5' \| 'gpt-4o' \| 'gpt-4-turbo' \| 'gpt-4'` | `'gpt-5'` | Model to use for translation/review |
|
|
161
|
+
| `reasoningEffort` | `'minimal' \| 'low' \| 'medium' \| 'high'` | `'medium'` | GPT-5 reasoning effort (affects speed and quality) |
|
|
162
|
+
| `verbosity` | `'low' \| 'medium' \| 'high'` | `'medium'` | GPT-5 response verbosity |
|
|
163
|
+
| `enabled` | `boolean` | `false` | Enable OpenAI features |
|
|
164
|
+
| `defaultMode` | `TranslationMode` | `'sanity-only'` | Default translation mode when dialog opens |
|
|
89
165
|
|
|
90
166
|
### Schema Setup
|
|
91
167
|
|
package/dist/index.d.ts
CHANGED
|
@@ -28,6 +28,14 @@ declare interface PluginConfig {
|
|
|
28
28
|
schemaId: string;
|
|
29
29
|
maxConcurrentTranslationJobs?: number;
|
|
30
30
|
maxReferenceDepth?: number;
|
|
31
|
+
openai?: {
|
|
32
|
+
apiKey: string;
|
|
33
|
+
model?: "gpt-5" | "gpt-4o" | "gpt-4-turbo" | "gpt-4";
|
|
34
|
+
reasoningEffort?: "minimal" | "low" | "medium" | "high";
|
|
35
|
+
verbosity?: "low" | "medium" | "high";
|
|
36
|
+
enabled?: boolean;
|
|
37
|
+
defaultMode?: TranslationMode;
|
|
38
|
+
};
|
|
31
39
|
}
|
|
32
40
|
|
|
33
41
|
/**
|
|
@@ -43,4 +51,9 @@ export declare const translationHistorySchema: {
|
|
|
43
51
|
WidenValidation &
|
|
44
52
|
WidenInitialValue;
|
|
45
53
|
|
|
54
|
+
declare type TranslationMode =
|
|
55
|
+
| "sanity-only"
|
|
56
|
+
| "openai-only"
|
|
57
|
+
| "sanity-with-review";
|
|
58
|
+
|
|
46
59
|
export {};
|