@easyling/sanity-connector 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Sanity Translation Plugin
+
+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,482 @@
+# 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.
+
+## 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
+
+## Installation
+
+Install the plugin in your Sanity Studio project:
+
+```bash
+npm install sanity-translation-plugin
+```
+
+Add the plugin to your `sanity.config.ts` file:
+
+```typescript
+import { defineConfig } from 'sanity'
+import translationPlugin from 'sanity-translation-plugin'
+
+export default defineConfig({
+  // ... your other config
+  plugins: [
+    // ... your other plugins
+    translationPlugin()
+  ]
+})
+```
+
+## 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.
+
+### Basic Configuration
+
+```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"
+}
+```
+
+## Translation Service Integration
+
+This plugin requires an external translation service that implements the specified API format. 
+
+### Quick Start with Example Service
+
+1. **Start the example translation service:**
+   ```bash
+   cd examples
+   npm install
+   npm start
+   ```
+
+2. **Configure the plugin** to use `http://localhost:8275/translate` as the endpoint
+
+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"
+}
+```
+
+## 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
+```
+
+### 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
+
+- **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
+
+### User Interface Components
+
+- **Document Actions** (`src/actions/translateDocument.ts`)
+  - Adds translate button to document toolbar
+  - Handles single document translation workflow
+  - Provides user feedback and error handling
+
+- **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)
+
+## 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
+
+**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
+
+```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;
+}
+```
+
+### Translation Request Format
+
+```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;
+}
+```
+
+### 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
+
+## 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