Page tree
Skip to end of metadata
Go to start of metadata

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. 

The Content Translation Support Extend modules extend translation functionality to allow automatic machine-translation, content translation workflow and integration with Translations.com.

 

Installing

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

<dependency>
  <groupId>info.magnolia</groupId>
  <artifactId>magnolia-module-content-translation-support</artifactId>
  <version>2.1.8</version>
</dependency>

Pre-built jars are also available for download. See Installing a module for help.

Configuration

The module is configured in /modules/content-translation-support.

Node nameValue

 modules

 

 content-translation-support

 

 apps

 

 config

 

 dialogs

 

 commands

 

 fieldTypes

 

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.

The GoogleSpreadsheetTranslationBundleWriter exporter class 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.

Node nameValue

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

Importers and exporters are configured in /modules/content-translation-support/config

Node nameValue

 content-translation-support

 

 config

 

 importers

 

 xlsImporter

 

 class

info.magnolia.module.contenttranslationsupport.reimport.XlsTranslationBundleUpdateReader

 extension

xls

 label

contenttranslation.fileformat.xls

 csvImporter

 

 xliffImporter

 

 exporters

 

 xlsExporter

 

 class

info.magnolia.module.contenttranslationsupport.export.XlsTranslationBundleWriter

 extension

xls

 label

contenttranslation.fileformat.xls

 csvExporter

 

 xliffExporter

 

 googleSpreadsheetExporter

 


Properties:

class

required

Class that performs the import or export.

  • info.magnolia.module.contenttranslationsupport.reimport. XlsTranslationBundleUpdateReader
  • info.magnolia.module.contenttranslationsupport.reimport. CsvTranslationBundleUpdateReader
  • info.magnolia.module.contenttranslationsupport.reimport. XliffTranslationBundleUpdateReader
  • info.magnolia.module.contenttranslationsupport.export. XlsTranslationBundleWriter
  • info.magnolia.module.contenttranslationsupport.export. CsvTranslationBundleWriter
  • info.magnolia.module.contenttranslationsupport.export. XliffTranslationBundleWriter
  • info.magnolia.module.contenttranslationsupport.export. GoogleSpreadsheetTranslationBundleWriter

You can write your own importers and exporters for other file formats, databases, or Web services that translators use. See examples in Git (importers | exporters).

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/content-translation-support/commands/contenttranslationsupport.

Node nameValue

 content-translation-support

 

 commands

 

 contenttranslationsupport

 

 downloadTranslationFile

 

 class

info.magnolia.module.contenttranslationsupport.commands.TranslationFileDownloadCommand

 uploadTranslationFile

 

 class

info.magnolia.module.contenttranslationsupport.commands.TranslationFileUploadCommand

 exportContent

 

 importContent

 

 website

 

 extends

/modules/pages/commands/website

Properties:

commands

required

Commands folder.

contenttranslationsupport

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.

contentTransporter

optional

Applicable only to the downloadTranslationFile command.

Set the node if the command should operate on other than the default (website) workspace.

formPath

required

The path to the form.

workspace

required

Workspace name.

class

required

  • TranslationFileDownloadCommand
    • Downloads files from a specified path in a specified format, for translation. Operates on the  website  workspace by default.
    • Calls the relevant exporter 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. For example the file name for /travel/about/careers page is  website.travel.about.careers.<file extension>.
  • TranslationFileUploadCommand
    • Uploads translated files in a specified format to a specified path. Operates on the website workspace by default.
    • Calls the relevant importer class.
    • Content is uploaded to relevant i18n fields in the dialogs.

website

optional

Website catalog.

extends

optional

Extends the website command's catalog to ensure that publication and unpublication of pages is subject to workflow.

(warning) Content Translation Support 2.1.2+ / Magnolia 5.4.4+  exportCommand and importCommand are deprecated.

Action definitions

The module includes dialogs and action definition classes that are used in the Content Translation app. These can be adapted for any content app.

Example: Commit actions to download and upload translation files in /modules/content-translation-support/dialogs/downloadTranslationFile and uploadTranslationFile.

Node nameValue

 content-translation-support

 

 dialogs

 

 downloadTranslationFile

 

 actions

 

 commit

 

 catalog

contenttranslationsupport

 class

info.magnolia.module.contenttranslationsupport.dialog.action.TranslationFileDownloadDialogActionDefinition

 command

