Managing multilingual content traditionally requires coordinating with translation services or manual work for every content update—a time-consuming process that creates bottlenecks in content publication.

AI-powered translation changes this by providing instant, high-quality translations directly within your editing interface. Modern AI models understand context, preserve formatting, and produce natural-sounding translations that adapt to your content rather than mechanical word-for-word replacements.

The AI Translations plugin integrates leading AI providers—OpenAI (ChatGPT), Google (Gemini), Anthropic (Claude), and DeepL — directly into DatoCMS. Translate individual fields, entire records, multiple records from table views, or batch-translate whole models. The plugin intelligently handles complex field types including Structured Text, supports contextual translations for better accuracy, and preserves ICU Message Format patterns.

What you can do

The AI Translations plugin enables editors to:

• Translate individual fields: Use field-level actions to translate content from one locale to another or to all locales at once

• Translate entire records: Use the sidebar panel to translate all localizable fields in a record with a single action

• Bulk translate from table views: Select multiple records in any table view and translate them all simultaneously

• Translate whole models: Use the dedicated bulk translations page to translate all records across one or more models

• Work with multiple AI providers: Choose between OpenAI (ChatGPT), Google (Gemini), Anthropic (Claude), or DeepL based on your needs and preferences

• Preserve complex formatting: Automatically handle Structured Text, ICU Message Format patterns, HTML, and other complex field types

• Use contextual translations: Leverage record context for more accurate, consistent translations that understand specialized terminology

• Enforce terminology with glossaries: Use DeepL glossaries to ensure preferred translations for specific terms across all content

The plugin works with all DatoCMS field types including single-line strings, markdown, structured text, modular content, SEO fields, and media fields with metadata.

Requirements

• DatoCMS project with at least two locales configured

• API key from at least one supported provider:

  • OpenAI: Regular secret key from platform.openai.com

  • Google (Gemini): API key from GCP project with Generative Language API enabled

  • Anthropic (Claude): API key from console.anthropic.com

  • DeepL: API key (Free or Pro)

Installation

Install the AI Translations plugin from the DatoCMS Marketplace:

1. Navigate to your DatoCMS project

2. Go to Settings → Plugins

3. Click Add → From Marketplace

4. Search for "AI Translations"

5. Click Install on the AI Translations plugin

The plugin will appear in your project's plugin list and be ready for configuration.

Configuration

Access the plugin configuration screen from Settings → Plugins → AI Translations → Settings.

Choose your AI provider

Vendor selection: Select your preferred translation provider from the dropdown:

• DeepL (recommended): Fastest response times, professional translation quality, specialized for language translation with glossary support

• OpenAI (ChatGPT): Fast, widely available, excellent for general content

• Google (Gemini): Cost-effective with strong multilingual capabilities

• Anthropic (Claude): High-quality translations with nuanced understanding

Configure provider credentials

For OpenAI:

• OpenAI API Key: Paste your API key from platform.openai.com/api-keys

• GPT Model: Select your preferred model

For Google (Gemini):

• Google API Key: Paste your API key from Google Cloud Console

• Gemini Model: Select your preferred model

For Anthropic (Claude):

• Anthropic API Key: Paste your API key from console.anthropic.com

• Anthropic Model: Select from available Claude models for optimal quality

For DeepL:

• DeepL API Key: Paste your API key from deepl.com/pro-api

• Use DeepL Free endpoint: Enable if your key ends with :fx

• Formality: Choose translation formality level (default, more, less)

• Advanced settings: Configure glossaries and formatting options

Translatable field types

Select which field editor types should show translation actions:

• Single line string

• Markdown

• HTML Editor (WYSIWYG)

• Textarea

• Slug

• JSON

• SEO fields

• Structured Text

• Modular Content

• Media Fields (translates metadata like title, alt text)

Enable only the field types you need to translate. This keeps the interface clean and prevents accidental translations of fields that shouldn't change across locales.

Translation features

• Translate Whole Record: Enable the sidebar panel that translates all localizable fields in a record with one action

• Translate Bulk Records: Enable bulk translation from table views, allowing editors to select and translate multiple records simultaneously

• AI Bulk Translations Page: Enable the dedicated page for translating entire models at once (accessible from Settings → AI Bulk Translations)

Prompt customization

Prompt Template: Customize how the AI is instructed to translate content. Use placeholders:

• {fieldValue}: The content to translate

• {fromLocale}: Source language (e.g., "en-US")

• {toLocale}: Target language (e.g., "pt-BR")

• {recordContext}: Automatically generated context about the record

Default prompt:

Translate the following text from {fromLocale} to {toLocale}.
Preserve all formatting, HTML tags, and placeholder variables.
{recordContext}

Text to translate:
{fieldValue}

The {recordContext} placeholder provides the AI with information about other fields in the record, improving translation accuracy by understanding specialized terminology and maintaining consistency across related fields.

