Content Translation Extended module

Edition

Incubator (services)

Issues

Git

Latest

3.4.12

Compatible with Magnolia 6.2.

The Content Translation Support Extended (CTSX) module enables you to translate content automatically. This module comes with several apps which are used to manage the translation tasks.

This module is at the INCUBATOR level.

When using Blossom, set the command run asynchronous to false in the batches-subapp.yaml file.
The frequency of the scheduled jobs may be high for most. For more information on how to configure the cron property see: Scheduler module.
DelegatingMultiValueChildNodeWithLocaleTransformer is the transformer to be used when nesting composite fields in multivalue fields, Magnolia 5.7 and 6.x only.
There is a NullPointerException when translating multilanguage in Magnolia 5.6.6+. Due to changes on 5.6.6, the registered translators were missing after changing the language.

Restarting the server will help to reload the translator. Doing so should help resolve the issue.
NoSuchDefinitionException when clicking on review action in translation workflow after upgrading to 2.0.2. There was a missing update of the configuration for the messageViews node after consolidating the translation comparison app with the other apps.

Navigate to: /modules/content-translation-support-ext-core/messageViews/reviewTranslation/actions/review. Add properties: appName=extendContentTranslation and subAppName=comparison.

OpenJDK Java 11 needs additional dependencies

Expand to see dependencies

<!-- For OpenJDK 11 CTE 3.0 you will need to have the following dependencies -->
<!-- in your web app lib folder-->

<dependency>
    <groupId>com.sun.xml.bind</groupId>
    <artifactId>jaxb-impl</artifactId>
    <version>2.3.1</version>
</dependency>
<dependency>
    <groupId>javax.xml.ws</groupId>
    <artifactId>jaxws-api</artifactId>
    <version>2.3.1</version>
</dependency>
<dependency>
    <groupId>javax.jws</groupId>
    <artifactId>javax.jws-api</artifactId>
    <version>1.1</version>
</dependency>
<dependency>
    <groupId>com.sun.xml.ws</groupId>
    <artifactId>rt</artifactId>
    <version>2.2.10</version>
</dependency>
<dependency>
    <groupId>com.sun.org.apache.xml.internal</groupId>
    <artifactId>resolver</artifactId>
    <version>20050927</version>
</dependency>
<dependency>
    <groupId>com.sun.xml.stream.buffer</groupId>
    <artifactId>streambuffer</artifactId>
    <version>1.5.6</version>
</dependency>
<dependency>
    <groupId>com.sun.xml.ws</groupId>
    <artifactId>policy</artifactId>
    <version>2.3.1</version>
</dependency>
<dependency>
    <groupId>com.sun.xml.messaging.saaj</groupId>
    <artifactId>saaj-impl</artifactId>
    <version>1.5.0</version>
</dependency>
<dependency>
    <groupId>org.glassfish.gmbal</groupId>
    <artifactId>gmbal-api-only</artifactId>
    <version>3.2.0-b003</version>
</dependency>
<dependency>
    <groupId>jakarta.xml.ws</groupId>
    <artifactId>jakarta.xml.ws-api</artifactId>
    <version>3.0.1</version>
</dependency>

From Magnolia version 6.2.39, you need additional dependencies in your webapp

Expand to see dependencies

 <!-- Manage versions of content-editor to v2 -->
<dependency>
    <groupId>info.magnolia</groupId>
    <artifactId>magnolia-link-unfurl</artifactId>
    <version>${contentEditor2Version}</version>
</dependency>
<dependency>
    <groupId>info.magnolia.block</groupId>
    <artifactId>magnolia-block-api</artifactId>
    <version>${contentEditor2Version}</version>
</dependency>
<dependency>
    <groupId>info.magnolia.block</groupId>
    <artifactId>magnolia-block-templating</artifactId>
    <version>${contentEditor2Version}</version>
</dependency>
<dependency>
    <groupId>info.magnolia.editor</groupId>
    <artifactId>magnolia-content-editor</artifactId>
    <version>${contentEditor2Version}</version>
</dependency>
<dependency>
    <groupId>info.magnolia.editor</groupId>
    <artifactId>stories-app</artifactId>
    <version>${contentEditor2Version}</version>
</dependency>
<dependency>
    <groupId>info.magnolia.editor</groupId>
    <artifactId>magnolia-content-editor-widgetset-v2</artifactId>
    <version>${contentEditor2Version}</version>
