Content Translation Support module

The Content Translation Support module allows you to export and import content in translation-friendly XLIFF, CSV and Excel formats. You can send a file to a translator and then import the translated content. The file includes context information and a link to the relevant content to make translation easier. The module comes with a Content Translation app for managing page translation. Export formats are pluggable and can be extended to support a custom format. 

Installing

<dependency>
  <groupId>info.magnolia.translation</groupId>
  <artifactId>magnolia-content-translation</artifactId>
</dependency>

<dependency>
  <groupId>info.magnolia.translation</groupId>
  <artifactId>magnolia-content-translation-pages-integration-app</artifactId>
</dependency>

Compatibility module

We have been gradually removing the old Content API from our modules since Magnolia 5.6. If you have custom code relying on classes from the old form module then you must do one of two things:

• Update your code for the new version of the content translation support module.
• Or you can use the magnolia-content-translation-support-compatibility module together with the magnolia-core-compatibility module.

<dependency>
  <groupId>info.magnolia.translation</groupId>
  <artifactId>magnolia-content-translation-support-compatibility</artifactId>
</dependency>

Configuration

The module is configured in the following JCR nodes:

• /modules/translation
• /modules/translation-pages-integration

In addition, the following directories in the Web Dev > Resource Files app contain configuration by file: 

• /translation/dialogs
• /translation/fieldTypes
• /translation/i18n

Content Translation app

The Content Translation app allows you to manage the translation of pages. The app is in the Tools section in the app launcher.

• Export translation: Exports i18n content of a page or tree.
• Import translation: Imports translated content of a page or tree.
• Preview page: Opens the page in preview mode in the Pages app.
• Publish and Unpublish are subject to workflow. 

Exporting pages for translation

To export pages:

1. Select a page. Subpages are included in the export file.
2. Click Export translation.
3. Select a file format
4. Click Export File.

The download filename is created from the file path in the website workspace, with dots replacing forward slashes such as  website.travel.about.xls. The file has the following columns (comma separated headings in CSV or elements in XLIFF):

• Modification date of page
• Key: Internal identifier that consists of component UUID and field name. This is used by Magnolia to store and render translated content. Do not edit this value.
• Link to page: Page URL for easy access by the translator. Click to see the translatable text in page context.
• Title: A pseudo-title created by combining component type and field name, for example Text and Image: Subheading. This tells the translator what kind of page element he is translating.
• Default language: Default language text.
• <language_code>: Columns for each locale configured for the site. This is where the translator types the language text. Already translated content can be updated and new translations added.

Importing translated page content

Once the file has been translated you can upload it in the app. The translated content is automatically included on the page.

To import translated page content:

1. Select the page.
2. Click Import translation.
3. Upload the file.
4. Optionally check the overwrite and import empty translations options.
5. Click Import File.

In the Pages app you can now see the translated content in the components and dialogs.

Locales

Your site definition needs to have at least one locale in addition to the default locale. Locales show up as columns in the export file.

Example: travel site definition with English and German locales.

Importers and exporters

Importers and exporters are Java classes that contain business logic to convert translatable content into a convenient format. Out of the box the module provides importers and exporters for XLIFF, Excel and CSV files, and an exporter for Uploading to Googe Docs.

Importers and exporters are configured in /modules/translation/config. 

Commands

The module includes two TranslationFile commands that are used to export and import content in various formats for translation.

Commands are configured in /modules/translation/commands/translation.

Properties:

Action definitions

The module includes some dialog actions that are used in the Content translation app. These can be Enabling content translation in content apps.

Example: Commit actions to download and upload files in /translation-pages-integration/dialogs/downloadTranslationFile/actions/downloadTranslationFile and uploadTranslationFile.

These actions are configured by file, for example in Web Dev > Resource Files >  /translation/dialogs/downloadTranslationFile.yaml, not in JCR nodes.

form:
  ...
actions:
  commit:
    command: downloadTranslationFile
    catalog: translation
    class: info.magnolia.translation.ui.action.TranslationFileDownloadDialogActionDefinition
  cancel:
    class: info.magnolia.ui.dialog.action.CancelDialogActionDefinition

form:
  tabs:
    ...

actions:
  commit:
    command: uploadTranslationFile
    catalog: translation
    class: info.magnolia.translation.ui.action.TranslationFileUploadDialogActionDefinition
    successMessage: translation.uploadTranslationFile.executionSuccess
  cancel:
    class: info.magnolia.ui.dialog.action.CancelDialogActionDefinition

Action definition classes:

What is exported and imported

