Extending the translation system

This section covers how developers can extend the translation system to integrate with custom translation providers or add custom functionality.

Architecture overview

The translation system is designed to provide common translation tooling out of the box while providing extensibility where needed. Here are the core components that can be extended:

Component	Purpose	Guide
Translation Service	Integration point for translation providers	Building a Translation Service
Translation Data Converter	Packages content for translation and applies results	Below
Completion Action	Defines post-translation behavior	Building a Completion Action
Translation Action	Custom UI components on the Translations tab	Building a Translation Action
Site Assignment Option	Controls which site owns translated content	Below
Translation Permission Provider	Custom permission settings for roles	Below
Translation References Page	Customizes referenced content selection UI	Below
Rich Text Preprocessor	Preprocesses rich text before translation	Below

Translation lifecycle

Understanding the translation lifecycle is essential for building custom integrations. Here's the typical code path when translating content:

1. User initiates translation

A user initiates the translation request via the content edit page menu, which triggers TranslateAction.java.

2. Translation request page

TranslationRequestPage.java displays in a CMS pop-up where the user:

1. Selects a source locale (if not set) and translation service
2. Selects target locales (determined by TranslationService#getSupportedLocales)
3. Optionally selects referenced content to translate
4. Reviews and clicks translate

3. Translation context construction

A TranslationContext.java object is constructed containing:

• Site, user, service, source locale, target locales
• Items to be translated
• TranslationData.java objects created via TranslationDataConverter.java

4. Translation service execution

TranslationService#translate is called with the context. The service:

1. Processes the translation (synchronously or asynchronously)
2. Produces TranslationLog.java objects for each translation
3. Sets initial status to TranslationStatus#PENDING

5. Waiting for Completion

How translated data is received depends on the service implementation:

• Repeating tasks polling for completion
• Webhooks receiving callbacks
• Synchronous completion in the translate method

6. Translation Data Received

When translation completes:

1. The service converts raw data to TranslationData.java
2. TranslationService#completeTranslation is called
3. TranslationDataConverter#copyTranslatedDataOntoObject applies data to content
4. LocalizationData.java metadata connects translated content to source
5. TranslationCompletionAction#completeTranslation finalizes the content
6. TranslationLog#status is set to success

Extension Points

• Translation Services — Build integrations with third-party translation providers
• Completion Actions — Custom logic when translations complete
• Translation Actions — Custom UI elements on the Translations tab

Translation Data Converter

The TranslationDataConverter transforms content for translation services and applies results back to Brightspot content. The default implementation handles most use cases.

When to Implement a Custom Converter

Implement a custom converter when you need to:

• Transform specific field types differently — For example, extracting only certain parts of a complex field
• Handle custom data structures — When your content has nested or embedded objects that need special handling
• Integrate with services requiring specific data formats — Some services expect XML, specific JSON structures, or proprietary formats
• Exclude fields from translation — When certain fields should never be translated
• Add metadata to translation payloads — For tracking or service-specific requirements

Implementation

1. Implement the TranslationDataConverter interface:

1
public class CustomTranslationDataConverter implements TranslationDataConverter {
2

3
    @Override
4
    public void initialize(String settingsKey, Map<String, Object> settings) {
5
        // Initialize converter with settings if needed
6
    }
7

8
    @Override
9
    public TranslationData constructTranslationData(Recordable content) {
10
        // Extract translatable fields from content
11
        // Return a TranslationData object with field paths mapped to values
12
        return null;
13
    }
14

15
    @Override
16
    public void copyTranslatedDataOntoObject(
17
            Recordable content,
18
            TranslationData data,
19
            TranslationLog log) {
20
        // Apply translated values back to the content object
21
    }
22
}

2. Return your converter from your TranslationService:

1
// In your TranslationService subclass:
2
@Override
3
public TranslationDataConverter getDataConverter() {
4
    return new CustomTranslationDataConverter();
5
}

Translation Value Types

The converter works with two main value types:

• TextTranslationValue — Plain text or HTML text
• RichTextTranslationValue — Complex rich text with nested modules and formatting

Site Assignment Options

Site assignment options control which site owns translated content. Brightspot provides four built-in options, and you can create custom ones.

Built-in Options

Option	Class	Behavior
Source Content Site	SourceOwnerSiteAssignment	Inherits site from source content
Auto	AvailableLocaleSiteAssignment	Assigns based on locale availability
Manual	ManualSiteAssignment	Uses a manually configured site
User Site	UsersSiteSiteAssignment	Uses the translator's current site

Custom Site Assignment

Implement SiteAssignmentOption to create custom site assignment logic:

1
public class CustomSiteAssignment extends SiteAssignmentOption {
2

3
    @Override
4
    protected void assignOwner(Site.ObjectModification siteData, TranslationLog log) {
5
        // Assign site ownership to the translated content
6
        // siteData.setOwner(determineSite(log));
7
    }
8
}

Translation Permission Provider

Implement TranslationPermissionProvider to add custom permissions that appear in Users & Roles.

1
public class CustomPermissionProvider implements TranslationPermissionProvider {
2

3
    @Override
4
    public Set<TranslationPermissionValue> getTranslationPermissions() {
5
        return Collections.singleton(new TranslationPermissionValue(
6
            "translation/custom/myaction",  // Permission ID
7
            "My Custom Action"              // Display name in UI
8
        ));
9
    }
10
}

Use with @Permission annotation on tool pages to restrict access.

Translation References Page

The TranslationReferencesPage interface controls how referenced content is presented during translation. The default implementation shows a content selector.

Implement this interface when you need to:

• Customize which references are shown
• Add filtering logic for referenced content
• Change the UI for reference selection

Return your implementation from TranslationService#getTranslationReferencesPage().