Sanity Translation Plugin

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 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

Install the plugin in your Sanity Studio project:

npm install sanity-translation-plugin

Add the plugin to your sanity.config.ts file:

import { defineConfig } from 'sanity'
import translationPlugin from 'sanity-translation-plugin'

export default defineConfig({
  // ... your other config
  plugins: [
    // ... other plugins
    translationPlugin()
  ]
})

Configuration

Authentication & Connection

The plugin supports two modes of operation:

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.

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.

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.

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.

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.

Defaults

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.
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 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.

Managing Translatable Fields

Sometimes you need to keep specific fields (like product codes, technical IDs, or proper names) from being translated.

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.

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

Plugin not appearing in Studio

• 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 action only appears on documents that have translatable fields defined in their schema.

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.

Support

Our support team can be reached at [email protected].

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 file for details.