You can translate Confluence content in a Translation Management System (TMS) by exporting a space as a ZIP file, and then importing this ZIP to your TMS.

First steps

  • To create a translation ZIP of a space, you must have either Space Admin or Confluence Admin permissions, or be a Doc-Admin.
  • You can only follow the steps in this guide if you have already activated and configured Scroll Translations in the space you want to export.

Create a translation ZIP

The first step is to create the translation ZIP, by navigating to Space Tools > Scroll Add-ons > Translations > New translation.

The export does not respect viewing permissions

All pages within the scope of the export will be exported – even view-restricted pages. If a user who generates the translation ZIP doesn't have access to all pages in the space, all pages that fall within the scope of the export (version, variant, language) will still be exported in the XML.

You have multiple options when creating the translation ZIP:

Translation format

Choose between XLIFF and Simple.

We recommend XLIFF, as it is a standardized format that requires no configuration in the TMS. Scroll Translations uses XLIFF version 1.2.

The Simple translation format is an XML export of the Confluence storage format – the translator's TMS must be configured to work with this format.

Output format

Create one single file, or one file per translated page.

This setting is only available with the Simple Translation format option.

Target language

The language you want the source content to be translated to.

VersionIf Scroll Versions' version management feature is activated, you can choose which version to export.
VariantIf Scroll Versions' variant management feature is activated, you can choose which variant to export.

Select 'All pages' to export all pages within the scope of the export.

If you select 'Outdated pages only', pages that have the translation status 'Complete' are excluded from the export.

Workflow status

If this option is activated, only pages with the Scroll Versions workflow status 'complete' will be exported in the ZIP.

XLIFF translation format: specify which custom and third-party macros should be translated 

If you chose the XLIFF translation format, then by default, the parameters and body of 'unknown' macros (custom user macros and third-party macros) will not be translated. If you want to translate them, you need to define which parameters should be translated. You can only specify text parameters to be translated – all other parameter types can't and shouldn't be translated.

To specify which text parameters and macro bodies should be translated, log in as a global admin and navigate to  General Configuration > Scroll Runtime > Advanced Plugin Settings > Scroll Platform >translations.custom.macro.translation.

The plugin setting value has to be a JSON object consisting of multiple key/value pairs representing macros. The key represents the macro name, while the value is another JSON object consisting of a "parameters" and "body" attribute:

  • "parameters" is an object with parameter names as attributes and booleans as values. Boolean values indicate if parameters should be translated or not. Every parameter not listed here will not be translated.
  • "body" is a boolean value indicating if the body should be translated or not. 

For example, the following JSON will cause the body of "warning" and "code" macros not to be translated, while the "title" parameter for the "code" and "status" macros will be translated, whereas the "theme" parameter will not:

	"warning": {"body": false},
	"status": {"parameters": {"title" : true}},
	"code": {"parameters": {"title" : true , "theme" : false}, "body": false}

If a macro is specified in the plugin settings, the default values for this macro will be overwritten.

Simple translation format: configure your TMS 

If you chose the Simple translation format, the TMS where the ZIP will be translated must be configured to work with this format. This section describes the export format of the exported ZIP file, so you can configure it in your TMS.

Export vs. Import Files

Export and import files have exactly the same structure, and only differ in the metadata that is being set on the top-level translation element.

Exported files are named as follows:


The contained XML file follows the same naming scheme, except for the file extension:


XML schema

The schema of the XML file is very simple:

+- translation (+ attributes)
   +- page (+ attributes)
      +- title
      +- content
         +- [Confluence Storage Format]

Translation element

The translation element represents a translation of one or more pages in the specific language.


spaceKeyThe space key of the content.(tick)
languageThe language of the content in the file.(tick)

The original language of the content in Confluence.

In export files, it should have the same value as the language attribute.


The requested language of the translation.

In import files, it should have the same value as the language attribute.



The id of the translated version.

If the currently published versions exported or if the version management is not enabled in the current space, the value will be 'current'.


The id of the translated variant.

If all pages are exported, the value will be 'all'.

exportTimestampThe time of the export.(tick)

Page element

The page elements represents a page to be translated.


pageIdThe Confluence page ID.(tick)
versionThe version of the page.(tick)

Title element

The title contains the title of the page in the specific language as <![CDATA[Title]>.

The content element 

The content is provided in the Confluence storage format as anyType. In order to make the storage format work in the translation management system, links that contain CDATA as body need to be transformed to a separate representation to improve the handling in the translation systems.

    <ri:page ri:content-title="Page Title" />
        <![CDATA[Link to another Confluence Page]]>

will be exported as

    <ri:page ri:content-title="Page Title" />
        <span class="sv-cdata-translate">Link to another Confluence Page</span>

Update the translated ZIP's language attribute

After you get your now translated translation ZIP back from TMS, you can update the language attribute in the XML file. This is not necessary, but it prevents an error message appearing when re-importing the translation ZIP.

Translation-descriptor timestamp must match the timestamp of the XLF files. Archiving some old translation-descriptor with newer XLF files won't work.

To update the translation zip follow the steps below:

  1. Unzip the translated ZIP
  2. Open the translation-descriptor.xml file (if you selected One file per page when creating the translation ZIP) or the translation file (if you selected One file per page when creating the translation ZIP) in a text editor.
  3. Change the language value to be the same as the targetLanguage value:
  4. Save the file and ZIP it again.

Re-import the translated ZIP

Now, you're ready to import the ZIP back into your Confluence system.

Before importing the ZIP file you have to make sure that the files in there are properly structured. The translated XML files and the translation-descriptor.xml file must be on top level in the ZIP file, as they originally were in the exported ZIP file.


  • Instead of archiving a folder with XLIFF files, archive them directly without a folder. Then upload this ZIP file.
  • If you want to create archives on macOS without dot files, use this command in Terminal
    zip -r directory -x "*/\.DS_Store"
  1. Open the space where you want to import the translation ZIP, then navigate to Space tools > Scroll Add-ons > TranslationsImport Translation, and import the ZIP.
  2. The file will be validated, and an overview of the target language and the number of imported pages is displayed.
  3. Select if you want to Notify watchers, then click Import.

Now, the translated pages are available in the translated language.