AI Translations

Translate your DatoCMS content into every locale of your project with DeepL, OpenAI, Google Gemini, Anthropic Claude or Yandex Translate. Translate a single field, a whole record, a selection of records or entire models, without leaving DatoCMS.

• Translate one field into one locale or all of them, from the field's menu
• Translate a whole record from its sidebar, and review the result before saving
• Translate many records at once: a selection from a table, or every record of the models you pick
• Five providers: DeepL, OpenAI, Google Gemini, Anthropic Claude and Yandex Translate
• Rich content included: HTML, Markdown, Structured Text, blocks, SEO fields and image alt text
• Publish in one click after a bulk run, for models with draft/published

Installation

Install AI Translations from Configuration → Plugins and, when asked, let it use the current user's API token. Bulk translations need it to read and save records. Without it, the table action and the Bulk translations page can't run.

Then open the plugin settings, pick an AI Vendor, enter its credentials and click Save. Your project needs at least two locales.

Choose a provider

DeepL is the fastest and cheapest option, and it's what we recommend for most projects. OpenAI, Gemini and Claude are language models: they also get the record's title and other short text fields as context, which helps with tone and terminology, and you can edit the Translation prompt they follow.

The same page lets you choose the Fields that can be translated and turn the sidebar panel or the table action off. Turn on Show exclusion rules to hide the plugin from some models or roles, or to skip specific fields. DeepL glossaries, the prompt and the other provider options are described in docs/Providers.md.

Translate a field

Open the menu at the top right of a localized field, choose Translate to, then a locale or All locales. Translate from works the other way round: it fills the locale you're on with a translation of another locale.

The translation goes into the form, so review it and click Save. Translate to only appears once the field has content in the locale you're on.

Translate a whole record

The AI Translations panel in the record sidebar translates every translatable field at once.

1. Pick the From locale and the To locales. All the other locales are selected by default.
2. Click Translate all fields. Each field and locale shows up in the panel as it's translated. Click one to jump to that field.
3. Review the translations in the form and click Save.

Cancel stops the run. Fields that were already translated stay in the form.

Translate records from a table

1. Open a model's records, select the ones to translate, then open the ⋮ menu in the bar at the bottom and choose AI Translate these records.
2. In Translate records, pick the Source locale and the Target locales (All other locales by default). Then pick the fields to translate for each model (All fields by default).
3. Click Translate N records, check the summary and confirm.
4. The Translation progress dialog follows each record. See Understanding the results.

Unlike the field menu and the sidebar, bulk translations save each record as soon as it's translated. In models with draft/published, the changes stay unpublished until you publish them.

Translate whole models

Open Configuration → Bulk translations, under AI Translations in the sidebar. Only roles that can edit the schema see it.

Pick the locales, then the Models to translate: every record of those models is translated. Each model gets its own field picker, with all its translatable fields selected. Click Translate records, confirm, and follow the run in the same Translation progress dialog. If the button is disabled, hover it to see what's missing.

Block models aren't listed, because blocks are translated together with the records that contain them.

Understanding the results

The progress dialog counts successful and failed records as the run goes. Each row links to its record, which opens in a new tab. Hover a row to see the details of a warning or an error. Cancel stops the run, and records that were already saved stay translated.

Why are linked records copied? A link field points to other records, which are the same in every locale, so the plugin never translates it. When a bulk run fills a locale for the first time, it copies the links from the source locale so the record stays valid, for example when the field requires at least one linked record. The linked records themselves aren't translated. The warning lets you check whether the new locale should link to different records.

Publishing. When the run ends, Publish all translated records (N) publishes every record that was updated, if its model uses draft/published. If publishing stops partway, click Retry publishing remaining (N).

Good to know

• What gets translated: localized fields of the types picked in Fields that can be translated: single-line strings, textareas, Markdown, HTML, slugs, JSON, SEO, Structured Text, Modular Content, and the alt text and title of media. All types are on by default. Fields that aren't localized are never changed.
• Translations replace what's there. Translating into a locale overwrites the content it already has in the selected fields.
• Linked records stay the same. Link fields are never translated, and neither are the records they point to.
• SEO limits: translated SEO titles longer than 60 characters and descriptions longer than 160 are cut short and end with "...".
• API keys are saved in the plugin settings and used from each editor's browser, so treat them as visible to your team. Use a dedicated key, and restrict it where the provider allows, such as a Google key limited to the Generative Language API.
• DeepL glossaries: open Glossary Settings in the DeepL settings to apply your DeepL glossaries, as a Default glossary or for specific language pairs. If a glossary doesn't match the languages being translated, the text is translated without it.
• Yandex Translate accepts at most 10,000 characters per piece of text. A longer field, such as a long HTML or Markdown text, fails with an error asking you to shorten it.
• Two locales or more: translation actions need a second locale in the record, and in the environment for bulk runs.
• Debug logging: Enable debug logging prints each translation request and response to the browser console, with API keys hidden.

Development

From this directory:

1
npm ci
2
npm run dev
3
npm test
4
npm run lint
5
npm run build

Connect the development URL to a test project using the DatoCMS plugin development workflow. The release history is in the changelog.