Content Translation Support module

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

Download

Download the Content Translation Support module from Magnolia Store or Nexus repository.

Installing

Content Translation Support is an enterprise module included in the Enterprise Edition bundle and typically already installed. Go to Magnolia Store > Installed modules in AdminCentral to check. To install the module individually, see the general module installation instructions.

Uninstalling

Please see the general module uninstalling instructions and advice.

Configuration

The module is ready to use and configured in /modules/content-translation-support.

Locales

The module is fully integrated with the Standard Templating Kit. Your website needs to have at least one locale in addition to the default locale. Locales will show up as columns in the export file. Locales are defined in Templating Kit > Site Definitions. Here's the /default definition with English as the default locale and German and simplified Chinese as additional locales.

Importers and exporters

Importers and exporters are Java classes that contain business logic to convert translatable content into 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.

Properties:

<importer/exporter name>
- class: Fully qualified name of the class that contains the business logic. See class names below.
- extension: File extension without the dot.
- label: i18n key of the label that is displayed in the dialog. See Language on how to use keys.

Class names:

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 or to store translatable text in a database or send it to a Web service that translators use. See GIT for exporter examples.

Commands

Commands are configured in /modules/content-translation-support/commands.

ExportCommand:
- Downloads files from a specified path in the website workspace, in a specified format, for translation.
- Calls the relevant exporter class.
- The exported file contains all page content nodes marked as i18n in the template definitions.
- The file path in the repository is converted into the file name by replacing forward slashes with dots. For example the file name for /demo-project/about/history page is website.demo-project.about.history.<file extension>.
ImportCommand:
- Uploads translated files in a specified format to a specified path in the website workspace.
- Calls the relevant importer class.
- Content is uploaded to relevant i18n fields in the dialogs.

What is exported and imported

The ContentTranslationSupportModule class supports two configuration nodes that define the content types that are exported and imported.

controlTypeToExport: Registers the fckEdit and edit control definitions. These control types contain the textual i18n content.
nodeDataToTransferFinder: The STKDialogBasedNodeDataToTranslateFinder class is a STK-specific finder class that finds the relevant i18n content.

Content translation tool

The content translation tool allows you to manually export pages for translation and re-import translated pages. The tool is available at Tools > Content Translation.

Exporting content for translation

We use the googleSpreadsheetExporter exporter to demonstrate. 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.

To export content:

Choose a page. Subpages are included in the export file.
Select a file format
Click Download file.

The download filename is created from the file path in the website workspace, with dots replacing forward slashes. In our example website.demo-project.about.history.csv. 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>. Empty columns for each locale configured for the site. German (de) and Chinese (zh_CN) in the example below. This is where the translator types the corresponding target language text.

Uploading to Google Docs

You can upload the file to Google Docs for automatic machine-translation, or to give your translator a useful starting point. In Google Docs ensure that you have the Settings > Upload Settings > Convert documents, presentations, spreadsheets, and drawings to the corresponding Google Docs format option selected.

Here's the History page in Google Docs. You can now download the file and save it as a CSV file for import into Magnolia.

Importing translated content

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

To import translated content:

Upload the file.
Select the format.
Optionally check the overwrite and import empty translations options.
Click Upload file.

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

i18n content storage

You can view the translated content in the website workspace in Tools > JCR. Here the page properties for the History page. The translated content is suffixed with a language identifier, _de and zh_CN in our example. Since English is the default language on this site no _en identifier is used.

Scheduling translation jobs

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

Here is an example export job that exports content from /demo-project/news-and-events to an Excel file on the local computer at midnight. You need to pass the following parameters under the params node:

exporter. File format to save in. Choose xlsExporter for Excel, csvExporter for CSV or googleSpreadsheetExporter for CSV suitable for Google Docs.
file. Path and file name where to save the exported data.
path. Content to export. This is a path in the website workspace. All pages under the branch will be exported.

Here is an example of an import job that imports the same Excel file once it has been translated.

Observing nodes for translation

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

Here's an example configuration that executes the ExportCommand command when a new page is added in the About section of the demo-project website.

Page tree