@pigment/auto-translate 1.2.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Team Pigment
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,405 @@
+# Payload CMS Auto-Translate Plugin
+
+A powerful auto-translation plugin for [Payload CMS](https://payloadcms.com) that automatically translates content from your default language to secondary languages with field-level translation control.
+
+## ✨ Features
+
+- 🌍 **One-Way Auto-Translation**: Automatically translates content from default language to secondary languages
+- 🔒 **Field-Level Exclusion**: Toggle "do not translate" on specific fields in secondary languages
+- 🎯 **Smart Translation**: Preserves excluded fields when updating default language content
+- 🔧 **Flexible Configuration**: Configure per-collection settings and global exclusions
+- 🤖 **OpenAI Integration**: Uses GPT-4o for high-quality translations (with custom provider support)
+- 📦 **Zero UI Overhead**: Seamlessly integrates with Payload's admin panel
+- ⚡ **Performance Optimized**: 10-15x faster translation with smart extraction and deduplication
+
+## 📋 How It Works
+
+1. Create or edit a post in your **default language** (e.g., Swedish)
+2. Save the document - it automatically translates to all secondary languages (e.g., English)
+3. Switch to a secondary language and mark specific fields as "translation locked" 🔒
+4. Future updates to those fields in the default language won't overwrite your custom translations
+
+## 🚀 Installation
+
+```bash
+npm install auto-translate
+# or
+pnpm add auto-translate
+# or
+yarn add auto-translate
+```
+
+## ⚙️ Configuration
+
+### Basic Setup
+
+```typescript
+import { autoTranslate } from 'auto-translate'
+import { buildConfig } from 'payload'
+
+export default buildConfig({
+  // Your localization config is required
+  localization: {
+    defaultLocale: 'sv',
+    locales: ['sv', 'en', 'de', 'fr'],
+    fallback: true,
+  },
+
+  collections: [
+    // Your collections...
+  ],
+
+  plugins: [
+    autoTranslate({
+      collections: {
+        posts: true,
+        pages: true,
+      },
+    }),
+  ],
+})
+```
+
+### Environment Variables
+
+Create a `.env` file in your project root:
+
+```bash
+# Required for OpenAI translation
+OPENAI_API_KEY=your-openai-api-key
+
+# Optional: Custom OpenAI endpoint
+OPENAI_BASE_URL=https://api.openai.com/v1
+```
+
+> **⚠️ Important:** Restart your server after updating `.env` or plugin settings.
+
+---
+
+## 🔧 Advanced Configuration
+
+### Full Configuration Options
+
+```typescript
+import { autoTranslate } from 'auto-translate'
+
+export default buildConfig({
+  plugins: [
+    autoTranslate({
+      // Enable auto-translate for specific collections
+      collections: {
+        posts: true,
+        pages: {
+          enabled: true,
+          // Exclude specific fields from translation in this collection
+          excludeFields: ['slug', 'author'],
+        },
+      },
+
+      // Optional: Show debug logs
+      debugging: false,
+
+      // Optional: Translation provider settings
+      provider: {
+        type: 'openai', // or 'custom'
+        model: 'gpt-4o', // OpenAI model to use
+        apiKey: process.env.OPENAI_API_KEY,
+        baseURL: process.env.OPENAI_BASE_URL,
+
+        // Optional: Custom translation function
+        customTranslate: async ({ data, fromLocale, toLocale }) => {
+          // Your custom translation logic
+          return translatedData
+        },
+      },
+
+      // Optional: Global field exclusions (across all collections)
+      excludeFields: ['slug', 'id', 'createdAt', 'updatedAt'],
+
+      // Optional: Enable translation sync by default
+      enableTranslationSyncByDefault: true,
+
+      // Optional: Custom collection slug for metadata
+      translationExclusionsSlug: 'translation-exclusions',
+
+      // Optional: Disable field-level exclusions entirely (default: true)
+      // When disabled: no exclusion UI, no exclusion collection
+      enableExclusions: true,
+    }),
+  ],
+})
+```
+
+### Per-Collection Configuration
+
+You can configure translation behavior per collection:
+
+```typescript
+collections: {
+  // Simple enable
+  posts: true,
+
+  // Disable translation
+  drafts: false,
+
+  // Advanced configuration
+  pages: {
+    enabled: true,
+    excludeFields: ['slug', 'author', 'seo.keywords'],
+  },
+}
+```
+
+### Disabling Field-Level Exclusions
+
+For simpler setups, you can disable the field-level exclusion system entirely:
+
+```typescript
+autoTranslate({
+  collections: {
+    posts: true,
+    pages: true,
+  },
+  enableExclusions: false, // Disable field-level locking
+  excludeFields: ['slug'], // Global exclusions still work
+})
+```
+
+**When disabled**:
+- ❌ No translation exclusions collection
+- ❌ No 🌐/🔒 buttons on fields
+- ✅ All localized fields are always translated
+- ✅ Global/collection `excludeFields` still work
+
+### Custom Translation Provider
+
+If you don't want to use OpenAI, you can provide your own translation function:
+
+```typescript
+provider: {
+  type: 'custom',
+  customTranslate: async ({ data, fromLocale, toLocale, payload, collection }) => {
+    // Use Google Translate, DeepL, or any other service
+    const translated = await yourTranslationService.translate(data, {
+      from: fromLocale,
+      to: toLocale,
+    })
+
+    return translated
+  },
+}
+```
+
+---
+
+## 📚 Usage Guide
+
+### 1. Creating Content
+
+1. Create a new document in your **default language**
+2. Fill in all the fields with content
+3. Save the document
+4. ✨ The plugin automatically translates and saves the content in all secondary languages
+
+### 2. Locking Fields from Translation
+
+Sometimes you want to customize translations in secondary languages without them being overwritten:
+
+1. Switch to a **secondary language** (e.g., English)
+2. Find the field you want to customize
+3. Click the **🔒 Translation lock** button (or **🌐 Auto-translate** to unlock)
+4. Edit the field with your custom translation
+5. Save the document
+
+Now when you update that field in the default language, it won't overwrite your custom translation in the secondary language!
+
+### 3. Managing Translation Sync
+
+Each document has a **"Enable Auto-Translation"** checkbox in the sidebar:
+
+- ✅ **Enabled** (default): Changes in default language automatically translate
+- ❌ **Disabled**: No automatic translation occurs
+
+### 4. Field-Level Control
+
+The plugin tracks field exclusions per document, per locale, per field path. This means you can:
+
+- Lock translation for `title` in English but keep it unlocked in German
+- Lock a specific block item (e.g., `content.0.description`) in one language
+- Lock nested fields like `seo.meta.description`
+
+---
+
+## 🏗️ How Translation Works
+
+### Translation Flow
+
+```
+1. User edits document in DEFAULT language (e.g., Swedish)
+   ↓
+2. User saves/publishes document
+   ↓
+3. Plugin checks if translationSync is enabled
+   ↓
+4. Plugin checks if document is published (skips drafts/autosaves)
+   ↓
+5. For each SECONDARY language (e.g., English, German):
+   a. Fetch field-level exclusions for that language
+   b. Remove excluded fields from translation payload
+   c. Translate remaining fields using OpenAI
+   d. Merge translated data with existing, preserving excluded fields
+   e. Save translated document in that language
+```
+
+> **📝 Note**: When using Payload's drafts feature with autosave enabled, translations only trigger when you explicitly **publish** the document, not during autosave operations. This prevents unnecessary translation costs and API calls.
+
+### Field Exclusion Logic
+
+- **Global exclusions**: Applied to all collections (configured in plugin options)
+- **Collection exclusions**: Applied to specific collections (configured per collection)
+- **Field-level exclusions**: Set by users via UI (stored in `translation-exclusions` collection)
+- **Auto-excluded**: `id`, `_id`, `createdAt`, `updatedAt`, `translationSync`, `__v`
+
+### Nested Field Support
+
+The plugin fully supports nested and complex field structures:
+
+- **Objects**: `meta.description` ✅
+- **Arrays**: `content.0.title` ✅
+- **Blocks**: `layout.0.heading` ✅
+- **Rich Text**: Translates rich text content ✅
+
+---
+
+## 🎨 UI Components
+
+The plugin adds minimal UI elements to your admin panel:
+
+### Translation Sync Toggle
+
+- **Location**: Document sidebar
+- **Purpose**: Enable/disable auto-translation for the entire document
+
+### Translation Control Button (per field)
+
+- **Location**: Near each translatable field (in secondary languages only)
+- **Purpose**: Lock/unlock translation for specific fields
+- **States**:
+  - 🌐 **Auto-translate**: Field will be updated from default language
+  - 🔒 **Translation locked**: Field won't be overwritten from default language
+
+---
+
+## 🔍 Debugging
+
+Enable debugging to see detailed logs:
+
+```typescript
+autoTranslate({
+  debugging: true,
+  // ... other options
+})
+```
+
+This will log:
+
+- Configuration on startup
+- Translation triggers
+- Excluded paths for each translation
+- Translation success/failure messages
+- API calls and responses
+
+---
+
+## 📊 Architecture
+
+The plugin is built with a clean, modular architecture inspired by [payload-ai](https://github.com/ashbuilds/payload-ai):
+
+```
+src/
+├── index.ts                    # Main plugin entry point
+├── types/                      # TypeScript type definitions
+├── collections/                # Translation metadata collection
+├── services/                   # Translation service layer
+│   └── translationService.ts   # Handles translation logic
+├── utilities/                  # Helper functions
+│   └── fieldHelpers.ts         # Field traversal & merging
+├── components/                 # UI components
+│   └── TranslationControl.tsx  # Field-level control button
+└── endpoints/                  # Custom API endpoints
+    └── translationExclusionsEndpoint.ts
+```
+
+---
+
+## ⚡ Performance
+
+The plugin includes intelligent optimizations that make translation 10-15x faster for large documents:
+
+- **Smart String Extraction**: Only translatable content is sent to the API (80-95% size reduction)
+- **Deduplication**: Identical strings are translated once and reused
+- **Lexical Editor Support**: Special handling for rich text fields
+
+For large documents with Lexical editor content, translation time can be reduced from 30-120 seconds to just 3-10 seconds.
+
+---
+
+## 🧪 Testing
+
+Run the test suite:
+
+```bash
+pnpm test              # Run all tests
+pnpm test:int          # Run integration tests
+pnpm test:e2e          # Run end-to-end tests
+```
+
+---
+
+## 🔒 Access Control
+
+The plugin respects Payload's access control. Translation operations run with the same permissions as the user making the update.
+
+If you need custom access control for translation features, you can add hooks or modify the endpoints.
+
+---
+
+## 🚧 Limitations
+
+- **One-way translation only**: Default language → Secondary languages (not vice versa)
+- **No real-time translation**: Translation happens on save, not as you type
+- **OpenAI dependency**: Requires OpenAI API key (unless using custom provider)
+- **Cost considerations**: Each translation uses OpenAI API credits
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+---
+
+## 📝 License
+
+MIT
+
+---
+
+## 🙏 Acknowledgments
+
+Inspired by the excellent [payload-ai plugin](https://github.com/ashbuilds/payload-ai) by [@ashbuilds](https://github.com/ashbuilds).
+
+---
+
+## 📞 Support
+
+If you have questions or need help:
+
+1. Check the [Payload CMS documentation](https://payloadcms.com/docs)
+2. Open an issue on [GitHub](https://github.com/pigment-se/auto-translate/issues)
+3. Join the [Payload Discord](https://discord.gg/payload)
+4. Visit [pigment.se](https://pigment.se)
+
+---
+
+**Made with ❤️ by Team Pigment for the Payload CMS community**

package/dist/collections/translationExclusions.d.ts

@@ -0,0 +1,2 @@
+import type { CollectionConfig } from 'payload';
+export declare const getTranslationExclusionsCollection: (slug?: string) => CollectionConfig;

package/dist/collections/translationExclusions.js

@@ -0,0 +1,78 @@
+export const getTranslationExclusionsCollection = (slug = 'translation-exclusions')=>({
+        slug,
+        access: {
+            create: ()=>true,
+            delete: ()=>true,
+            read: ()=>true,
+            update: ()=>true
+        },
+        admin: {
+            defaultColumns: [
+                'collection',
+                'documentId',
+                'locale',
+                'excludedPaths'
+            ],
+            description: 'Stores field-level translation exclusions per document and locale. Each locale can have its own set of excluded fields. There should only be ONE record per (collection, documentId, locale) combination.',
+            group: 'Settings',
+            useAsTitle: 'collection'
+        },
+        fields: [
+            {
+                name: 'collection',
+                type: 'text',
+                admin: {
+                    description: 'The collection this exclusion belongs to',
+                    position: 'sidebar',
+                    readOnly: true
+                },
+                index: true,
+                required: true
+            },
+            {
+                name: 'documentId',
+                type: 'text',
+                admin: {
+                    description: 'The ID of the document',
+                    position: 'sidebar',
+                    readOnly: true
+                },
+                index: true,
+                required: true
+            },
+            {
+                name: 'locale',
+                type: 'text',
+                admin: {
+                    description: 'The locale these exclusions apply to (e.g., "en", "de", "fr")',
+                    position: 'sidebar',
+                    readOnly: true
+                },
+                index: true,
+                label: 'Locale',
+                required: true
+            },
+            {
+                name: 'excludedPaths',
+                type: 'array',
+                admin: {
+                    description: 'Fields that should NOT be auto-translated in this specific locale. Each locale has its own independent set of exclusions.'
+                },
+                fields: [
+                    {
+                        name: 'path',
+                        type: 'text',
+                        admin: {
+                            description: 'Field path (e.g., "title", "content.0.description")'
+                        },
+                        label: 'Field Path',
+                        required: true
+                    }
+                ],
+                label: `Excluded Fields for this Locale`,
+                required: true
+            }
+        ]
+    });
+
+//# sourceMappingURL=translationExclusions.js.map

package/dist/collections/translationExclusions.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/collections/translationExclusions.ts"],"sourcesContent":["import type { CollectionConfig } from 'payload'\n\nexport const getTranslationExclusionsCollection = (\n  slug: string = 'translation-exclusions',\n): CollectionConfig => ({\n  slug,\n  access: {\n    create: () => true,\n    delete: () => true,\n    read: () => true,\n    update: () => true,\n  },\n  admin: {\n    defaultColumns: ['collection', 'documentId', 'locale', 'excludedPaths'],\n    description:\n      'Stores field-level translation exclusions per document and locale. Each locale can have its own set of excluded fields. There should only be ONE record per (collection, documentId, locale) combination.',\n    group: 'Settings',\n    useAsTitle: 'collection',\n  },\n  fields: [\n    {\n      name: 'collection',\n      type: 'text',\n      admin: {\n        description: 'The collection this exclusion belongs to',\n        position: 'sidebar',\n        readOnly: true,\n      },\n      index: true,\n      required: true,\n    },\n    {\n      name: 'documentId',\n      type: 'text',\n      admin: {\n        description: 'The ID of the document',\n        position: 'sidebar',\n        readOnly: true,\n      },\n      index: true,\n      required: true,\n    },\n    {\n      name: 'locale',\n      type: 'text',\n      admin: {\n        description: 'The locale these exclusions apply to (e.g., \"en\", \"de\", \"fr\")',\n        position: 'sidebar',\n        readOnly: true,\n      },\n      index: true,\n      label: 'Locale',\n      required: true,\n    },\n    {\n      name: 'excludedPaths',\n      type: 'array',\n      admin: {\n        description:\n          'Fields that should NOT be auto-translated in this specific locale. Each locale has its own independent set of exclusions.',\n      },\n      fields: [\n        {\n          name: 'path',\n          type: 'text',\n          admin: {\n            description: 'Field path (e.g., \"title\", \"content.0.description\")',\n          },\n          label: 'Field Path',\n          required: true,\n        },\n      ],\n      label: `Excluded Fields for this Locale`,\n      required: true,\n    },\n  ],\n})\n"],"names":["getTranslationExclusionsCollection","slug","access","create","delete","read","update","admin","defaultColumns","description","group","useAsTitle","fields","name","type","position","readOnly","index","required","label"],"mappings":"AAEA,OAAO,MAAMA,qCAAqC,CAChDC,OAAe,wBAAwB,GACjB,CAAA;QACtBA;QACAC,QAAQ;YACNC,QAAQ,IAAM;YACdC,QAAQ,IAAM;YACdC,MAAM,IAAM;YACZC,QAAQ,IAAM;QAChB;QACAC,OAAO;YACLC,gBAAgB;gBAAC;gBAAc;gBAAc;gBAAU;aAAgB;YACvEC,aACE;YACFC,OAAO;YACPC,YAAY;QACd;QACAC,QAAQ;YACN;gBACEC,MAAM;gBACNC,MAAM;gBACNP,OAAO;oBACLE,aAAa;oBACbM,UAAU;oBACVC,UAAU;gBACZ;gBACAC,OAAO;gBACPC,UAAU;YACZ;YACA;gBACEL,MAAM;gBACNC,MAAM;gBACNP,OAAO;oBACLE,aAAa;oBACbM,UAAU;oBACVC,UAAU;gBACZ;gBACAC,OAAO;gBACPC,UAAU;YACZ;YACA;gBACEL,MAAM;gBACNC,MAAM;gBACNP,OAAO;oBACLE,aAAa;oBACbM,UAAU;oBACVC,UAAU;gBACZ;gBACAC,OAAO;gBACPE,OAAO;gBACPD,UAAU;YACZ;YACA;gBACEL,MAAM;gBACNC,MAAM;gBACNP,OAAO;oBACLE,aACE;gBACJ;gBACAG,QAAQ;oBACN;wBACEC,MAAM;wBACNC,MAAM;wBACNP,OAAO;4BACLE,aAAa;wBACf;wBACAU,OAAO;wBACPD,UAAU;oBACZ;iBACD;gBACDC,OAAO,CAAC,+BAA+B,CAAC;gBACxCD,UAAU;YACZ;SACD;IACH,CAAA,EAAE"}

package/dist/components/TranslationControl.css

@@ -0,0 +1,92 @@
+.translation-control {
+  margin-top: 0.75rem;
+  opacity: 0;
+  transform: translateY(-4px);
+  transition:
+    opacity 0.2s ease-in-out,
+    transform 0.2s ease-in-out;
+  pointer-events: none;
+}
+
+/* Show control when parent field is focused or hovered */
+.field-type:focus-within .translation-control,
+.field-type:hover .translation-control,
+.translation-control.is-excluded {
+  opacity: 1;
+  transform: translateY(0);
+  pointer-events: auto;
+}
+
+/* Keep excluded/locked fields always slightly visible for better awareness */
+.translation-control.is-excluded {
+  opacity: 0.7;
+}
+
+.translation-control.is-excluded:hover {
+  opacity: 1;
+}
+
+.translation-control__button {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.5rem;
+  padding: 0.375rem 0.75rem;
+  background: var(--theme-elevation-0, #ffffff);
+  border: 1px solid var(--theme-elevation-300, #d1d5db);
+  border-radius: 6px;
+  cursor: pointer;
+  font-size: 0.813rem;
+  font-weight: 500;
+  color: var(--theme-text, #374151);
+  transition: all 0.15s ease;
+  box-shadow: 0 1px 2px rgba(0, 0, 0, 0.05);
+}
+
+.translation-control__button:hover:not(:disabled) {
+  background: var(--theme-elevation-50, #f9fafb);
+  border-color: var(--theme-primary-500, #3b82f6);
+  box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
+  transform: translateY(-1px);
+}
+
+.translation-control__button:active:not(:disabled) {
+  transform: translateY(0);
+  box-shadow: 0 1px 2px rgba(0, 0, 0, 0.05);
+}
+
+.translation-control__button:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+/* Excluded/Locked state styling */
+.translation-control.is-excluded .translation-control__button {
+  background: var(--theme-warning-50, #fef3c7);
+  border-color: var(--theme-warning-400, #f59e0b);
+  color: var(--theme-warning-900, #92400e);
+}
+
+.translation-control.is-excluded .translation-control__button:hover:not(:disabled) {
+  background: var(--theme-warning-100, #fde68a);
+  border-color: var(--theme-warning-500, #f59e0b);
+}
+
+.translation-control__icon {
+  font-size: 1rem;
+  line-height: 1;
+}
+
+.translation-control__label {
+  line-height: 1;
+}
+
+.translation-control__status {
+  display: inline-block;
+  margin-left: 0.5rem;
+  padding: 0.25rem 0.5rem;
+  background: var(--theme-warning-50, #fef3c7);
+  border-radius: 4px;
+  font-size: 0.75rem;
+  color: var(--theme-warning-900, #92400e);
+  line-height: 1.4;
+}

package/dist/components/TranslationControl.d.ts

@@ -0,0 +1,18 @@
+import React from 'react';
+import './TranslationControl.css';
+type TranslationControlProps = {
+    collectionSlug?: string;
+    defaultLocale: string;
+    fieldPath?: string;
+    path?: string;
+};
+/**
+ * UI component that allows users to toggle "do not translate" for specific fields
+ * Only shows on secondary locales (not the default locale)
+ *
+ * The component can receive the field path in two ways:
+ * 1. From Payload's `path` prop (preferred - includes runtime array/block indices)
+ * 2. From the `fieldPath` clientProp (fallback - static path from field definition)
+ */
+export declare const TranslationControl: React.FC<TranslationControlProps>;
+export {};