</dependency>

Installing with Maven

Maven is the easiest way to install the module. Add the following to your bundle:

Installation on JDK 11 needs extra dependencies. Please see the warnings section of this document.

Magnolia 6.2
Magnolia 6.1
Magnolia 5.7
Magnolia 5.6

<dependency>
  <groupId>info.magnolia.translation</groupId>
  <artifactId>magnolia-content-translation-support-ext-core</artifactId>
  <version>3.4.12</version>
</dependency>

<dependency>
  <groupId>info.magnolia.translation</groupId>
  <artifactId>magnolia-content-translation-support-ext-core</artifactId>
  <version>3.0.5</version>
</dependency>

<dependency>
  <groupId>info.magnolia.translation</groupId>
  <artifactId>magnolia-content-translation-support-ext-core</artifactId>
  <version>2.9.8</version>
</dependency>

<dependency>
  <groupId>info.magnolia.translation</groupId>
  <artifactId>magnolia-content-translation-support-ext-core</artifactId>
  <version>2.9.4</version>
</dependency>

Usage

Content Translation Support Extended (CTSX) enables you to translate content automatically over a translation provider ensuring a more accurate translation. Translation is done from a base language, typically English, to a target language. The base language should exist as content within your website or content app as properties. The target languages should be configured in your site definition. See Enabling multilanguage content for more information.

The Configuration shown here reflects usage with Magnolia 6.2. If you use an older version of Magnolia, see Pre 6.1 Usage.

Configuration

Parameter Description

supportedFieldDefinitions

required; taken from default Module Content Translation

Defines the field types that are going to be translated. Default is text and richText; possible values are composite and multiValue.

supportedFieldDefinitions

'supportedFieldDefinitions':
  'blockField': 'info.magnolia.block.BlockFieldDefinition'
  'codeField': 'info.magnolia.ui.field.CodeFieldDefinition'
  'collapsibleCompositeField': 'info.magnolia.editor.app.field.CollapsibleCompositeFieldDefinition'
  'compositeField': 'info.magnolia.ui.field.CompositeFieldDefinition'
  'damRichTextField': 'info.magnolia.dam.app.field.DamRichTextFieldDefinition'
  'expandingLinkField': 'info.magnolia.editor.app.field.ExpandingLinkFieldDefinition'
  'expandingTextField': 'info.magnolia.editor.app.field.ExpandingTextFieldDefinition'
  'jcrMultiField': 'info.magnolia.ui.field.JcrMultiFieldDefinition'
  'jcrMultiValueField': 'info.magnolia.ui.field.JcrMultiValueFieldDefinition'
  'lightRichTextField': 'info.magnolia.editor.field.LightRichTextFieldDefinition'
  'multiJcr': 'info.magnolia.editor.block.jcr.MultiJcrBlockDefinition'
  'refreshableTextField': 'info.magnolia.editor.app.field.RefreshableTextFieldDefinition'
  'richText': 'info.magnolia.ui.form.field.definition.RichTextFieldDefinition'
  'richTextField': 'info.magnolia.ui.field.RichTextFieldDefinition'
  'switchableField': 'info.magnolia.ui.field.ConfiguredSwitchableFieldDefinition'
  'text': 'info.magnolia.ui.form.field.definition.TextFieldDefinition'
  'textField': 'info.magnolia.ui.field.TextFieldDefinition'

Content types for multi field need to specify decorator and item provider in the definition

entryResolution:
    propertyNameDecorator: info.magnolia.ui.field.NoopNameDecorator
  field:
    itemProvider:
      $type: currentItemProvider

propertiesToTranslateFinder

required

The class that finds the properties to be translated. Default value: info.magnolia.translation.ext.core.finder.AdaptivePropertiesToTranslateFinder; finds the properties by processing the fields in the dialogs.

sourceLanguages

optional

From version 2.9.7, 3.0.3 Defines the source languages. The default is the value in the site definition fallbackLanguage; you can define as many languages as your 3rd party translator supports, the dialog will display just the ones supported in the current site definition.

configuration structure

Translation providers

There are several translation providers to choose from: CTSX Google Translator, CTSX Microsoft Translator, CTSX Translations.com, CTSX AT Language Solutions, CTSX DeepL Translator, and CTSX Instant Translation. To make use of the translation functionality, a user account is required for the chosen provider.

A translator module connects Magnolia to translation services. The behavior of the service depends on the translation service selected.

