Content Translation Support module

Content management Unbundled: Extension

Edition DX Core

License

MLA

Issues

MGNLCTS

Maven site

Content Translation Support

Latest

3.0.0

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.

Module artifacts have changed

Please note that the artifact IDs (Maven groupId and artifactId) have changed since Magnolia 5.5.

If you have custom Java code relying on this module, you need to install a compatibility module too.

Check Git for the new module structure.

See also the Content Translation Extended module (CTSX) module, which provides automated translation services for your content.

Note the changes in groupId and artifactId since the 2.2 release.

Installing with Maven

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

<dependency>
  <groupId>info.magnolia.translation</groupId>
  <artifactId>magnolia-content-translation</artifactId>
  <version>3.0.0</version> (1)
</dependency>
1 Should you need to specify the module version, do it using <version>. 
<dependency>
  <groupId>info.magnolia.translation</groupId>
  <artifactId>magnolia-content-translation-pages-integration-app</artifactId>
  <version>3.0.0</version> (1)
</dependency>
1 Should you need to specify the module version, do it using <version>.

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, you must do one of two things:

Add the following snippet to your POM file:

<dependency>
  <groupId>info.magnolia.translation</groupId>
  <artifactId>magnolia-content-translation-support-compatibility</artifactId>
  <version>3.0.0</version> (1)
</dependency>
1 Should you need to specify the module version, do it using <version>.

Configuration

The module is configured in the following JCR nodes:

  • /modules/translation

  • /modules/translation-pages-integration

In addition, the following directories in the 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.

  • 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.

GoogleSpreadsheetTranslationBundleWriter adds the Google Translate formula to the CSV exporter. When you upload the CSV file to Google Docs, it evaluates the formula and the text is machine-translated into the target i18n languages automatically.

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.

travel:
  i18n:
    locales:
      en:
        country:
        enabled: true
        language: en
      de:
        country:
        enabled: true
        language: de
      class: info.magnolia.cms.i18n.DefaultI18nContentSupport
      enabled: true
      fallbackLocale: en

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 Google Docs.

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

translation:
  config:
    importers:
      xlsImporter:
        readerImplementationClass: info.magnolia.translation.io.reader.XlsTranslationItemReader
        extension: xls
        label: contenttranslation.fileformat.xls
      csvImporter:
      xliffImporter:
    exporters:
      xlsExporter:
        writerImplementationClass: info.magnolia.translation.io.writer.XlsTranslationItemWriter
        extension: xls
        label: contenttranslation.fileformat.xls
      csvExporter:
      xliffExporter:
      googleSpreadsheetExporter:

class

required

Class that performs the import or export (readerImplementationClass and writerImplementationClass properties respectively).

  • info.magnolia.translation.io.reader.*

    • XlsTranslationItemReader

    • CsvTranslationItemReader

    • UnzippedXliffTranslationItemReader

  • info.magnolia.translation.io.writer.*

    • XlsTranslationItemWriter

    • CsvTranslationItemWriter

    • XliffTranslationItemWriter

    • GoogleSpreadsheetTranslationItemWriter

You can write your own importers and exporters for other file formats, databases, or Web services that translators use.

extension

optional

File extension without the dot.

label

optional

Extension label.

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.

translation:
  commands:
    translation:
      downloadTranslationFile:
        class: info.magnolia.translation.commands.TranslationFileDownloadCommand
      uploadTranslationFile:
        class: info.magnolia.translation.commands.TranslationFileUploadCommand
Property Description

commands

required

Commands folder.

     translation

required

Content translation support catalog.

         <command name>

required

  • downloadTranslationFile: Name of the command node to download files for translation.

  • uploadTranslationFile: Name of the command node to reupload translation files.

                 formPath

required

The path to the form.

                 workspace

required

Workspace name.

             class

required

  • info.magnolia.translation.commands.TranslationFileDownloadCommand:

    • Downloads files from a specified path in a specified format, for translation. Operates on the website workspace by default.

    • Calls the relevant importers and exporters class.

    • The exported file contains all page content nodes marked as i18n in the template definition.

    • The file path in the repository is converted into the file name by replacing forward slashes with dots.

  • info.magnolia.translation.commands.TranslationFileUploadCommand:

    • Uploads translated files in a specified format to a specified path. Operates on the website workspace by default.

    • Calls the relevant importers and exporters class.

    • Content is uploaded to relevant i18n fields in the dialogs.

