Magnolia 5.6 reached end of life on June 25, 2020. This branch is no longer supported, see End-of-life policy.
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.
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.
See also the Content Translation Support Extended (CTSX) module, which provides automated translation services for your content.
Note the changes in groupId
and artifactId
since the 2.2 release.
With Magnolia 5.6 we've begun removing the old Content API from our modules. If you have custom code relying on classes from the old form module then you must do one of two things:
magnolia-content-translation-support-compatibility
module together with the magnolia-core-compatibility
module.The module is configured in the following JCR nodes:
/modules/translation
/modules/translation-pages-integration
Node name | Value |
---|---|
modules | |
translation | |
config | |
commands |
Node name | Value |
---|---|
modules | |
translation-pages-integration | |
apps |
In addition, the following directories in the Web Dev > Resource Files app contain configuration by file:
/translation/dialogs
/translation/fieldTypes
/translation/i18n
The Content Translation app allows you to manage the translation of pages. The app is in the Tools section in the app launcher.
To export pages:
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):
Text and Image: Subheading
. This tells the translator what kind of page element he is translating.The GoogleSpreadsheetTranslationBundleWriter
importers and exporters 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.
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:
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.
Example: travel
site definition with English and German locales.
Node name | Value |
---|---|
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 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 /modules/translation/config
.
Node name | Value |
---|---|
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 |
Properties:
class | required Class that performs the import or export (
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. |
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
.
Node name | Value |
---|---|
translation | |
commands | |
translation | |
downloadTranslationFile | |
class | info.magnolia.translation.commands.TranslationFileDownloadCommand |
uploadTranslationFile | |
class | info.magnolia.translation.commands.TranslationFileUploadCommand |
Properties:
commands | required Commands folder. |
| required Content translation support catalog. |
| required
|
| required The path to the form. |
| required Workspace name. |
| required
|
The module includes some dialog actions that are used in the Content translation app. These can be Enabling content translation in content apps.
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 Web Dev > Resource Files > /translation/dialogs/downloadTranslationFile.yaml
, not in JCR nodes.
form: ... actions: commit: command: downloadTranslationFile catalog: translation class: info.magnolia.translation.ui.action.TranslationFileDownloadDialogActionDefinition cancel: class: info.magnolia.ui.dialog.action.CancelDialogActionDefinition
form: tabs: ... 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
commit | required Commit action configuration. |
| required
|
| required Action definition class. See below. |
| required Name of command configuration node. |
| optional 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 * |
By default, text and rich text fields are included in export files, and additional field types can be Registering additional field types.
The type of content that is exported is configured in /modules/translation/config/supportedFieldDefinitions
and /propertiesToTranslateFinder
.
Node name | Value |
---|---|
modules | |
translate | |
config | |
importers | |
exporters | |
supportedFieldDefinitions | |
richText | info.magnolia.ui.form.field.definition.RichTextFieldDefinition |
text | info.magnolia.ui.form.field.definition.TextFieldDefinition |
propertiesToTranslateFinder | |
class | info.magnolia.translation.finder.AdaptivePropertiesToTranslateFinder |
Properties:
config | optional Module configuration folder. |
| required Defines the field types to export. |
| required Registers rich text field and text field definition classes. These field types typically contain the textual i18n content. |
| required Node data to translate finder node. |
| required
|
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 name | Value |
---|---|
supportedFieldDefinitions | |
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.
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 name | Value |
---|---|
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 |
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.
You can enable content translation support in any content app.
Example: Enabling content translation in the Contacts app.
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 name | Value |
---|---|
editor | |
form | |
tabs | |
personal | |
fields | |
bio | |
class | info.magnolia.ui.form.field.definition.TextFieldDefinition |
i18n | true |
label | Bio |
rows | 3 |
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
Node name | Value |
---|---|
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 |
downloadTranslationFile
and uploadTranslationFile
dialog definition files in Web Dev > 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
form: ... actions: commit: command: downloadContactTranslation catalog: translation class: info.magnolia.translation.ui.action.TranslationFileDownloadDialogActionDefinition cancel: class: info.magnolia.ui.dialog.action.CancelDialogActionDefinition
form: tabs: ... 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
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
.
Node name | Value |
---|---|
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 |
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 |