Google Translate Integration for dotCMS

Native integration that enables automatic content translation across language versions through workflow automation, powered by the Google Cloud Translation API.

What It Does#

The Google Translate integration in dotCMS automatically translates content from one language into all other configured language versions in your instance. When a content editor triggers a workflow action with the "Translate Content" sub-action, dotCMS sends the translatable text fields to the Google Translation API and creates translated copies of the content in each target language.

Key capabilities:

• One-click translation to all installed languages or specific language codes
• Translates Text, WYSIWYG, and Textarea fields automatically
• Binary fields and Tags are copied as-is to translated versions
• API key configurable per-site via Apps or globally via config property
• Recursive translation protection (translated content won't re-trigger translation)
• Source content publish state is preserved in translated versions

What it does not do:

• Does not translate Binary fields, Tag fields, or Category fields
• Does not translate Block Editor fields by default (must be added manually)
• Does not auto-publish unless the source content was live

Prerequisites#

1. dotCMS instance with multiple language versions installed
2. Google Cloud Platform account with billing enabled
3. Google Cloud Translation API enabled
4. API Key from Google Cloud Console

Google Cloud Setup#

Step 1: Enable Cloud Translation API#

1. Go to Google Cloud Console
2. Select or create a project
3. Go to APIs & Services → Library
4. Search for "Cloud Translation API"
5. Click Enable

Step 2: Create an API Key#

1. Go to APIs & Services → Credentials
2. Click Create Credentials → API Key
3. Copy the generated API key
4. (Recommended) Click Restrict Key:
   • Under API restrictions, select Cloud Translation API
   • Click Save

dotCMS Configuration#

Step 1: Install Language Versions#

The integration translates content into all installed languages. Make sure your target languages are configured:

1. Go to Settings → Languages
2. Click Add Language for each target language
3. Save

Step 2: Configure the Google Translate App#

1. Go to Settings → Apps
2. Find Google Translation in the list
3. Click to configure
4. Select your site (or System Host for global configuration)
5. Enter your Google Service API Key
6. Click Save

API key resolution order:

1. Value entered directly in the workflow sub-action parameters
2. Apps configuration for the current site
3. Apps configuration for System Host
4. GOOGLE_TRANSLATE_SERVICE_API_KEY property in dotmarketing-config.properties

Step 3: Create the Translation Workflow#

1. Go to Settings → Workflow Schemes
2. Create or edit a workflow
3. Add a workflow action (e.g., "Translate to All Languages")
4. Add the Translate Content sub-action
5. Configure the sub-action parameters:

1. Important: Place the Translate Content sub-action after a Save sub-action. The source content must be persisted before translation runs.

Recommended sub-action order:

1. Save Content
2. Translate Content
3. (Optional) Push Publish

Step 4: Assign Workflow to Content Type#

1. Go to Content Types
2. Select the content type to enable translation for
3. Go to the Workflow tab
4. Assign the workflow scheme containing your translation action
5. Click Save

Usage#

Translating Content#

1. Create or edit content in your primary language
2. Fill in all fields
3. Click Save (or use a Save action first)
4. Click the workflow action button (e.g., "Translate to All Languages")
5. dotCMS sends text fields to Google Translation API
6. Translated content versions are created for each target language
7. Switch the language selector in the content editor to view each translation

What Gets Translated#

Including Block Editor Fields#

To include Block Editor fields, update the Translate Field Types parameter in the sub-action:

text,wysiwyg,textarea,block_editor

Targeting Specific Languages#

Instead of translating to all languages, specify language codes:

es,fr,de,pt

Language codes must match the language codes of installed language versions in your dotCMS instance.

Using Ignore Fields#

To exclude specific fields from translation, add their variable names to Ignore Fields:

internalNotes,seoMetadata,urlTitle

How It Works Under the Hood#

When the Translate Content sub-action runs:

1. Validates source content is saved and retrievable
2. Identifies translatable fields based on fieldTypes and ignoreFields params
3. Resolves target languages from translateTo param against installed languages (excludes source language)
4. Calls Google Translation API (translation.googleapis.com/language/translate/v2) for each target language
5. Creates translated contentlets with translated text fields
6. Copies binary files and tag values from source to each translated version
7. Saves and optionally publishes translated versions (mirrors source content's live state)
8. Unlocks the source contentlet

The integration uses the Google Translation REST API v2 directly via HTTP POST — not the Google Cloud SDK.

Troubleshooting#

"No API Key Found"#

Cause: No API key is configured anywhere in the resolution chain.

Solution:

• Go to Settings → Apps → Google Translation
• Add your API key for the site or System Host
• Save

"Content must be persisted first"#

Cause: The Translate Content sub-action ran before the content was saved.

Solution:

• In your workflow action, ensure a Save Content sub-action appears before Translate Content

"No Fields to translate"#

Cause: The Translate Field Types parameter doesn't match any fields in the content type.

Solution:

• Check the field types in your content type
• Update the Translate Field Types parameter to match (e.g., add wysiwyg if that's the field type being used)

Translation not appearing for a language#

Cause: The language code in translateTo doesn't match an installed language.

Solution:

• Go to Settings → Languages and note the exact language codes installed
• Update the translateTo parameter to match

API quota or billing errors#

Cause: Google Cloud billing is not enabled, or the API quota has been exceeded.

Solution:

• Verify billing is enabled in Google Cloud Console
• Check API usage under APIs & Services → Cloud Translation API → Quotas

Technical Details#

Code locations in dotCMS/core:

• Workflow Actionlet: dotCMS/src/main/java/com/dotmarketing/portlets/workflows/actionlet/TranslationActionlet.java
• Translation Service: dotCMS/src/main/java/com/dotcms/translate/GoogleTranslationService.java
• App Config: dotCMS/src/main/resources/apps/dotGoogleTranslate-config.yml

API endpoint used:

POST https://translation.googleapis.com/language/translate/v2?key={apiKey}

Request payload:

{
  "q": ["Text to translate"],
  "source": "en",
  "target": "es"
}

Resources#

• dotCMS Documentation: Translate Content Sub-Action
• Google Cloud Translation API: Documentation
• Supported Languages: Language Support
• dotCMS Source: dotCMS/core on GitHub

Next Steps#

This guide will be used as the basis for:

1. Google Translate integration page on dotcms.com
2. Updated documentation on dev.dotcms.com/docs