Ray Enterprise Translation
Enterprise-grade translation management module that integrates Drupal with the Ray Enterprise (formerly Lingotek) cloud-based Translation Management System (TMS).
lingotek
Install
composer require 'drupal/lingotek:^11.0'
composer require 'drupal/lingotek:^4.1'
Overview
Ray Enterprise Translation provides comprehensive translation management capabilities for Drupal sites, enabling seamless integration with the Lingotek cloud-based Translation Management System. The module supports translation of content entities (nodes, taxonomy terms, media, etc.), configuration entities (views, blocks, menus), and user interface strings.
The module offers flexible translation workflows through customizable profiles that can be set to automatic (hands-off translation), manual (user-controlled), or disabled modes. Each profile can have language-specific overrides and Intelligence Metadata enrichment for tracking content lifecycle and business context.
Key capabilities include bulk translation operations, real-time status monitoring via webhooks, job-based translation grouping, and deep integration with Drupal's content moderation systems. The module provides a visual dashboard for managing all translation activities and supports advanced features like related entity detection, paragraph/media translation, and Layout Builder integration.
Features
- Upload content entities to Lingotek TMS for professional translation with automatic or manual workflows
- Download completed translations and automatically create translated content versions
- Configure translation profiles with customizable automation settings (auto-upload, auto-request, auto-download)
- Translate configuration entities including views, blocks, menus, and custom config types
- Translate Drupal interface strings (UI text) from themes, modules, and installation profiles
- Bulk management interface for mass translation operations across multiple entities
- Real-time translation status tracking via webhook notifications from the TMS
- Job-based translation grouping for organizing and tracking related translations
- Intelligence Metadata enrichment for adding business context to translations (author, campaign, business unit, etc.)
- Visual translation dashboard showing language coverage and status at a glance
- Language-specific profile overrides for granular control per target language
- Target locking to prevent accidental overwrites of finalized translations
- Integration with Content Moderation and Workbench Moderation workflows
- Drush commands for CLI-based translation operations
- Related entity detection for translating embedded content (paragraphs, media, block references)
- Support for advanced field types including Layout Builder, Metatag, Paragraphs, and Cohesion
Use Cases
Automated Content Translation Workflow
For sites with high content volume, configure the Automatic profile to handle translation without manual intervention. When content is created or updated, it automatically uploads to Lingotek, requests translations for all enabled languages, and downloads completed translations. This is ideal for news sites, e-commerce catalogs, or any site where content needs to be translated quickly across multiple languages with minimal editorial oversight.
Editorial Review Translation Workflow
For sites requiring editorial control, use the Manual profile. Content editors manually trigger uploads when content is ready for translation, review translation requests before sending, and download translations only after verification. This suits legal, medical, or regulated content where accuracy must be verified before publication.
Selective Translation by Content Type
Configure different profiles for different content types. Product pages might use Automatic profile for quick turnaround, while legal pages use Manual profile for careful review. Blog posts might use a custom profile with auto-upload but manual download for editorial review of translations.
Job-Based Translation Management
Group related translations using Job IDs for project management. Create a job for a product launch with all related content (landing pages, product descriptions, marketing materials), track progress across the entire job, and ensure all pieces are completed before launch.
Intelligence Metadata for Translation Analytics
Enable Intelligence Metadata to track translation costs and performance by business unit, campaign, or region. Configure metadata per profile to allocate translation costs correctly and analyze which content types or campaigns require the most translation investment.
Multi-Region Content Strategy
Use language-specific profile overrides to route translations to different workflows based on target market. European languages might use one translation vendor/workflow, while Asian languages use another specialized vendor. Different vaults can store region-specific Translation Memory.
Configuration Translation for Multi-Language Sites
Translate not just content but also site configuration: menu names, block titles, view displays, and field labels. Enable configuration translation in settings and manage via the Config translation management page to ensure the entire user experience is localized.
Interface Translation for Custom Modules
Use the Interface Translation feature with potx module to extract and translate UI strings from custom modules and themes. This ensures custom development is fully localized alongside contributed and core translations.
Paragraph-Heavy Content Sites
For sites using Paragraphs module extensively, enable paragraph bulk management in Integrations settings. The related entity detection automatically identifies paragraphs needing translation and can manage them as part of the parent content or separately.
Target Locking for Finalized Translations
Use the new Target Lock feature to lock translations after final review. This prevents accidental overwrites when source content is updated, protecting finalized translations from being replaced with new machine translations until explicitly unlocked.
Tips
- Use the Dashboard regularly to monitor translation coverage across languages - it provides quick visual feedback on overall translation status
- Create custom profiles for different content workflows rather than constantly changing profile assignments on individual content
- Enable Interaction Logging temporarily when troubleshooting API issues - it provides detailed request/response logs but generates significant log volume
- Use Job IDs to group related content for campaigns or projects - this makes tracking and reporting much easier
- Configure language-specific workflow overrides when different target languages have different quality requirements or vendor preferences
- The 'Split Download All' preference can improve reliability for large translation batches by processing one language at a time
- Enable the queue worker for auto-downloads on high-traffic sites to prevent translation downloads from impacting page response times
- Use the target lock feature for regulatory or legal content where translations must be reviewed and finalized before any updates
- Test webhook connectivity by uploading a single test document and verifying the status updates automatically
- Consider using Intelligence Metadata even if not required - the data helps with translation cost analysis and vendor management over time
Technical Details
Admin Pages 11
/admin/lingotek
Main dashboard providing an overview of translation status across all languages. Shows visual representation of content translation coverage for each enabled language with color-coded status indicators. Supports adding/removing target languages and viewing translation progress at a glance.
/admin/lingotek/settings
Comprehensive settings page with multiple tabs for configuring all aspects of the Lingotek integration including account settings, content types, configuration, profiles, Intelligence Metadata, preferences, integrations, and utilities.
/admin/lingotek/manage
Bulk management interface for content entity translations. Provides filtering, selection, and batch operations for managing translations across multiple entities simultaneously.
/admin/lingotek/config/manage
Bulk management interface for configuration entity and object translations. Similar to content management but for configuration items like views, blocks, field configurations, etc.
/admin/lingotek/manage/interface-translation
Interface for managing translation of Drupal UI strings from modules, themes, and installation profiles. Requires the potx module for extracting translatable strings.
/admin/lingotek/jobs
View and manage translation jobs. Jobs group related translations together for tracking and organization purposes.
/admin/lingotek/job/{job_id}/content
View and manage content entities within a specific translation job. Shows filtered view of content management with job pre-selected.
/admin/lingotek/job/{job_id}/config
View and manage configuration items within a specific translation job.
/admin/lingotek/settings/profile/add
Create a new custom translation profile with specific automation settings, TMS defaults, Intelligence Metadata overrides, and per-language customizations.
/admin/lingotek/setup/account
Initial setup page for connecting to a Lingotek account. Provides options for existing accounts (enter access token) or creating new accounts (free or enterprise signup).
/admin/lingotek/supported-locales
Reference page listing all locale codes supported by Lingotek with their mappings to Drupal language codes.
Permissions 3
Hooks 8
hook_lingotek_content_entity_translation_presave
Allows modules to alter content entity translation data before it is saved after download from Lingotek
hook_lingotek_content_entity_document_upload
Allows modules to alter the document data before it is uploaded to Lingotek TMS
hook_lingotek_content_entity_get_profile
Allows modules to override the translation profile for a content entity
hook_lingotek_config_entity_translation_presave
Allows modules to alter configuration entity translation data before saving
hook_lingotek_config_entity_document_upload
Allows modules to alter configuration entity document before upload
hook_lingotek_config_object_translation_presave
Allows modules to alter simple configuration object translation data before saving
hook_lingotek_config_object_document_upload
Allows modules to alter simple configuration object data before upload
hook_form_lingotek_management_form_alter
Standard Drupal form alter hook for customizing the Lingotek management form
Drush Commands 5
drush lingotek:upload
Upload a content entity to Lingotek TMS for translation
drush lingotek:check-upload
Check the upload status of a content entity in Lingotek
drush lingotek:request-translations
Request translations for a content entity from Lingotek
drush lingotek:check-translations-statuses
Check translation statuses for a content entity
drush lingotek:download-translations
Download completed translations for a content entity
Troubleshooting 10
Verify the translation profile has auto_download enabled. Check that the Lingotek notification callback URL is correctly configured (visible in Settings > Utilities). Ensure cron is running regularly if using queue worker for downloads. Check Drupal logs for any API errors.
Confirm the content type has Lingotek translation enabled in Settings > Content. Verify the profile assigned is not 'Disabled'. Check that the entity has a source language set and content translation is enabled for the bundle. Review API logs (enable Interaction Logging in Settings > Logging).
Navigate to Settings > Account and use 'Edit Defaults' or 'Update Access Token' to enter a new valid access token from your Lingotek account.
Check that specific fields are enabled for Lingotek translation in Settings > Content > [Content Type] > Edit. Some field types require specific field processors - verify the field type is supported.
Verify the callback URL is accessible from the internet (check firewall settings). The URL shown in Settings > Utilities must be reachable by Lingotek servers. Use 'Update Notification Callback URL' to refresh the registration.
The profile is in use. Check for content using this profile in the management interface (filter by profile). Also check content type settings where the profile may be set as default. Change all usages before deletion.
Enable configuration translation for specific config types in Settings > Configuration. Only enabled configuration mappers appear in the management interface.
Install and enable the potx module: composer require drupal/potx && drush en potx. The Interface Translation feature depends on potx for extracting translatable strings.
Enable 'Enable bulk management of paragraphs' in Settings > Integrations. Ensure paragraphs have content translation enabled at the paragraph type level. Check that the paragraph reference field is marked for Lingotek translation.
Before switching environments (dev to staging to production), use the 'Disassociate All' utility in Settings > Utilities to remove all local Lingotek associations. This prevents the new environment from creating duplicate documents in the TMS.
Security Notes 6
- The 'administer lingotek' permission provides full access to all Lingotek features including account disconnection and metadata deletion - grant only to trusted administrators
- API access tokens should be treated as sensitive credentials - they provide full access to your Lingotek TMS account
- The webhook endpoint (/lingotek/notify) is publicly accessible but validates requests are from Lingotek - ensure your server's firewall allows incoming requests from Lingotek IP ranges
- Translation profiles can be configured to auto-publish translations - consider implications for content workflows and whether translations should require editorial review before publication
- When using Intelligence Metadata with contact information, be aware this data is sent to and stored in the Lingotek TMS
- Disassociating all translations is a significant operation that cannot be undone - use with caution and preferably with a database backup