Action definitions

The module includes some dialog actions that are used in the Content Translation app.

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 Resource Files > /translation/dialogs/downloadTranslationFile.yaml, not in JCR nodes.

downloadTranslationFile.yaml
form:
  properties:
    ...
actions:
  commit:
    command: downloadTranslationFile
    catalog: translation
    class: info.magnolia.translation.ui.action.TranslationFileDownloadDialogActionDefinition
  cancel:
    class: info.magnolia.ui.dialog.action.CancelDialogActionDefinition
uploadTranslationFile.yaml
form:
  properties:
    ...
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
Property Description

commit

required

Commit action configuration.

     catalog

required

translation command catalog.

     class

required

Action definition class. See below.

     command

required

Name of command configuration node.

     label

optional

Action labels: Export file and Import file.

info.magnolia.translation.ui.action.* definition classes:

TranslationFileUploadDialogActionDefinition

Uploads the translation file.

TranslationFileDownloadDialogActionDefinition

Downloads the translation file.

OpenCreateTranslationFileUploadDialogActionDefinition

Used in the app to open the uploadTranslationFile dialog.

The downloadTranslationFile dialog is opened with info.magnolia.ui.dialog.actions.OpenDialogActionDefinition. See Action definition classes for more information.

What is exported and imported

Text and rich text fields are included in export files by default. Additional fields types can be registered, but they must be configured using Magnolia 6 UI.

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

modules:
  translate:
    config:
      importers:
      exporters:
      supportedFieldDefinitions:
        richText: info.magnolia.ui.field.RichTextFieldDefinition
        text: info.magnolia.ui.field.TextFieldDefinition
      propertiesToTranslateFinder:
        class: info.magnolia.translation.finder.AdaptivePropertiesToTranslateFinder
Property Description

config

optional

Module configuration folder.

     supportedFieldDefinitions

required

Defines the field types to export.

         <field name>

required

Registers rich text field and text field definition classes. These field types typically contain the textual i18n content.

     propertiesToTranslateFinder

required

Node data to translate finder node.

         class

required

info.magnolia.translation.finder.AdaptivePropertiesToTranslateFinder delegates calls to an implementation of PropertiesToTranslateFinder based on the modules that are currently installed.

Registering additional field types

You can register additional field types to be included in the exported file. These must be configured using Magnolia 6 UI (for example, info.magnolia.ui.form.field.definition.CompositeFieldDefinition must be updated to info.magnolia.ui.field.CompositeFieldDefinition).

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

supportedFieldDefinitions:
  richText: info.magnolia.ui.field.RichTextFieldDefinition
  text: info.magnolia.ui.field.TextFieldDefinition
  composite: info.magnolia.ui.field.CompositeFieldDefinition

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.

/my-module/dialogs/my-dialog.yaml
form:
  properties:
    test:
      $type: compositeField
      itemProvider: currentItemProvider
      properties:
        - name: text1
          $type: textField
          i18n: true
        - name: text2
          $type: textField

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.

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 information.

    Example: New text field called bio under /modules/contacts/apps/contacts/subApps/detail/editor/form/fields/bio.

    editor:
  form:
    fields:
      bio:
        $type: textField
        i18n: true
        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.

    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 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:
  properties:
    ...
actions:
  commit:
    command: downloadContactTranslation
    catalog: translation
    class: info.magnolia.translation.ui.action.TranslationFileDownloadDialogActionDefinition
  cancel:
    class: info.magnolia.ui.dialog.action.CancelDialogActionDefinition
    uploadContactTranslation.yaml
    form:
  properties:
    ...
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.

    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 actionbar.

    Example: Adding downloadTranslation and uploadTranslation actions to the contact section of actionbar in the Contacts app in /modules/contacts/apps/contacts/subApps/browser/actionbar/sections/contact/groups/importExportActions.

    browser:
  actionbar:
    sections:
      contact:
        groups:
          importExportActions:
            items:
              export:
              downloadTranslation:
              uploadTranslation:
Feedback

DX Core

×

Location

This widget lets you know where you are on the docs site.

You are currently perusing through the DX Core docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules