@easyling/sanity-connector 0.0.2 → 0.0.3

package/README.md

@@ -1,19 +1,18 @@
 # Sanity Translation Plugin
 
-A Sanity Studio plugin that enables document translation functionality with support for single and bulk operations. The plugin extracts document content as HTML and prepares translation requests for external translation services.
+A Sanity Studio plugin that enables seamless document translation workflows. It extracts content as HTML, manages translation requests to external services, and handles the re-import of translated content while preserving Portable Text structures.
 
 ## Features
 
-- **Single Document Translation**: Translate individual documents with user confirmation
-- **Bulk Translation**: Translate multiple documents in batch operations  
-- **Document Creation**: Automatically create new translated documents
-- **HTML Content Extraction**: Convert Sanity portable text to HTML format
-- **Portable Text Conversion**: Convert HTML responses back to Sanity portable text
-- **Translation-Invariant Fields**: Mark specific fields as non-translatable using the `dnt` (Do Not Translate) flag
-- **DNT Field Management UI**: User-friendly document action to manage which fields should not be translated
-- **Comprehensive Validation**: Multi-layer validation and error handling
-- **Progress Tracking**: Real-time progress updates for bulk operations
-- **Error Handling**: Detailed error reporting and rollback support
+- **Single Document Translation**: Translate individual documents directly from the document form.
+- **Bulk Translation**: Batch process multiple documents via a dedicated tool.
+- **Smart Content Extraction**: Converts Sanity Portable Text to HTML for translation and back again.
+- **Translation Invariance**: granular control over what gets translated via "Do Not Translate" (DNT) flags.
+  - **Inline Badges**: Toggle translation status for individual fields directly in the editor.
+  - **Field Management**: dedicated action to manage DNT status across the whole document.
+- **Authentication Support**: Secure OAuth integration with translation services, with a legacy mode for local testing.
+- **Auto-Configuration**: Intelligent defaults for new installations to get you started quickly.
+- **Progress Tracking**: Real-time feedback for long-running bulk operations.
 
 ## Installation
 
@@ -32,7 +31,7 @@ import translationPlugin from 'sanity-translation-plugin'
 export default defineConfig({
   // ... your other config
   plugins: [
-    // ... your other plugins
+    // ... other plugins
     translationPlugin()
   ]
 })