Access restrictions

• Models to exclude: Specify model API keys that should not show translation features

• Roles to exclude: Restrict which user roles can access translation features

• API Keys to exclude: Block specific API keys from using the plugin

Debugging

• Enable debugging: Turn on detailed console logging to troubleshoot translation issues

Security best practices

API key storage:

• Keys are stored in plugin settings and used client-side

• Never share your DatoCMS workspace publicly with API keys configured

• Rotate keys periodically

Key restrictions:

• OpenAI: Use regular secret keys, not publishable keys; set usage limits in your OpenAI dashboard

• Google: Restrict keys by HTTP referrer (https://admin.datocms.com/*) and enable only the Generative Language API

• Anthropic: Set spending limits in the Anthropic console

• DeepL: Set usage limits in your DeepL account dashboard

The plugin automatically redacts API keys from debug logs to prevent accidental exposure.

Using the plugin

Field-level translations

Translate individual fields directly in the record editor:

1. Open any record with localizable fields

2. Click the field's dropdown menu (three dots in the top-right corner of the field)

3. Select Translate to → Choose a target locale or All locales

4. The plugin generates the translation and updates the field automatically

Translate from a different source:

• Select Translate from → Choose a source locale

• The current locale's field will be filled with translated content from the selected source locale

This is useful when your primary content is in a locale other than the default, or when you want to translate from a recently updated locale.

Whole-record translations

Translate all localizable fields in a record at once:

1. Open a record that has multiple locales

2. The DatoGPT Translate panel appears in the sidebar (if enabled in settings)

3. Select your source locale (the locale containing the content to translate)

4. Select your target locale (the locale to translate into)

5. Click Translate Entire Record

6. All translatable fields update with AI-generated translations

This workflow is efficient for content editors who need to create complete translations for newly published content or update existing translations when source content changes.

Bulk translations from table view

Translate multiple records simultaneously from any model's table view:

1. Navigate to any model in the Content area

2. Switch to table view if not already displayed

3. Select multiple records by checking the boxes on the left

4. Click the three dots dropdown in the bottom bar

5. Choose Translate records

6. Select source and target locales

7. Click Start Translation

8. A progress modal shows translation status for all selected records

This is ideal for translating batches of content after bulk imports, when launching a new locale, or when updating multiple related records.

Bulk translations page

Translate entire models using the dedicated bulk translations page:

1. Go to Settings → AI Bulk Translations

2. Select your source locale (containing the content to translate)

3. Select your target locale (to receive translations)

4. Choose one or more models to translate

   • Block models are automatically excluded

   • Only models with localizable fields appear

5. Click Start Bulk Translation

6. The progress modal displays real-time status as records are processed

This workflow is designed for large-scale translation operations: launching new locales, migrating content, or keeping translations synchronized across your entire content base.

Contextual translations

The plugin supports context-aware translations through the {recordContext} placeholder in your prompt template.

How it works:

When translating a field, the plugin automatically generates a summary of other fields in the same record and includes it in the translation prompt. This gives the AI understanding of:

• Specialized terminology used in the record

• The overall topic and subject matter

• Related content in other fields

• Appropriate tone and style

Benefits:

• More accurate translations of technical terms and industry jargon

• Consistent terminology across all fields in a record

• Better understanding of context improves translation quality

• Appropriate formality and tone based on content type

ICU Message Format support

The plugin intelligently handles ICU Message Format strings, preserving complex pluralization and selection logic during translation.

Smart masking:

• Simple variables like {name} are masked (protected from translation)

• ICU structures like {count, plural, one {...} other {...}} are passed to the AI with explicit instructions to preserve the format

What gets translated:

The AI translates only the human-readable content inside ICU structures while preserving:

• Variable names and placeholders

• Keywords (plural, select, one, other, etc.)

• Structural syntax

• Number signs (#) and formatting codes

Example:

English:

You have {count, plural, one {# message} other {# messages}}

Portuguese translation:

Você tem {count, plural, one {# mensagem} other {# mensagens}}

The structure remains identical; only "message" and "messages" are translated to "mensagem" and "mensagens".

DeepL glossaries

When using DeepL as your translation provider, you can enforce preferred terminology through glossaries.

Requirements:

• DeepL API key with glossary access (check your plan)

• Glossary IDs from your DeepL account

Configuration:

1. Navigate to plugin settings → DeepL section

2. Expand Advanced settings

3. Configure glossaries: Default glossary ID: Used for all translations unless overridden Glossaries by language pair: Map specific language pairs to specific glossaries

Configuration examples:

Single language pair:

If you only translate from English to German:

• Default glossary ID: gls-12345 (your EN→DE glossary)

• Glossaries by language pair: (leave empty)

Multiple language pairs:

If you translate to multiple languages:

• Default glossary ID: (leave empty)

• Glossaries by language pair:EN->DE=gls-german123
EN->FR=gls-french456
EN->PT-BR=gls-portuguese789

Fallback strategy:

Use specific glossaries for main languages and a default for others:

• Default glossary ID: gls-fallback999

• Glossaries by language pair:EN->DE=gls-german123, EN->FR=gls-french456

Mapping syntax:

One entry per line. Supported formats:

EN->DE=gls-abc123
en-US->pt-BR=gls-xyz789
fr→it gls-123                 # alt arrow and delimiter
*->pt-BR=gls-777              # wildcard: any source to target
EN->*=gls-555                 # wildcard: source to any target
pt-BR=gls-777                 # shorthand for *->pt-BR

Creating glossaries:

Create and manage glossaries using the DeepL API (not through the plugin):

List existing glossaries:

curl -H "Authorization: DeepL-Auth-Key $DEEPL_AUTH_KEY" \
     https://api.deepl.com/v2/glossaries

Create a new glossary:

curl -X POST https://api.deepl.com/v2/glossaries \
  -H "Authorization: DeepL-Auth-Key $DEEPL_AUTH_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Marketing-EN-DE",
    "source_lang": "EN",
    "target_lang": "DE",
    "entries_format": "tsv",
    "entries": "CTA\tCall-to-Action\nlead magnet\tLeadmagnet"
  }'

Copy the returned glossary_id and paste it into the plugin settings.

Testing:

1. Create a small glossary with an obvious term

2. Add the glossary ID to plugin settings

3. Translate a field containing that term

4. Verify the glossary translation appears in the result

Workflow recommendations

For individual content updates:

• Use field-level translations for quick updates to specific fields

• Use whole-record translation when creating new localized versions

For launching new locales:

1. Configure the new locale in DatoCMS

2. Use the bulk translations page to translate all models at once

3. Review and refine translations in critical content

For ongoing content maintenance:

• Translate new records immediately after creation using whole-record translation

• Use bulk table view translations when updating multiple related records

• Enable debugging temporarily if you encounter translation issues

Quality optimization

Improve translation accuracy:

• Enable {recordContext} in your prompt template for context-aware translations

• Use glossaries (DeepL) to enforce preferred terminology

• Customize the prompt template to include industry-specific instructions

• Review AI-generated translations before publishing, especially for marketing copy

Handle special content types:

• Technical content: Use glossaries or custom prompts mentioning technical terminology

• Marketing copy: Consider using higher-quality models (e.g., gpt-4.1, gemini-2.5-pro)

• Legal content: Always have professional review; AI is a starting point, not final output

Troubleshooting

API key issues

Invalid API Key error:

• Verify the key matches the selected vendor

• Check that the key hasn't expired or been revoked

• Ensure there are no extra spaces or quotes around the key

• Test the key directly with the provider's API playground

Rate limit / quota errors:

• Reduce translation concurrency by translating smaller batches

• Switch to a lighter model (e.g., gpt-4o-mini, gemini-2.5-flash-lite)

• Check your provider's dashboard for usage limits

• Upgrade your plan if you consistently hit limits

Translation issues

Translations not appearing:

• Verify at least two locales are configured in your DatoCMS project

• Check that the field type is enabled in Translatable Field Types settings

• Ensure the field is set as localizable in the model schema

• Check browser console for errors (enable debugging in plugin settings)

Poor translation quality:

• Add {recordContext} to your prompt template for context-aware translations

• Try a more advanced model

• Customize the prompt template with specific instructions

• Use DeepL with glossaries for consistent terminology

Model not found:

• Verify the exact model ID exists for your account/region

• Check spelling and capitalization

• Refresh available models by re-entering your API key

DeepL-specific issues

Wrong endpoint error:

• Free keys (ending in :fx) require "Use DeepL Free endpoint" enabled in plugin settings

• Pro keys should have this setting disabled

Glossary not working:

• Verify the glossary ID exists in your DeepL account

• Check that glossary languages match your translation direction

• Ensure the glossary was created for the correct language pair

• Test with a known term from your glossary

Performance issues

Slow translations:

• Switch to faster models (gpt-4.1-mini, gemini-2.5-flash)

• Translate smaller batches instead of entire models at once

• Check your internet connection stability

• Verify you're not hitting rate limits (check provider dashboard)

Bulk operations timing out:

• Reduce the number of records per batch

• Translate one model at a time instead of multiple models

• Use a faster model for initial translations, then refine critical content manually

Limitations

• Browser-based execution: API keys are used client-side; keep workspaces private

• Locale configuration: Projects must have at least two locales for translations to function

• Field type support: Only configured field types show translation actions

• Provider availability: Translation quality and speed depend on selected provider and model

• Cost: Translation usage incurs costs from your chosen AI provider

• No translation memory: Each translation is independent; the plugin doesn't maintain a translation memory

• Manual review recommended: AI translations should be reviewed before publishing, especially for critical content