Service Notes

Service	Notes
Synchronous	Directly returns the translated result for each translation request. Google Microsoft AT Language Solutions (from version `3.3`) DeepL (from version 3.4)
Asynchronous	Does not return the translated result for each translation request. A second request is required to get the translated result. Translations.com AT Language Solutions (before version `3.3`)

Synchronous

Directly returns the translated result for each translation request.

Google
Microsoft
AT Language Solutions (from version 3.3)
DeepL (from version 3.4)

Asynchronous

Does not return the translated result for each translation request. A second request is required to get the translated result.

Translations.com
AT Language Solutions (before version 3.3)

Common properties

Property Description

Property	Description
`autoTranslationAllowed`	optional When true the content review process (workflow) is bypassed.
`class`	required Definition class for the translator to be used.
`configName`	required The display name of the configuration in Magnolia.
`defaultFlag`	required Set the translator to be the default.
`enabledFlag`	required Enables or disables the configuration with `true` or `false`.
`implementationClass`	required Implementation class for the translation service.
`leaveEmptyXliffTranslationValues`	optional Exported fields are filled in with the original values by default, to disable this behaviour set this property to `true`.

autoTranslationAllowed

optional

When true the content review process (workflow) is bypassed.

class

required

Definition class for the translator to be used.

configName

required

The display name of the configuration in Magnolia.

defaultFlag

required

Set the translator to be the default.

enabledFlag

required

Enables or disables the configuration with true or false.

implementationClass

required

Implementation class for the translation service.

leaveEmptyXliffTranslationValues

optional

Exported fields are filled in with the original values by default, to disable this behaviour set this property to true.

Translation Extend app

The module comes with the Translation Extend app which can be found under the tools menu of the applauncher. This app extends the functionality of Content Translation in the sense that translations can now be automatized. It is still possible to export the automatized translations from the Content Translation app after receiving them.

Translation subapps

The app is made up of several subapps for managing translation files and submissions.

Batches: In the Batches subapp users can
- Add a new or edit an existing batch.
- Submit a batch for translation.
- Get the history of the batch.
- Cancel a batch submission.
- Reload an existing batch.
Histories: Allows for viewing and managing the batch histories.
Queues: Allows for managing the translation submission.
Comparison: Allows you to compare original and translated values before importing or rejecting.

Translation status

Once a batch is created it has a status. The status is visible from Batches subapp.

Status Description

Status	Description
`NEW`	Created and not yet submitted.
`OPEN`	Processing and submitted.
`IMPORTED`	The content was imported.
`REJECTED`	The translation has been rejected by the reviewer.
`CANCELLED`	Cancelled
`EXPIRED`	Translation expired.
`ERROR`	An error occurred.

NEW

Created and not yet submitted.

OPEN

Processing and submitted.

IMPORTED

The content was imported.

REJECTED

The translation has been rejected by the reviewer.

CANCELLED

Cancelled

EXPIRED

Translation expired.

ERROR

An error occurred.

Workflow

This module provides a workflow for users to review and approve translated content. If the setting autoTranslationAllowed is true then the content is imported directly without a review step. Otherwise the content review workflow process is started.

The workflow is identical in nature to the 4-eye content approval workflow used for the Pages app. In this case the editor is the translation provider and the reviewer can be any person in the group. To configure your desired group, change the property here: /modules/content-translation-support-ext-core/tasks/reviewTranslation/groups@publishers.

Message views

Workflow message views define how messages display in Pulse during translation workflow. See Message view definition for more details.

Message views are configured here: /modules/content-translation-support-ext-core/messageViews.

message view definition oldUI

Work item handlers

The mapping is based on the work item name which is added to the jBPM process definition. There are two handlers configured for the workflow process.

approve: Handles importing translated content after approval
reject: Handler for content rejection

Work item handlers are configured here: /modules/content-translation-support-ext-core/workItemHandlers.

Translation jobs

The core module installs three scheduled jobs to automate the translation process. The translation is submitted to the translation provider. In the case of Translations.com or AT Language Solutions, a second request is required to retrieve the translation results. Finally, the translation is either directly imported or the workflow process is initiated.

The jobs are configured under: /modules/scheduler/config/jobs.

Submitting

The submitTranslationToExternalServiceJob sends translation submission requests to the provider.

