Translation

Brightspot’s translation system allows for the integration with third-party translation services to localize content published in Brightspot. The system provides the common components needed to begin and manage translations in Brightspot, including configuration settings, translation request UI and tracking UI, permission configuration, and notifications. Extension points are provided to integrate with translation providers and for other common customization needs.

The translation system leverages the Localization system, which tracks the relationship between different localized variations of a piece of content. The translation system is simply a way to produce those localized variations.

Overview of translations

Brightspot’s translation architecture is designed to provide common translation tooling out of the box while providing extensibility where needed. There are six core components of the translation system that can be extended:

1. Translation Service—Integration point to add new translation services that convert contents from one locale to another. A translation service implementation typically calls out to third-party APIs to translate the content. Brightspot provides a few translation service implementations out of the box, such as Lingotek, Google Translate, and AWS Translate.
2. Translation Log—A system of record for each translation conducted in the CMS. A translation log tracks who, what, when, and how a translation occurred.
   These logs can be extended to track additional data about a translation.
3. Translation Data Converter—The mechanism by which Brightspot content data gets packaged for delivery to translation services, and how data received from translation services is applied back to Brightspot content. Brightspot provides a common implementation that should work for most use cases; however, extension is available when needed.
4. Translation Completion Action—A way to define what should happen to a piece of content that is created via a translation. Admin configuration is provided to allow users to select which action should be used for which content types. Brightspot provides a few implementations out of the box, such as publishing the content immediately after translation or saving the content as a draft on completion.
5. Translation Action—Allows for the implementation of custom UI components on the Translations tab for a piece of content. This can allow users to take specific actions on translations that have occurred. An example could be allowing users to cancel translations that are in flight for a specific translation service.
6. Translation Permission Provider—Allows for the definition of custom permission settings in the context of translation when defining a Brightspot role. Typically used in conjunction with a translation action so that admins can control who can take certain actions on translations.

Translation Lifecycle

The following list walks you through the typical code path taken to translate a piece of content.

1. A user initiates the translation request flow via TranslateAction.java.
2. TranslationRequestPage.java is triggered and displayed in a CMS pop-up frame for the user to begin the translation.
   
   1. The user selects a source locale (if not set) and which translation service to use.
   2. The user selects the target locales for the translation. Target locales displayed are determined via TranslationService#getSupportedLocales.
   3. The user selects any referenced content to also translate.
   4. The user reviews what will be translated and clicks the translate button.
3. A TranslationContext.java object is constructed.
   
   1. Translation context includes data such as the site, user, service, source locale, target locales, and items to be translated.
   2. TranslationContext.java leverages TranslationDataConverter.java via TranslationService#getDataConverter to create a TranslationData.java object for each item to be translated.
4. TranslationService#translate is called on the translation service the user chose, with the constructed translation context being passed in as a parameter.
   
   1. At this point, the translation process is delegated to the translation service. It is expected that the translate call produces a list of TranslationLog.java objects for each translation.
   2. Translations at this point are typically in TranslationStatus#PENDING.
5. The system waits for translations to complete.
   
   1. How the translated data is received is determined by the specific translation service implementation. This could be accomplished via a repeating task, webhooks, or some other mechanism. If desired, current progress can be updated on custom fields in the translation log incrementally.
6. Translation data is received.
   
   1. The TranslationService implementation receives the raw translated data and converts it to a TranslationData.java.
   2. TranslationService#completeTranslation is called to finalize the translation.
      
      1. TranslationDataConverter#copyTranslatedDataOntoObject is called to copy data from TranslationData.java onto the Brightspot content type.
      2. LocalizationData.java metadata is set to connect the new translated object to the source content.
      3. TranslationCompletionAction#completeTranslation is called to finalize the translated content.
      4. TranslationLog#status is set to success.
7. Process complete.