downloadTranslationFile

 label

content-translation-support.downloadTranslationFile.actions.commit.label 

 cancel

 

 form

 

 uploadTranslationFile

 

 actions

 

 commit

 

 catalog

contenttranslationsupport

 class

info.magnolia.module.contenttranslationsupport.dialog.action.TranslationFileUploadDialogActionDefinition

 command

uploadTranslationFile

 label

content-translation-support.uploadTranslationFile.actions.commit.label

 cancel

 

 form

 


Properties:

commit

required

Commit action configuration.

catalog

required

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

Action definition classes:

info.magnolia.module.contenttranslationsupport.dialog.action. OpenCreateTranslationFileUploadDialogActionDefinition

Uploads the translation file.

info.magnolia.module.contenttranslationsupport.dialog.action. TranslationFileDownloadDialogActionDefinition

Downloads the translation file.

info.magnolia.module.contenttranslationsupport.dialog.action. OpenCreateTranslationFileUploadDialogActionDefinition

Used in the app to open the uploadTranslationFile dialog.

downloadTranslationFile dialog is opened with OpenEditDialogActionDefinition . See Action definition classes for more.

What is exported and imported

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

The type of content that is exported is configured in /modules/content-translation-support/config/controlTypesToExport and /nodeDataToTranslateFinder.

Node nameValue

 modules

 

 content-translation-support

 

 config

 

 importers

 

 exporters

 

 controlTypesToExport

 

 richText

info.magnolia.ui.form.field.definition.RichTextFieldDefinition

 text

info.magnolia.ui.form.field.definition.TextFieldDefinition

 nodeDataToTranslateFinder

 

 class

info.magnolia.module.contenttranslationsupport.export.AdaptiveNodeDataToTranslateFinder 

Properties:

config

optional

Module configuration folder.

controlTypesToExport

required

Defines the fields to export.

<field name>

required

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

nodeDataToTranslateFinder

required

Node data to translate finder node.

class

required

AdaptiveNodeDataToTranslateFinder delegates calls to an implementation of NodeDataToTranslateFinder based on the modules that are currently installed.

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.

Node nameValue

 controlTypesToExport

 

 richText

info.magnolia.ui.form.field.definition.RichTextFieldDefinition

 text

info.magnolia.ui.form.field.definition.TextFieldDefinition

 composite

info.magnolia.ui.form.field.definition.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:
  tabs:
    - name: tabText
      fields:
        - name: test 
          label: Test
          layout: vertical
          class: info.magnolia.ui.form.field.definition.CompositeFieldDefinition
          transformerClass: info.magnolia.ui.form.field.transformer.composite.DelegatingCompositeFieldTransformer
          fields:
            - name: text1
              i18n: true
              label: Text 1
              class: info.magnolia.ui.form.field.definition.TextFieldDefinition
            - name: text2
              label: Text 2
              class: info.magnolia.ui.form.field.definition.TextFieldDefinition
Node nameValue

 form

 

 tabs

 

 tabText

 

 fields

 

 test

 

 fields

 

 text1

 

 class

info.magnolia.ui.form.field.definition.TextFieldDefinition

 i18n

true

 label

Text 1

 text2

 

 class

info.magnolia.ui.form.field.definition.TextFieldDefinition

 label

Text 2

 class

info.magnolia.ui.form.field.definition.TextFieldDefinition

 label

Test

 layout

Vertical

 transformerClass

