DITA Translation Package Builder

Attention: This script is bundled with the all platforms distribution of Oxygen XML Author Eclipse plugin. To run the script, you are required to purchase a special scripting commercial license.

The DITA Translation Package Builder (translationPackageBuilder.sh, found in the scripts subfolder inside Oxygen's installation directory) script helps you to build a translation package for DITA files that can be sent to translators. You can also extract the changed files back into your project once you receive the package back from the translators.

This script requires the DITA Translation Package Builder add-on to be installed in the all platforms distribution of Oxygen XML Author Eclipse plugin. To install it the add-on, follow these instructions:

Go on the DITA Translation Package Builder plugin Releases page and download the latest translation-package-builder-{version}-plugin.jar package.
Unzip it inside {oxygenInstallDir}/plugins.
Note: Do not create any intermediate folders. Afterwards, the file system should look like this: {oxygenInstallDir}/plugins/translation-package-builder-{version}/plugin.xml

Examples for the DITA Translation Package Builder Script

Example: Generating a Milestone File

sh scripts/translationPackageBuilder.sh -gm -i ditamapFile [-m milestoneFile] [-verbose]

This action is the first one to use. It will generate a unique hash for each documentation resource. This information will be used by the second action to detect which files have been modified. A milestone file should be generated the first time you install this plugin and henceforth, after each package is sent to translators.

-gm: Requests the generation of a milestone file.
-i ditamapFile: The main DITA map file.
-m milestoneFile: The path to the milestone file. If missing, it is assumed that the milestone will be saved in the DITA map parent folder with the following name: {ditamapName}_translation_milestone.xml.
-verbose: Generates a console log about the performed steps. It is useful for debugging.

Example: Creating a Package with the Modified Files to Send to Translation

sh scripts/translationPackageBuilder.sh  -gp -i ditamapFile [-m milestoneFile] -p package.zip [-verbose]

This action detects which files have been changed since the last generated milestone. These files are packed inside a ZIP file that can be sent to translators. After doing this, you can also generate a new milestone so that the next package will only contain new changes.

-gp: Requests the generation of a package with the modified files.
-i ditamapFile: The main DITA map file.
-m milestoneFile: The path to the milestone file. If missing, it is assumed that the milestone will be located in the DITA map parent folder with the following name: {ditamapName}_translation_milestone.xml.
-p package.zip: The path to the zip archive where all the modified files are collected.
-verbose: Generates a console log about the performed steps. It is useful for debugging.

Example: Applying a Translation Package Over a DITA Map

sh scripts/translationPackageBuilder.sh -ap -i ditamapFile -p package.zip [-verbose]

When the translated files arrive from the translator, you should open the DITA map that corresponds to the received language (e.g. open dita-map-french.ditamap if the package contains the french translation). Invoking this action will extract the changed files inside the map's directory.

-ap: Requests the application of a translation package over a DITA map.
-i ditamapFile: The main DITA map file that matches the received package language. For example, if the package contains topics translated into French, then this map is the French version of your DITA map.
-p package.zip: The path to the archive with all the translated files.
-verbose: Generates a console log about the performed steps. It is useful for debugging.