By default, text and rich text fields are included in export files, and additional field types can be Registering additional field types. 

The type of content that is exported is configured in /modules/translation/config/supportedFieldDefinitions and /propertiesToTranslateFinder.

Properties:

Registering additional field types

You can register appropriate additional field types to be included in the exported file. 

Example: Registering composite field as a field type to export.

In addition to registration, the subfields of the composite field should have an i18n property set to true. It is not necessary for the composite field itself to have an i18n property.

Example: Composite field configuration where text1 field will be included in the download file, but text2 will not.

form:
  tabs:
    - name: tabText
      fields:
        - name: test 
          label: Test
          layout: vertical
          fieldType: composite
          transformerClass: info.magnolia.ui.form.field.transformer.composite.DelegatingCompositeFieldTransformer
          fields:
            - name: text1
              i18n: true
              label: Text 1
              fieldType: text
            - name: text2
              label: Text 2
              fieldType: text

i18n content storage

You can view the translated nodes in the website workspace in the JCR Browser app.  The translated content is suffixed with a locale such as _de. Since English is the default locale on this site no _en suffix is used. 

Example: Jumbotron on About page in the Travel demo.

Enabling content translation in content apps

You can enable content translation support in any content app. 

Example: Enabling content translation in the Contacts app. 

1. Add the i18n property to any field you want to translate in the detail subapp. See Enabling mulitlanguage content for more.
   Example: New Bio text field in the Personal tab in /modules/contacts/apps/contacts/subapps/detail/editor/form/tabs/personal/fields/bio. 

   Node name	Value
   editor
   form
   tabs
   personal
   fields
   bio
   class	text
   i18n	true
   label	Bio
   rows	3

2. Configure contact translation upload and download commands in the translation catalog in the translation module. The commands are called by the dialogs configured in step 3.
    Example: downloadContactTranslation and uploadContactTranslation commands configured in  /modules/translation/commands/translation/commands .

   Node name	Value
   commands
   translation
   downloadContactTranslation
   workspace	contacts
   formPath	/modules/contacts/apps/contacts/subApps/detail/editor/form
   class	info.magnolia.translation.commands.TranslationFileDownloadCommand
   uploadContactTranslation
   class	info.magnolia.translation.commands.TranslationFileUploadCommand

   
   

3. Configure contact translation dialogs in any module. The easiest way to do this is to copy the  downloadTranslationFile  and  uploadTranslationFile  dialog definition files in Web Dev > Resource Files /translation/dialogs/ and change the value of the command properties. These dialogs use the commands configured in step 2. 
   

   Example: downloadContactTranslation and uploadContactTranslation dialogs configured in  /modules/translation/commands/translation/dialogs .

   downloadContactTranslation.yaml

   form:
     ...
   actions:
     commit:
       command: downloadContactTranslation
       catalog: translation
       class: info.magnolia.translation.ui.action.TranslationFileDownloadDialogActionDefinition
     cancel:
       class: info.magnolia.ui.dialog.action.CancelDialogActionDefinition

   uploadContactTranslation.yaml

   form:
     tabs:
       ...
   
   actions:
     commit:
       command: uploadContactTranslation
       catalog: translation
       class: info.magnolia.translation.ui.action.TranslationFileUploadDialogActionDefinition
       successMessage: translation.uploadTranslationFile.executionSuccess
     cancel:
       class: info.magnolia.ui.dialog.action.CancelDialogActionDefinition

4. Add translation download and upload actions in the browser subapp. The easiest way to do this is to extend the downloadTranslationFile and uploadTranslationFile actions in the Content Translation app. 

   Example: Adding downloadTranslation and uploadTranslation actions in the Contacts app in /modules/contacts/apps/contacts/subapps/browser/actions.

   
   

   Node name	Value
   apps
   contacts
   subapps
   browser
   actions
   downloadTranslation
   extends	/modules/translation-pages-integration/apps/pages-translation/subApps/browser/actions/downloadTranslationFile
   label	Download for translation
   uploadTranslation
   extends	/modules/ translation-pages-integration /apps/ pages-translation /subApps/browser/actions/uploadTranslationFile
   label	Upload translated content

   
   

5. Add the actions created in step 4 to the actionbar.
   Example: Adding downloadTranslation and uploadTranslation actions to the contact section of the actionbar in the Contacts app in /modules/contacts/apps/contacts/subapps/browser/actionbar/sections/contact/groups/importExportActions.

   
   

   Node name
   browser
   actionbar
   sections
   contact
   groups
   importExportActions
   items
   export
   downloadTranslation
   uploadTranslation