The Content Translation Support module installs the Content Translation app that allows you to manually export and re-import page content in translation-friendly XLIFF, CSV and Excel formats.

The Content Translation Support module (warning) Magnolia 5.3+ 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. The module comes with a Content Translation app. 

Download

The Content Translation Support module is bundled with Magnolia and typically already installed. You can download it from our Nexus repository

Installing

Content Translation Support is a Enterprise Edition module. It is typically already installed. Launch the Configuration app and go to /modules/content-translation-support to check.

(warning) Create a backup of your system before you install a module. Uninstalling a module is not as simple as removing the .jar file. Modules add and change configurations and may change the content. Try new modules in a test environment first. A module consists of a JAR file and may include dependent JAR files. Modules are responsible for updating their own content and configurations across versions. Be sure to keep only one version of each module and its dependencies.

To install a module:

  1. Stop the application server.
  2. Copy the module JAR files into the WEB-INF/lib directory. The location of this directory depends on the application server.
    • Tomcat: /webapps/magnoliaAuthor/WEB-INF/lib
    • JBoss: /server/default/deploy/magnoliaAuthor/WEB-INF/lib
  3. Restart the server.
  4. Go to the AdminCentral URL.
  5. Start the Web update process.
  6. Click Start up Magnolia.

Repeat the steps for each author and public instance.

Uninstalling

To uninstall a module, remove the module JAR file from the /WEB-INF/lib folder and restart Magnolia.

(warning) However, this is rarely enough. Modules add and modify configuration during installation. The use of a module also changes content. Removing all of these changes is difficult without knowing the installation tasks in detail.

To test a module, use the embedded Derby database and take a backup of your repositories folder. Install the module and try it. When you are done testing, remove the module JAR and restore the repositories folder from the backup. This way you can go back to square one.

We also recommend that you segregate the development and production environments. Take regular backups for disaster recovery so you can revert to a prior state in a routine fashion.

Configuration

The module is ready to use and configured at Configuration > /modules/content-translation-support.

Node nameValue

 modules

 

 content-translation-support

 

 apps

 

 config

 

 dialogs

 

 commands

 

 fieldTypes

 

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 STK > Site Definitions.  Here's the /default definition with English as the default locale and German and simplified Chinese as additional locales.

Node nameValue

 default

 

 template

 

 themes

 

 variations

 

 i18n

 

 locales

 

 en

 

 de

 

 country

 -

 enabled

 true

 language

 de

 zh_CN

 

 country

CN

 enabled

 true

 language

zh

 class

info.magnolia.cms.i18n.DefaultI18nContentSupport

 defaultLocale

 en

 enabled

 true

 fallbackLocale

 en

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 at Configuration > /modules/content-translation-support/config.

Node nameValue

 modules

 

 content-translation-support

 

 config

 

 importers

 

 xlsImporter

 

 class

info.magnolia.module.contenttranslationsupport.reimport.XlsTranslationBundleUpdateReader

 extension

 xls

 label

contenttranslation.fileformat.xls

 csvImporter

 

 xliffImporter

 

 exporters

 

 xlsExporter

 

 csvExporter

 

 xliffExporter

 

 googleSpreadsheetExporter

 

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

There are two sets of equivalent commands. The TranslationFile commands are used by the app and the exportContent and importConent commands are suitable to scheduling and observation.

Commands are configured at Configuration > /modules/content-translation-support/commands.

  • TranslationFileDownloadCommand:
    • 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>.
  • TranslationFileUploadCommand:
    • 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.
  • The /website node extends the website command's catalog to ensure that publication and unpublication of pages is subject to workflow.
Node nameValue

 modules

 

 content-translation-support

 

 commands

 

 content-translation-support

 

 exportContent

 

 class

info.magnolia.module.contenttranslationsupport.commands.ExportCommand

 importContent

 

 class

info.magnolia.module.contenttranslationsupport.commands.ImportCommand

 importEmptyValues

false

 overwriteExistingValues

false

 downloadTranslationFile

 

 class

info.magnolia.module.contenttranslationsupport.commands.TranslationFileDownloadCommand

 uploadTranslationFile

 

 class

info.magnolia.module.contenttranslationsupport.commands.TranslationFileUploadCommand

 website

 

 extends

/modules/pages/commands/website

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  richText and text field definitions. These field types contain the textual i18n content.
  • nodeDataToTransferFinder: The STKDialogBasedNodeDataToTranslateFinder class is a STK-specific finder class that finds the relevant i18n content.
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.STKDialogBasedNodeDataToTranslateFinder 

Content Translation app

The  Content Translation app  allows you to manually export pages for translation and re-import translated pages. You can also preview and publish pages. The app is available at  Tools > Content Translation .

  • Preview page: Opens the the page in preview mode in the Pages app.
  • Publish and Unpublish are subject to workflow. 

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:

  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. 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 app. The translated content is automatically included on the page.

To import translated content:

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

In the Pages app 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. 

Node nameValue

 history

 

 extras

 

 promos

 

 base

 

 footer

 

 content

 

 metaNavigation

 

 comments

 

 abstract

This is the abstract for the History page. It is a brief...

 abstract_de

Dies ist die Zusammenfassung für die Geschichte-S...

 abstract_zh_CN

这是一个抽象的历史页面。是页的内容的简要介绍。摘...

 categories

[d7ba9d64-b7b8-4b93-8a3d-ecd14a049bb8, 248f71e9...

 hideInNav

false

 imageLocation

above

 title

History

 title_de

Geschichte

 title_zh_CN

历史

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.
Node nameValue

 modules

 

 scheduler

 

 config

 

 jobs

 

 newsTranslation

 

 params

 

 exporter

xlsExporter

 file

/Users/Shared/newsExport.xls

 path

/demo-project/news-and-events

 active

true

 catalog

contenttranslationsupport

 command

exportCommand

 cron

 0 0 0 * * *

 description

Export news content for translation

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

Node nameValue

 modules

 

 scheduler

 

 config

 

 jobs

 

 newsTranslationImport

 

 params

 

 file

/Users/Shared/newsExport.xls

 importer

xlsImporter

 path

demo-project/news-and events

 active

true

 catalog

contenttranslationsupport

 command

importCommand

 cron

 0 0 0 * * *

 description

Import translated news content

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.

Node nameValue

 observation

 

 config

 

 listenerConfigurations

 

 exportForTranslation

 

 listener

 

 command

 

 class

info.magnolia.module.contenttranslationsupport.commands.ExportCommand

 params

 

 exporter

xlsExporter

 file

/Users/Shared/export.xls

 path

demo-project/about

 class

info.magnolia.module.observation.commands.RestrictToNodeTypeEventListener 

 nodeType

mgnl:contentNode

 active

true

 description

Export articles for translation

 eventTypes

NODE_ADDED

 includeSubNodes

true

 path

/demo-project/about

 repository

website
#trackbackRdf ($trackbackUtils.getContentIdentifier($page) $page.title $trackbackUtils.getPingUrl($page))

To comment, create an account and log in.

© Copyright 2023 Magnolia