Content Translation Support module
Content management Bundled: DX Core
Edition | DX Core |
---|---|
License |
|
Issues |
|
Maven site |
|
Latest |
2.5.11 |
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.
Module artifacts have changed
Please note that the artifact IDs (Maven 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 Extended module (CTSX) module, which provides automated translation services for your content.
Note the changes in |
Installing with Maven
Bundled modules are automatically installed for you.
If the module is unbundled, add the following to your bundle including your project’s <dependencyManagement>
section and your webapp’s <dependencies>
section.
If the module is unbundled but the version is managed by the parent POM, add the following to your webapp’s <dependencies>
section.
<dependency>
<groupId>info.magnolia.translation</groupId>
<artifactId>magnolia-content-translation</artifactId>
<version>2.5.11</version> (1)
</dependency>
1 | Should you need to specify the module version, do it using <version> . |
<dependency>
<groupId>info.magnolia.translation</groupId>
<artifactId>magnolia-content-translation-pages-integration-app</artifactId>
<version>2.5.11</version> (1)
</dependency>
1 | Should you need to specify the module version, do it using <version> . |
Compatibility module
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, you must do one of two things:
-
Update your code for the new version of the Content Translation Support module.
-
Use the
magnolia-content-translation-support-compatibility
module together with themagnolia-core-compatibility
module.
Add the following snippet to your POM file:
<dependency>
<groupId>info.magnolia.translation</groupId>
<artifactId>magnolia-content-translation-support-compatibility</artifactId>
<version>2.5.11</version> (1)
</dependency>
1 | Should you need to specify the module version, do it using <version> . |
Configuration
The module is configured in the following JCR nodes:
-
/modules/translation
-
/modules/translation-pages-integration
In addition, the following directories in the Resource Files app contain configuration by file:
-
/translation/dialogs
-
/translation/fieldTypes
-
/translation/i18n
Content Translation app
The Content Translation app allows you to manage the translation of pages.
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.
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.
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 uploading to Google Docs.
Importers and exporters are configured in /modules/translation/config
.
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:
|
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. |
|
optional File extension without the dot. |
|
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/translation/commands/translation
.
translation:
commands:
translation:
downloadTranslationFile:
class: info.magnolia.translation.commands.TranslationFileDownloadCommand
uploadTranslationFile:
class: info.magnolia.translation.commands.TranslationFileUploadCommand
Property | Description |
---|---|
|
required Commands folder. |
|
required Content translation support catalog. |
|
required
|
|
required The path to the form. |
|
required Workspace name. |
|
required
|
Action definitions
The module includes some dialog actions that are used in the Content Translation app.
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 Resource Files >
/translation/dialogs/downloadTranslationFile.yaml
, not in JCR nodes.
form:
properties:
...
actions:
commit:
command: downloadTranslationFile
catalog: translation
class: info.magnolia.translation.ui.action.TranslationFileDownloadDialogActionDefinition
cancel:
class: info.magnolia.ui.dialog.action.CancelDialogActionDefinition
form:
properties:
...
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
Property | Description |
---|---|
|
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. |
info.magnolia.translation.ui.action.*
definition classes:
|
Uploads the translation file. |
||
|
Downloads the translation file. |
||
|
Used in the app to open the
|
What is exported and imported
Text and rich text fields are included in export files by default. Additional fields types can be registered, but they must be configured using Magnolia 6 UI.
The type of exported content is configured in
/modules/translation/config/supportedFieldDefinitions
and
/propertiesToTranslateFinder
.
modules:
translate:
config:
importers:
exporters:
supportedFieldDefinitions:
richText: info.magnolia.ui.field.RichTextFieldDefinition
text: info.magnolia.ui.field.TextFieldDefinition
propertiesToTranslateFinder:
class: info.magnolia.translation.finder.AdaptivePropertiesToTranslateFinder
Property | Description |
---|---|
|
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 info.magnolia.translation.finder.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 info.magnolia.ui.field.CompositeFieldDefinition
).
Example: Registering composite field as a field type to export.
supportedFieldDefinitions:
richText: info.magnolia.ui.field.RichTextFieldDefinition
text: info.magnolia.ui.field.TextFieldDefinition
composite: info.magnolia.ui.field.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:
properties:
test:
$type: compositeField
itemProvider: currentItemProvider
properties:
- name: text1
$type: textField
i18n: true
- name: text2
$type: textField
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.
Enabling content translation in content apps
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 thedetail
subapp. See Enabling mulitlanguage content for more information.Example: New text field called
bio
under/modules/contacts/apps/contacts/subApps/detail/editor/form/fields/bio
.editor: form: fields: bio: $type: textField i18n: true rows: 3
-
Configure contact translation upload and download commands in the
translation
catalog in thetranslation
module. The commands are called by the dialogs configured in step 3.Example:
downloadContactTranslation
anduploadContactTranslation
commands configured in/modules/translation/commands/translation/commands
.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
-
Configure contact translation dialogs in any module. The easiest way to do this is to copy the
downloadTranslationFile
anduploadTranslationFile
dialog definition files in Resource Files/translation/dialogs/
and change the value of thecommand
properties. These dialogs use the commands configured in step 2.Example:
downloadContactTranslation
anduploadContactTranslation
dialogs configured in/modules/translation/commands/translation/dialogs
.downloadContactTranslation.yamlform: properties: ... actions: commit: command: downloadContactTranslation catalog: translation class: info.magnolia.translation.ui.action.TranslationFileDownloadDialogActionDefinition cancel: class: info.magnolia.ui.dialog.action.CancelDialogActionDefinition
uploadContactTranslation.yamlform: properties: ... 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
-
Add translation download and upload actions in the
browser
subapp. The easiest way to do this is to extend thedownloadTranslationFile
anduploadTranslationFile
actions in the Content Translation app. Example: AddingdownloadTranslation
anduploadTranslation
actions in the Contacts app in/modules/contacts/apps/contacts/subApps/browser/actions
.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
actionbar
.Example: Adding
downloadTranslation
anduploadTranslation
actions to thecontact
section ofactionbar
in the Contacts app in/modules/contacts/apps/contacts/subApps/browser/actionbar/sections/contact/groups/importExportActions
.browser: actionbar: sections: contact: groups: importExportActions: items: export: downloadTranslation: uploadTranslation: