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.
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:
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.
GoogleSpreadsheetTranslationBundleWriter 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.
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.
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.
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.
Used in the app to open the uploadTranslationFile dialog.
The downloadTranslationFile dialog is opened with
info.magnolia.ui.dialog.actions.OpenDialogActionDefinition.
See Action definition
classes for more information.
Registers
rich
text field and
text
field definition classes. These field types typically contain the
textual i18n content.
propertiesToTranslateFinder
required
Node data to translate finder node.
class
required
info.magnolia.translation.finder.AdaptivePropertiesToTranslateFinder
delegates calls to an implementation of PropertiesToTranslateFinder
based on the modules that are currently installed.
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.
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.
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 the
detail 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.
Configure contact translation upload and download
commands in the translationcatalog 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.
Configure contact translation dialogs in any module. The easiest way
to do this is to copy the downloadTranslationFile and
uploadTranslationFile dialog definition files in 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.
Add translation download and upload actions in the 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.
Example: Adding downloadTranslation and uploadTranslation actions
to the contact section of actionbar in the Contacts app in
/modules/contacts/apps/contacts/subApps/browser/actionbar/sections/contact/groups/importExportActions.