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.
Please note that the artifact's IDs (Maven
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.
See also the Content Translation Support Extended (CTSX) module, which provides automated translation services for your content.
Maven is the easiest way to install the module. Add the following dependencies to your bundle:
Note the changes in
artifactId since the 2.2 release.
<dependency> <groupId>info.magnolia.translation</groupId> <artifactId>magnolia-content-translation</artifactId> <version>2.5</version> </dependency>
<dependency> <groupId>info.magnolia.translation</groupId> <artifactId>magnolia-content-translation-pages-integration-app</artifactId> <version>2.5</version> </dependency>
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-compatibilitymodule together with the
Add the following snippet to your pom file:
<dependency> <groupId>info.magnolia.translation</groupId> <artifactId>magnolia-content-translation-support-compatibility</artifactId> <version>2.5</version> </dependency>
The module is configured in the following JCR nodes:
In addition, the following directories in the Resource Files app contain configuration by file:
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:
- Select a page. Subpages are included in the export file.
- Click Export translation.
- Select a file format
- 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:
- Select the page.
- Click Import translation.
- Upload the file.
- Optionally check the overwrite and import empty translations options.
- Click Import File.
In the Pages app, you can now see the translated content in the components and dialogs.
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.
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
Class that performs the import or export (
File extension without the dot.
The module includes two
TranslationFile commands that are used to export and import content in various formats for translation.
Commands are configured in
Content translation support catalog.
The path to the form.
The module includes some dialog actions that are used in the Content Translation app.
Example: Commit actions to download and upload files in
These actions are configured by file, for example in Resource Files >
/translation/dialogs/downloadTranslationFile.yaml, not in JCR nodes.
Commit action configuration.
Action definition class. See below.
Name of command configuration node.
Action labels: Export file and Import file.
Action definition classes:
|Uploads the translation file.|
|Downloads the translation file.|
Used in the app to open the
What is exported and imported
The type of exported content is configured in
Module configuration folder.
Defines the field types to export.
Node data to translate finder node.
AdaptivePropertiesToTranslateFinder delegates calls to an implementation of
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
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
Example: Composite field configuration where
text1 field will be included in the download file, but
text2 will not.
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.
i18nproperty to any field you want to translate in the
detailsubapp. See Enabling mulitlanguage content for more information.
Example: New text field called
bioin the Personal tab under
Configure contact translation upload and download commands in the
translationcatalog in the
translationmodule. The commands are called by the dialogs configured in step 3.
uploadContactTranslationcommands configured in
- Configure contact translation dialogs in any module. The easiest way to do this is to copy the
uploadTranslationFiledialog definition files in Resource Files
/translation/dialogs/and change the value of the
commandproperties. These dialogs use the commands configured in step 2.
uploadContactTranslationdialogs configured in
- Add translation download and upload actions in the
browsersubapp. The easiest way to do this is to extend the
uploadTranslationFileactions in the Content Translation app.
uploadTranslationactions in the Contacts app in
Add the actions created in step 4 to the actionbar.
uploadTranslationactions to the
contactsection of the actionbar in the Contacts app in