@braze/sanity-plugin-ai-translation 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,258 @@
+# @braze/sanity-plugin-ai-translation
+
+> A Sanity Studio v3 plugin that provides AI-powered translation capabilities for internationalized content using Sanity Agent Actions.
+
+## 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
+- 🔗 **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
+
+## Installation
+
+```sh
+pnpm add @braze/sanity-plugin-ai-translation
+```
+
+## Prerequisites
+
+This plugin requires:
+
+1. **Sanity Studio v4** - Version 4.9.0 or later
+2. **@sanity/client** - Version 7.1.0 or later (for Agent Actions)
+3. **@sanity/document-internationalization** - Plugin must be installed and configured
+4. **sanity-plugin-internationalized-array** - Version 3.1.5 or later
+
+## Configuration
+
+### Basic Setup
+
+Add the plugin to your `sanity.config.ts` file:
+
+```typescript
+import { defineConfig } from 'sanity'
+import { documentInternationalization } from '@sanity/document-internationalization'
+import { aiTranslationPlugin } from '@braze/sanity-plugin-ai-translation'
+
+const SUPPORTED_LANGUAGES = [
+  { id: 'en', title: 'English' },
+  { id: 'es', title: 'Spanish' },
+  { id: 'fr', title: 'French' },
+  { id: 'de', title: 'German' },
+]
+
+export default defineConfig({
+  // ... other config
+  plugins: [
+    // Document internationalization must be configured first
+    documentInternationalization({
+      supportedLanguages: SUPPORTED_LANGUAGES,
+      schemaTypes: ['post', 'page', 'product'],
+    }),
+
+    // Then add the AI translation plugin
+    aiTranslationPlugin({
+      // Required: Array of supported languages
+      supportedLanguages: SUPPORTED_LANGUAGES,
+
+      // Required: Document types that can be translated
+      translatableSchemaTypes: ['post', 'page', 'product'],
+
+      // Required: Field name containing the language identifier
+      languageFieldName: 'language',
+
+      // Required: Schema ID for Agent Actions (usually '_.schemas.default')
+      schemaId: '_.schemas.default',
+
+      // Optional: Maximum concurrent translation jobs (default: 5)
+      maxConcurrentTranslationJobs: 5,
+    }),
+  ],
+})
+```
+
+### Configuration Options
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `supportedLanguages` | `Array<{id: string, title: string}>` | **Yes** | List of supported languages for translation |
+| `translatableSchemaTypes` | `string[]` | **Yes** | Document types that should have translation actions |
+| `languageFieldName` | `string` | **Yes** | Field name containing the language identifier in documents |
+| `schemaId` | `string` | **Yes** | Schema ID for Sanity Agent Actions (typically `'_.schemas.default'`) |
+| `maxConcurrentTranslationJobs` | `number` | No | Maximum number of concurrent translations (default: 5) |
+
+### Schema Setup
+
+The plugin requires you to add the `translationHistory` schema to your document internationalization configuration:
+
+```typescript
+import { documentInternationalization } from '@sanity/document-internationalization'
+import { translationHistorySchema } from '@braze/sanity-plugin-ai-translation'
+
+// In your sanity.config.ts
+documentInternationalization({
+  supportedLanguages: SUPPORTED_LANGUAGES,
+  schemaTypes: ['post', 'page'],
+  // Add translation history to metadata
+  metadataFields: [translationHistorySchema],
+})
+```
+
+### Deploy Schema
+
+After configuration, deploy your schema so Agent Actions can access it:
+
+```bash
+cd your-sanity-project
+npx sanity deploy
+```
+
+## Usage
+
+### Translation Action
+
+Once configured, a "Translate" action will appear on all documents of types listed in `translatableSchemaTypes`.
+
+1. Open a document in Sanity Studio
+2. Click the "Translate" action in the document menu
+3. Select target languages
+4. Configure translation options:
+   - **Overwrite fresh translations** - Re-translate even if translation is up-to-date
+   - **Translate only diffs** - For stale translations, only translate changed fields
+   - **Translate references** - Include referenced documents in translation
+   - **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:
+
+```typescript
+{
+  _type: 'translationSettings',
+  _id: 'translation-settings',
+
+  // Global prompt applied to all translations
+  globalPrompt: 'Maintain a professional tone. Preserve formatting and links.',
+
+  // Locale-specific prompts
+  localePrompts: [
+    {
+      locale: 'es',
+      prompt: 'Use formal Spanish (usted). Avoid Latin American regionalisms.'
+    },
+    {
+      locale: 'fr',
+      prompt: 'Use formal French. Maintain gender agreement for all terms.'
+    }
+  ],
+
+  // Terms that should never be translated
+  protectedPhrases: ['Braze', 'iOS', 'Android', 'SDK']
+}
+```
+
+### Translation Glossary
+
+Create `translationGlossaryTerm` documents for specific term mappings:
+
+```typescript
+{
+  _type: 'translationGlossaryTerm',
+  translations: [
+    { locale: 'en', value: 'dashboard' },
+    { locale: 'es', value: 'panel de control' },
+    { locale: 'fr', value: 'tableau de bord' },
+    { locale: 'de', value: 'Dashboard' }
+  ]
+}
+```
+
+### 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
+5. **Localize References** - Optionally translates referenced documents
+6. **Update Metadata** - Stores translation history with snapshots
+
+### Reference Translation
+
+When "Translate references" is enabled:
+
+```typescript
+// Example: Post with author reference
+{
+  _type: 'post',
+  title: 'My Post',
+  author: { _ref: 'author-en' } // Original English author
+}
+
+// After translation with references enabled:
+{
+  _type: 'post',
+  language: 'es',
+  title: 'Mi Publicación',
+  author: { _ref: 'author-es' } // Now points to Spanish author
+}
+```
+
+The plugin:
+- Recursively traverses references up to configured depth
+- Translates referenced documents if they don't exist
+- Updates references to point to localized versions
+- Uses semaphore to control concurrent jobs
+
+## Publishing
+
+This package is configured for internal publishing to the Braze npm registry.
+
+```bash
+# Login to registry
+npm login --scope=@braze --registry=https://registry.npmjs.org/
+
+# Build and publish
+cd package
+pnpm build
+npm publish
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@braze/sanity-plugin-ai-translation",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "A Sanity Studio v3 plugin that provides AI translation for translations fields.",
   "private": false,
   "keywords": [
@@ -41,7 +41,7 @@
   ],
   "browserslist": "extends @sanity/browserslist-config",
   "scripts": {
-    "build": "plugin-kit verify-package --silent && pkg-utils build --strict --check --clean",
+    "build": "bash copy-readme.sh && plugin-kit verify-package --silent && pkg-utils build --strict --check --clean",
     "dev": "plugin-kit link-watch",
     "prepublishOnly": "pnpm run build",
     "test": "vitest run",
@@ -60,7 +60,7 @@
     "@types/react": "^18.3.0",
     "@types/react-dom": "^18.3.0",
     "lodash.defaults": "4.2.0",
-    "postcss": "8.4.0",
+    "postcss": "8.4.31",
     "react-fast-compare": "^3.2.2",
     "rxjs": "^7.8.2",
     "sanity-plugin-utils": "^1.6.8"