Search by

recranet / craft-ai-translator

recranet

AI-powered content translation for Craft CMS (Claude, OpenAI, DeepL)

Package info

github.com/recranet/craft-ai-translator

Type:craft-plugin

pkg:composer/recranet/craft-ai-translator

Statistics

Installs: 121

Dependents: 0

Suggesters: 1

Stars: 0

1.2.0 2026-10-06 12:14 UTC

This package is auto-updated.

Last update: 2026-11-16 16:29:19 UTC


README

AI-powered content translation for multi-site Craft CMS installations. In-house replacement for the Multi Translator plugin.

Features

  • Providers: Claude (Anthropic), OpenAI (GPT) and DeepL behind a single interface — switch in the plugin settings
  • Element types: entries, categories and global sets
  • Bulk element action: select entries/categories in any index → "Translate with AI" → choose target sites; translations run as queue jobs
  • Sidebar button: translate the entry/category you're editing from any other site in one click
  • Per-field buttons: a small "Translate" button on Plain Text, CKEditor and Redactor fields (shown when editing a non-primary-language site)
  • Utility: translation status per section/site (translated, outdated, missing) plus bulk translate forms for sections, category groups and globals (Utilities → AI Translator)
  • Supported content: titles, Plain Text, CKEditor/Redactor (HTML structure preserved), Matrix (recursive, incl. nested Matrix), SEOmatic meta title/description/keywords
  • Translation tracking: every run stores a per-field hash of the source; later runs only re-translate fields whose source changed, and outdated translations are surfaced in the utility
  • Draft or direct save: per action, editors choose whether translations land as a draft (review first) or are saved directly; repeated draft runs reuse the same draft
  • Skip or overwrite: fields that were manually translated (deviating target without a tracking record) are left alone; overwrite mode replaces everything
  • Slug updates: slugs are regenerated from the translated title (configurable)
  • Resilient: transient provider failures (rate limits, timeouts, malformed output) are retried with backoff
  • Glossary & tone of voice: brand terms that must never be translated, and free-form style instructions (Claude/OpenAI only)

Requirements

  • Craft CMS 5.0+
  • A multi-site install with sites in different languages
  • An API key for at least one provider

Installation

composer require recranet/craft-ai-translator
php craft plugin/install ai-translator

Configuration

Settings → Plugins → AI Translator:

Setting Description
Provider Claude, OpenAI or DeepL
API key Supports env vars, e.g. $ANTHROPIC_API_KEY
Model Model id for Claude/OpenAI (defaults: claude-sonnet-5, gpt-4o-mini)
Glossary Terms that must never be translated, one per line
Tone of voice Extra prompt instructions (e.g. "Gebruik informele aanspreekvorm")
Default save mode Draft or direct save (editors can override per action)
Overwrite by default Whether existing translations are replaced
Batch size Max texts per API request

Grant the Translate content with AI permission to the user groups that may translate.

Permissions

ai-translator:translate only grants access to the tool. Every translation is additionally checked against the acting user's own element permissions: they must be able to view the element in the source site and save it (or create drafts for it) in the target site, including editSite access to both. Queued jobs re-check at execution time, so revoking access also stops jobs that are already queued. The utility only lists sections, category groups, global sets and sites the user can edit.

How field skipping works

Without overwrite:

  • Fields previously translated by the plugin (tracked via a source-value hash) are re-translated only when the source changed since — note this replaces any manual edits made to the AI translation of that field. Draft-mode and direct-save translations are tracked separately, so content that only exists in a draft never makes the live element look translated.
  • Fields never translated by the plugin are translated when the target is empty or still an untranslated copy of the source; a deviating target is assumed manually translated and skipped.

Drafts on multi-site installs

A Craft draft is a snapshot of the element in every site, and applying it writes all of those site copies back to the live element. Craft merges intervening live changes into the draft first, but that merge misses edits to Matrix blocks that were also touched in the draft — even when the draft touched them in a different site (craftcms/cms#9962, reproduced on Craft 5.11). An AI translation draft touches every translated block in the target site, so without countermeasures a concurrent live edit of such a block in another site would be lost when the draft is applied.

The plugin therefore treats a translation draft as a change to its target site only. Right before Craft applies one of its drafts (and before it writes into a draft left over from an earlier run), every other site copy in the draft tree — the draft itself and each nested block draft under it — is rewritten from the live element. Applying then writes those sites back unchanged, while the target site receives the translation.

What this does not cover:

  • Edits made in the target site itself between the translation run and the apply, in fields the AI also wrote: the draft's value wins, as with any Craft draft. Fields the AI left alone are merged by Craft's own canonical merge where it works.
  • Drafts created by editors (including Craft's provisional autosave drafts). The general concurrent-editing problem is Craft's, not the plugin's; CRAFT_AUTOSAVE_DRAFTS=false in .env is the common workaround (deprecated since Craft 4.0 but still functional).

Known limitations

  • Supported top-level elements: entries, categories, global sets (Matrix nested entries are handled recursively).
  • Global sets are always saved directly; Craft doesn't support drafts for globals.
  • Table fields are not translated.
  • DeepL ignores the glossary and tone-of-voice settings (no prompt support); HTML is handled via DeepL's native tag_handling.
  • SEOmatic fields inside Matrix blocks are not translated.

Development

composer install
composer test