info.magnolia.ui.form.field.transformer.composite.DelegatingCompositeFieldTransformer

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 nameValue

     editor

     

     form

     

     tabs

     

     personal

     

     fields

     

     bio

     

     class

    info.magnolia.ui.form.field.definition.TextFieldDefinition

     i18n

    true

     label

    Bio

     rows

    3
  2. Configure contact translation upload and download commands in the contenttranslationsupport catalog in the Content Translation module. The commands are called by the dialogs configured in step 3.
     ExampledownloadContactTranslation and uploadContactTranslation commands configured in  /modules/content-translation-support/commands/contenttranslationsupport/commands .

    Node nameValue

     commands

     

     contenttranslationsupport

     downloadContactTranslation

     

     contentTransporter


     workspace

    contacts

     formPath

    /modules/contacts/apps/contacts/subApps/detail/editor/form 

     class

    info.magnolia.module.contenttranslationsupport.commands.TranslationFileDownloadCommand 

     uploadContactTranslation

     

     class

    info.magnolia.module.contenttranslationsupport.commands.TranslationFileUploadCommand 
  3. Configure contact translation dialogs in any module. The easiest way to do this is to copy the downloadTranslationFile and uploadTranslationFile dialogs in the Content Translation Support module and change the value of the command properties. These dialogs use the commands configured in step 2. 

    ExampledownloadContactTranslation and uploadContactTranslation dialogs configured in  /modules/content-translation-support/commands/contenttranslationsupport/dialogs .

    Node nameValue

     dialogs

     

     downloadTranslationFile

     

     uploadTranslationFile

     

     downloadContactTranslation

     

     actions

     

     commit

     

     catalog

    contenttranslationsupport

     class

    info.magnolia.module.contenttranslationsupport.dialog.action.TranslationFileDownloadDialogActionDefinition

     command

    downloadContactTranslation

     label

    content-translation-support.downloadTranslationFile.actions.commit.label

     cancel

     

     class

    info.magnolia.ui.admincentral.dialog.action.CancelDialogActionDefinition

     form

     

     uploadContactTranslation

     

     actions

     

     commit

     

     catalog

    contenttranslationsupport

     class

    info.magnolia.module.contenttranslationsupport.dialog.action.TranslationFileUploadDialogActionDefinition

     command

    uploadContactTranslation

     label

    content-translation-support.uploadTranslationFile.actions.commit.label

     cancel

     

     class

    info.magnolia.ui.admincentral.dialog.action.CancelDialogActionDefinition

     form

     

    The fileFormat field uses a custom field definition class:  TranslationFileFormatOptionGroupFieldDefinition .

  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 Support app. 

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

    Node nameValue

     apps

     

     contacts

     

     subapps

     

     browser

     

     actions

     

     downloadTranslation

     

     extends

    /modules/content-translation-support/apps/contentTranslationSupport/subApps/browser/actions/downloadTranslationFile

     label

    Download for translation 

     uploadTranslation

     

     extends

    /modules/content-translation-support/apps/contentTranslationSupport/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

Scheduling translation jobs

<These configurations no longer work. Tested with both the deprecated and new commands>

You can use the Scheduler module to schedule translation export and import jobs.

Example: Exports content from /travel/about/careers to an Excel file at midnight 

Node nameValue

 modules

 

 scheduler

 

 config

 

 jobs

 

 newsTranslation

 

 params

 

 exporter

xlsExporter

 file

/Users/Shared/careers.xls

 path

/travel/about/careers

 active

true

 catalog

contenttranslationsupport

 command

exportCommand

 cron

 0 0 0 * * *

 description

Export jobs for translation


Parameters:

exporter

required

Name of the exporter node as defined in Importers and exporters:

  • xlsExporter for Excel
  • csvExporter for CSV
  • xliffExporter for XLIFF
  • googleSpreadsheetExporter for CSV suitable for Google Docs.
file

required

Path and file name where to save the exported data on the server.

path

required

Content to export. This is a path in the website workspace. All pages under the path will be exported.

Example: Importing the same Excel file once it has been translated

Node nameValue

 modules

 

 scheduler

 

 config

 

 jobs

 

 newsTranslationImport

 

 params

 

 file

/Users/Shared/careers.xls

 importer

xlsImporter

 path

/travel/about/careers

 active

true

 catalog

contenttranslationsupport

 command

importCommand

 cron

 0 0 0 * * *

 description

Import translated jobs

Observing nodes for translation

<Hidden because schedling no longer works. Suspected that same would happen here>

You can use the Observation module to listen for changes in the website workspace and execute the ExportCommand command when they occur.

Example: Execute the ExportCommand when a new page is added in the About section.

Node nameValue

 observation

 

 config

 

 listenerConfigurations

 

 exportForTranslation

 

 listener

 

 command

 

 class

info.magnolia.module.contenttranslationsupport.commands.ExportCommand

 params

 

 exporter

xlsExporter

 file

/Users/Shared/export.xls

 path

/travel/about

 class

info.magnolia.module.observation.commands.RestrictToNodeTypeEventListener 

 nodeType

mgnl:contentNode

 active

true

 description

Export articles for translation

 eventTypes

NODE_ADDED

 includeSubNodes

true

 path

/travel/about

 repository

website