AI Translate

When to Use

Status: DEPRECATED — moving to standalone drupal/ai_translate project. No replacement has been announced. See https://www.drupal.org/node/3570275 for the migration plan. This guide covers the module as it exists in AI 1.3.5.

Decision

Situation	Choose	Why
Translate UI strings	ai_translate + locale	AJAX button per string on translation pages
Translate content fields	ai_translate + content_translation	"AI Translations" column on overview
Bulk translation	Drush commands	drush ai:translate-entity
Per-language model	language_settings config key	Override model/prompt per target language

Config: ai_translate.settings

Key	Default	Description
use_ai_translate	true	Override translate tab with AI links
entity_reference_depth	1	Max recursion for references (0=unlimited)
translation_status	keep_original	keep_original or create_draft
redirect_after_create	list	list or edit
language_settings	{}	Per-language model/prompt overrides

Drush Commands

drush ai:translate-entity node "1,2,3" en fr  # Translate specific nodes to French
drush ai:translate-text "Hello world" en fr    # Translate a text string

Alter Hook

hook_ai_translate_translation_alter(&$messages, &$provider_id, &$model_id)

ChatTranslationProvider

The module wraps the AI chat operation to implement the translate_text operation type. ChatTranslationProvider takes text, source language, and target language, constructs a chat prompt, and returns the translated text. Allows any chat provider to serve as a translation backend.

Custom FieldTextExtractor

#[FieldTextExtractor(
  id: 'my_field',
  label: new TranslatableMarkup('My Field'),
  field_types: ['my_field_type'],
)]
class MyFieldExtractor extends FieldExtractorBase {
  public function getColumns(): array { return ['value', 'extra']; }
}

Built-in FieldTextExtractor Plugins

Plugin	Field Types	Translates
text	title, text, string	value
text_with_summary	text_with_summary	value, summary
link	link	title
image	image	alt, title
layout_builder	layout_section	Inline blocks (symmetric + asymmetric)
entity_reference	entity_reference	Referenced entities recursively

Entity Reference Translation

Per-field translation of referenced entities is controlled via third-party settings on entity reference fields: ai_translate:translate_references. When enabled, the translator recursively processes referenced entities up to entity_reference_depth levels.

Common Mistakes

• Wrong: Setting entity_reference_depth: 0 without performance testing → Right: Unlimited depth can translate the entire entity graph recursively; set conservatively
• Wrong: Using ai_translate for new projects → Right: Module is deprecated; plan for the standalone replacement

See Also

• AI Module Core Architecture
• Reference: web/modules/contrib/ai/modules/ai_translate/
• Deprecation issue: https://www.drupal.org/node/3570275