Get Started With External Translation

What Is External Translation?

Scroll Translations provides an XLIFF export feature allowing users to translate Confluence content in combination with Translation Management Systems or external translation agencies. The basic flow of external translation would be as follows:

The XML Localization Interchange File Format (XLIFF) is an XML-based file format that is frequently used by computer-aided translation tools. Learn more about XLIFF 1.2.

Create a Translation ZIP

To generate and download a translation ZIP file, navigate to Space Tools > Scroll Add-ons > Languages . There, locate the row for the target language and select Export.

The Languages management screen where languages can be defined and translation files can be managed

Before you export a translation file, you need to fulfill the following prerequisites:

Acquire space admin permissions or the Doc-Admin role, this is required to export a space for translation.
Configure Scroll Translations and define a target language.

Configure the export

When exporting, you can select from different format and configuration options.

Export translation dialog showing the different export configuration options

Find each format and configuration option explained in the table below:

Field	Options	Description
Translation format	XLIFF Confluence storage format	We recommend XLIFF, as it is a standardized format that requires no configuration in the TMS. Scroll Translations uses XLIFF version 1.2. The Confluence storage format requires translation in the XML directly – the translator's TMS must be configured to work with this format.
Output format	One single file One file per page	Create one single file, or one file for every translated page. For bigger spaces we recommend exporting one file per page.
Version	Available versions	If Scroll Versions' version management feature is activated, you can choose which version to export.
Variant	Available variants	If Scroll Versions' variant management feature is activated, you can choose which variant to export.
Pages	All pages Outdated pages only	If you select "Outdated pages only", pages that have the translation status "Complete" are excluded from the export.
Labels	Exclude labels (optional) Include labels (optional)	Exclude: Pages with these labels will not be included in the translation ZIP Include: Only pages with these labels will be included in the translation ZIP
Workflow status	Export only complete pages (optional)	If this option is activated, only pages with the Scroll Versions workflow status "Complete" will be exported in the ZIP.

The export does not respect viewing permissions

Similar to other Confluence space content exports, all pages within the scope of the export will be exported – even view-restricted pages.

While the Content Is in Translation

External translation of an entire space can take a while. During that time, we generally recommend to restrain from editing both the original and the target language. Changes to the target language will be overwritten when the XLIFF is important, while changes to the original language will cause the translation to be outdated upon import. Of course, necessary changes can still be made, just keep the effects in mind.

Import the Translated ZIP

Once the XLIFF files have been translated, you're ready to import them back into your Confluence space.

Scroll Translations expects a ZIP file structured exactly as the one you originally downloaded. Before importing the ZIP file, make sure the translated XML files and the translation-descriptor.xml file are on top level in the ZIP file.

To import a translation file, follow the steps below:

Navigate to Space tools > Scroll Add-ons > Languages > Import Translation.
Select or drag and drop the ZIP containing the translated files.
On the ZIP validation screen, check the target language and the number of imported pages.
Select if you want to notify watchers, then click Import.

You're done! The pages and their content will now appear translated in your space.

Below are some tips you can apply when zipping your translation files:

To make sure the XLIFF files are on top level, archive them directly, not the containing folder.
When creating a ZIP archive on macOS, use this command in terminal to prevent hidden system files from be included in the ZIP.
zip -r archive.zip directory -x "*/\.DS_Store"

What's Next?

Working With XLIFF: Learn about our XLIFF structure and configuring translatable macros.
Working with Storage Format: Learn about translating Confluence format directly and how TMS tools can be configured to support it.