@@ -40,443 +39,84 @@ export default defineConfig({
 
 ## Configuration
 
-The plugin works with a placeholder endpoint by default for testing purposes. In production, you'll need to configure it with your translation service endpoint.
+### Authentication & Connection
 
-### Basic Configuration
+The plugin supports two modes of operation:
 
-```typescript
-import translationPlugin from 'sanity-translation-plugin'
-
-export default defineConfig({
-  plugins: [
-    translationPlugin({
-      // Plugin configuration options will be available in future versions
-      // Currently uses placeholder endpoint for testing
-    })
-  ]
-})
-```
-
-### Translation Service Requirements
-
-Your translation service should accept POST requests with the following payload structure:
-
-```json
-{
-  "content": "<h1>Document content in HTML format</h1>",
-  "format": "html",
-  "metadata": {
-    "documentId": "document-id",
-    "documentType": "document-type",
-    "title": "Document Title",
-    "sourceLanguage": "en",
-    "targetLanguage": "es"
-  }
-}
-```
-
-And return responses in this format:
-
-```json
-{
-  "success": true,
-  "translatedContent": {
-    "body": "<h1>Translated HTML content</h1>",
-    "title": "Translated Title",
-    "slug": "translated-slug",
-    "fields": {}
-  },
-  "requestId": "optional-request-id"
-}
-```
+1.  **OAuth Mode (Recommended for Production)**:
+    -   Uses secure token-based authentication.
+    -   Configurable via the **OAuth Configuration** tool within Sanity Studio.
+    -   Supports project-specific access control.
 
-## Translation Service Integration
+2.  **Legacy/Development Mode**:
+    -   Default behavior out of the box.
+    -   Points to `http://app.easyling.com` by default.
+    -   Useful for local development and testing without setting up full auth.
 
-This plugin requires an external translation service that implements the specified API format. 
+To configure the plugin for production use, navigate to the **Easyling Translation Plugin Configuration** document type in your Sanity Studio after installation, and create a new configuration. Enter your project code and access token (both are available in the Easyling platform), and publish your configuration.
 
-### Quick Start with Example Service
+Next, navigate to the **Locales** tab of the configuration, and add the locales you wish to handle. These are the ones you will be able to translate your content into.
 
-1. **Start the example translation service:**
-   ```bash
-   cd examples
-   npm install
-   npm start
-   ```
+At this point, you're ready to begin processing content, but if you want, you can add translation-invariant fields for your content types, by toggling the badges on the individual fields.
 
-2. **Configure the plugin** to use `http://localhost:8275/translate` as the endpoint
+### Defaults
 
-3. **Test translation** using the document actions in Sanity Studio
-
-### Documentation
-
-- **[Translation Service API Documentation](./docs/translation-service-api.md)** - Complete API specification
-- **[JSON Schema](./docs/translation-response-schema.json)** - Response format validation
-- **[Example Implementation](./examples/)** - Working example service
-- **[Documentation Overview](./docs/README.md)** - All documentation files
-
-### Expected Response Format
-
-Your translation service must return responses in this format:
-
-**Success Response:**
-```json
-{
-  "success": true,
-  "translatedContent": {
-    "body": "<h1>Translated HTML content</h1>",
-    "title": "Translated Title",
-    "slug": "translated-slug",
-    "fields": {}
-  },
-  "requestId": "optional-request-id"
-}
-```
-
-**Error Response:**
-```json
-{
-  "success": false,
-  "error": "Error message describing the failure",
-  "requestId": "optional-request-id"
-}
-```
+The plugin comes with "Auto-Default" behavior. When you install it for the first time, it will automatically select sensible defaults (like "Draft" mode for new translated documents) so you can start using it immediately without manual configuration.
 
 ## Usage
 
 ### Single Document Translation
 
-1. **Open a document** in Sanity Studio that you want to translate
-2. **Click the "Translate" action** button in the document toolbar (appears as a translate icon)
-3. **Review the confirmation dialog** showing the document details
-4. **Click "Translate"** to proceed with the translation
-5. **Monitor the progress** - the plugin will show loading states during processing
-6. **View results** - translation requests are logged to the browser console for testing
-
-**Example workflow:**
-```
-Document: "Welcome Post" (blog post)
-↓ Extract content as HTML
-↓ Prepare translation request
-↓ Log request to console (for testing)
-↓ Show success confirmation
-```
+1.  Open a document in Sanity Studio.
+2.  Click the **Translate** icon in the document toolbar.
+3.  Review the document details in the confirmation dialog.
+4.  Click **Translate**.
+5.  The plugin will process the translation and inform you when complete.
 
 ### Bulk Translation
 
-1. **Open the "Bulk Translate" tool** from the Sanity Studio tools menu
-2. **Select document types** you want to translate (e.g., "post", "page")
-3. **Choose specific documents** from the filtered list
-4. **Click "Translate X Documents"** where X is the number of selected documents
-5. **Confirm the bulk operation** in the dialog
-6. **Monitor progress** with the real-time progress indicator
-7. **Review results** in the summary report
-
-**Example workflow:**
-```
-Selected: 5 blog posts
-↓ Extract content from each document
-↓ Prepare 5 translation requests
-↓ Process requests (logged to console)
-↓ Show summary: "5 documents processed successfully"
-```
-
-### Testing the Plugin
-
-Since the plugin uses a placeholder endpoint for testing:
-
-1. **Open browser developer tools** to view the console
-2. **Perform translation actions** (single or bulk)
-3. **Check console logs** to see the prepared translation requests
-4. **Verify request format** matches your translation service expectations
-
-**Console output example:**
-```javascript
-[Translation Plugin] Request prepared for document: welcome-post
-{
-  "content": "<h1>Welcome to our blog</h1><p>This is our first post...</p>",
-  "format": "html",
-  "metadata": {
-    "documentId": "welcome-post",
-    "documentType": "post",
-    "title": "Welcome to our blog"
-  }
-}
-```
-
-## Development
-
-### Building the Plugin
-
-```bash
-# Install dependencies
-npm install
-
-# Build the plugin
-npm run build
-
-# Build and watch for changes
-npm run dev
-
-# Run tests
-npm run test
-
-# Run tests with coverage
-npm run test:coverage
-
-# Lint code
-npm run lint
-
-# Fix linting issues
-npm run lint:fix
-```
-
-### Project Structure
-
-```
-sanity-translation-plugin/
-├── src/
-│   ├── index.ts                 # Plugin entry point
-│   ├── plugin.ts               # Main plugin definition
-│   ├── actions/
-│   │   ├── translateDocument.ts # Single document translation
-│   │   └── bulkTranslate.ts     # Bulk translation tool
-│   ├── services/
-│   │   ├── contentExtractor.ts  # HTML content extraction
-│   │   ├── translationService.ts # Translation request handling
-│   │   └── documentCreationService.ts # Document creation
-│   └── utils/
-│       ├── htmlFormatter.ts     # HTML formatting utilities
-│       └── logger.ts           # Logging utilities
-├── dist/                       # Built plugin files
-├── docs/                       # Documentation
-└── examples/                   # Example implementations
-```
-
-## Architecture
-
-The plugin follows a modular architecture with clear separation of concerns:
-
-### Core Services
-
-- **ContentExtractor** (`src/services/contentExtractor.ts`)
-  - Extracts content from Sanity documents
-  - Converts portable text to HTML format
-  - Handles various field types (text, images, references)
-
-- **TranslationService** (`src/services/translationService.ts`)
-  - Prepares translation request payloads
-  - Handles request logging for testing
-  - Manages bulk translation processing
+1.  Open the **Bulk Translate** tool from the Sanity Studio tools menu.
+2.  Select the document types you wish to translate.
+3.  Filter and select specific documents from the list.
+4.  Click the **Translate** button to process the batch.
+5.  A summary report will be displayed upon completion.
 
-- **DocumentCreationService** (`src/services/documentCreationService.ts`)
-  - Creates new Sanity documents from translation responses
-  - Converts HTML back to portable text format
-  - Handles document validation and error recovery
+### Managing Translatable Fields
 
-### User Interface Components
+Sometimes you need to keep specific fields (like product codes, technical IDs, or proper names) from being translated.
 
-- **Document Actions** (`src/actions/translateDocument.ts`)
-  - Adds translate button to document toolbar
-  - Handles single document translation workflow
-  - Provides user feedback and error handling
+**Method 1: Inline Badges**
+In the document editor, you will see small badges below translatable fields:
+-   **Green "Will Translate"**: The field will be included in the translation request.
+-   **Red "Do Not Translate"**: The field will be skipped.
+Click the badge to toggle the status.
 
-- **Bulk Translation Tool** (`src/actions/bulkTranslate.ts`)
-  - Provides bulk translation interface
-  - Document selection and filtering
-  - Progress tracking and result reporting
-
-### Utilities
-
-- **HTML Formatter** (`src/utils/htmlFormatter.ts`)
-  - HTML formatting and validation utilities
-  - Content structure preservation
-
-- **Logger** (`src/utils/logger.ts`)
-  - Structured logging for debugging
-  - Request/response tracking
-
-## Requirements
-
-- **Sanity Studio**: v3.0.0 or higher
-- **Node.js**: 16.0.0 or higher
-- **React**: 18.0.0 or higher
-- **TypeScript**: 5.0.0 or higher (for development)
+**Method 2: Field Management Action**
+For a high-level view:
+1.  Click the document menu (three dots) in the top right.
+2.  Select **Manage Translation Fields**.
+3.  View and toggle the translation status for all fields in the document.
 
 ## Troubleshooting
 
-### Common Issues
-
 **Plugin not appearing in Studio**
-- Ensure the plugin is properly installed: `npm list sanity-translation-plugin`
-- Check that the plugin is added to your `sanity.config.ts` file
-- Restart your Sanity Studio development server
+-   Verify `npm install sanity-translation-plugin` completed successfully.
+-   Ensure `translationPlugin()` is in the `plugins` array in `sanity.config.ts`.
+-   Restart the Sanity Studio development server.
 
 **Translation action not visible**
-- The translate action only appears for documents with translatable content
-- Check browser console for any JavaScript errors
-- Ensure you're using Sanity Studio v3+
-
-**Console logs not appearing**
-- Open browser developer tools (F12)
-- Check the Console tab
-- Ensure log level is set to show all messages
-
-**Build errors during development**
-- Run `npm run clean` to clear build cache
-- Delete `node_modules` and run `npm install`
-- Check TypeScript version compatibility
-
-### Getting Help
-
-- Check the [documentation](./docs/) for detailed API information
-- Review [example implementations](./examples/) for reference
-- Open an issue on GitHub for bug reports or feature requests
-
-## API Reference
-
-### Plugin Configuration
+-   The action only appears on documents that have translatable fields defined in their schema.
 
-```typescript
-interface TranslationPluginConfig {
-  // Future configuration options will be added here
-  // Currently uses default placeholder endpoint
-}
-```
-
-### Content Extraction
-
-```typescript
-interface DocumentContent {
-  documentId: string;
-  documentType: string;
-  title: string;
-  htmlContent: string;
-  extractedAt: Date;
-}
-```
+**Authentication Issues**
+-   If using OAuth, check the **OAuth Configuration** tool to ensure your tokens are valid.
+-   If using local testing, ensure your mock translation service is running on the expected port.
 
-### Translation Request Format
+## Support
 
-```typescript
-interface TranslationRequest {
-  content: string;
-  format: 'html';
-  metadata: {
-    documentId: string;
-    documentType: string;
-    title: string;
-    sourceLanguage?: string;
-    targetLanguage?: string;
-  };
-}
-```
-
-### Translation Response Format
-
-```typescript
-interface TranslationResponse {
-  success: boolean;
-  translatedContent?: {
-    body: string;
-    title?: string;
-    slug?: string;
-    fields?: Record<string, any>;
-  };
-  error?: string;
-  requestId?: string;
-}
-```
+Our support team can be reached at support@easyling.com.
 
-### Translation-Invariant Fields
-
-The plugin now supports marking specific fields as translation-invariant using the `dnt` (Do Not Translate) flag. This is useful for fields that should not be translated, such as product IDs, dates, URLs, and other technical identifiers.
-
-```typescript
-import { ExtendedDocumentContent, TranslatableField } from 'sanity-translation-plugin';
-
-const content: ExtendedDocumentContent = {
-  documentId: 'product-123',
-  title: 'Premium Headphones',
-  htmlContent: '<p>High-quality wireless headphones</p>',
-  slug: 'premium-headphones',
-  fields: {
-    // Translatable field
-    description: {
-      value: 'Premium audio quality',
-      dnt: false
-    },
-    // Translation-invariant field
-    sku: {
-      value: 'HDPHN-001',
-      dnt: true  // This field will NOT be translated
-    },
-    price: {
-      value: 299.99,
-      dnt: true
-    }
-  }
-};
-```
-
-For backward compatibility, flat field values are automatically converted to the new structure with `dnt: false`.
-
-**See the [Translation-Invariant Fields Guide](./docs/translation-invariant-fields.md) for detailed documentation and examples.**
-
-#### Managing DNT Fields via Inline Badges
-
-The plugin displays **inline badges** on each translatable field in the document editor, allowing you to toggle DNT status with a single click:
-
-**Visual indicators appear below each field:**
-- **Green "Will Translate" badge** - Field will be translated ✓
-- **Red "Do Not Translate" badge** - Field will NOT be translated ⊘
-
-Simply click the badge to toggle the DNT status. Changes save automatically and apply during translation.
-
-**Supported field types**: string, text, number, url, email
-
-**See the [Inline DNT Badges Guide](./docs/inline-dnt-badges.md) for visual examples and detailed instructions.**
-
-#### Additional DNT Management
-
-For bulk operations, use the **"Manage Translation Fields" document action**:
-
-1. Open any document in Sanity Studio
-2. Click the document menu (three dots)
-3. Select "Manage Translation Fields"
-4. View all fields and clear DNT preferences if needed
-
-**See the [DNT Field Management Guide](./docs/dnt-field-management.md) for complete documentation.**
-
-## Contributing
-
-We welcome contributions! Please follow these steps:
-
-1. **Fork the repository** and create a feature branch
-2. **Install dependencies**: `npm install`
-3. **Make your changes** with appropriate tests
-4. **Run the test suite**: `npm test`
-5. **Lint your code**: `npm run lint`
-6. **Build the plugin**: `npm run build`
-7. **Submit a pull request** with a clear description
-
-### Development Guidelines
-
-- Follow TypeScript best practices
-- Add unit tests for new functionality
-- Update documentation for API changes
-- Use conventional commit messages
-- Ensure all tests pass before submitting
+**Note:** In order to investigate compatibility or interoperability issues, we may need access to your Sanity data lake and Studio codebase. We are happy to work with you to establish secure access for debugging purposes.
 
 ## License
 
 MIT License - see [LICENSE](LICENSE) file for details.
-
-## Changelog
-
-### v1.0.0
-- Initial release
-- Single document translation support
-- Bulk translation functionality
-- HTML content extraction
-- Portable text conversion
-- Comprehensive test coverage