# Configuration shown in YAML but must exist as a JCR Node.
submitTranslationToExternalServiceJob:
  catalog: workflowTranslation
  command: submitTranslationToExternalServiceProcessCommand
  cron: 1/60 * * * * ? # set to execute every minute at 1 second past the minute
  description: Output, Send, Update translation batch
  enabled: true
  concurrent: false
  params:
    maxAttempt: 10 # define the max retry for each item

Retrieving

The retrieveTranslationResultFromExternalServiceJob is for asynchronous translation. For translating services that require a second request to retrieve the translations you will need to use this job as well.

# Configuration shown in YAML but must exist as a JCR Node.
retrieveTranslationResultFromExternalServiceJob:
  catalog: workflowTranslation
  command: retrieveTranslationResultFromExternalServiceProcessCommand
  cron: 5/60 * * * * ? # set to execute every minute at 5 seconds past the minute
  description: Get translation from provider
  enabled: true
  concurrent: false
  params:
    maxAttempt: 10 # define the max retry for each item

Importing

The startImportWorkflowOrAutoImportJob imports the translation immediately or starts the workflow. The behavior is set by autoTranslationAllowed property in the translator configuration.

# Configuration shown in YAML but must exist as a JCR Node.
startImportWorkflowOrAutoImportJob:
  catalog: workflowTranslation
  command: startImportWorkflowOrAutoImportJob
  cron: 0/30 * * * * ? # set to execute every 30 seconds
  description: Import or create import workflow
  enabled: true
  concurrent: false
  params:
    maxAttempt: 10 # define the max retry for each item

Clean up imported submission job

The cleanUpImportedSubmissionJob clean up the successful batch, imported translation and all related histories from the workspace.

# Configuration shown in YAML but must exist as a JCR Node.
'cleanUpImportedSubmissionJob':
  'command': 'cleanUpImportedSubmission'
  'catalog': 'workflowTranslation'
  'cron': '0 0/10 * 1/1 * ? *'
  'description': 'Clean up imported submission'
  'enabled': true
  'concurrent': false
  'params':
    'minusDays': '14' #get record has lastModified from the pass
    'numOfBatchPerProcess': '10'

What is exported and imported

By default, text and rich text fields are included in export files. Additional field types may be registered here: /modules/translation/config/supportedFieldDefinitions. Add another property with the value set to the definition class of the field that should be included.

what is exported imported

In addition to registration, the child fields of the composite field should have an i18n property set to true.

compositeFieldI18nChildNodeChildrenI18n:
      label: compositeField
      $type: compositeField
      i18n: true
      itemProvider:
        $type: jcrChildNodeProvider
      propertyNameDecorator: info.magnolia.ui.field.PrefixNameDecorator
      properties:
        - name: textField1
          label: textField1
          $type: textField
          i18n: true
        - name: textField2
          label: textField2
          $type: textField
          i18n: true

Notification Email

Magnolia uses Mail module to send a notification email to submitter in case of errors. The template provided is here. The notification email template is configured here: /modules/mail/config/templatesConfiguration/translationNotificationTemplate.

core email notification

Changelog

Version Notes

Version	Notes
`3.4.12`	Changelog Release notes for 3.1.12: info.magnolia.editor.block.jcr.MultiJcrBlockDefinition Needs to be added to supportedFieldDefinitons for translating blocks (like in the stories app)
`3.4.11`	Changelog
`3.4.10`	Changelog
`3.4.9`	Changelog
`3.4.8`	Changelog
`3.4.7`	Changelog
`3.4.6`	Changelog
`3.4.5`	Changelog
`3.4.4`	Changelog
`3.4.3`	Changelog
`3.4.2`	Changelog
`3.4.1`	Changelog
`3.4`	Changelog
`3.3`	Changelog
`3.2`	Changelog
`3.1.1`	Changelog
`3.1.0`	Changelog
`3.0.5`	Changelog
`3.0.4`	Changelog
`3.0.3`	Changelog
`3.0.2`	Changelog
`3.0.1`	Changelog
`3.0`	Changelog
`2.9.8`	Changelog
`2.9.7`	Changelog
`2.9.6`	Changelog
`2.9.5`	Changelog
`2.9.4`	Changelog
`2.9.3`	Changelog
`2.9.2`	Changelog
`2.9.1`	Changelog
`2.0.3`	Changelog
`2.0.2`	Changelog
`2.0.1`	Changelog
`2.0`	Initial release of the extensions version of the module.

3.4.12

Changelog

Release notes for 3.1.12: