DITA-XLIFF Roundtrip for OT
===========================
This tool will transform an entire DITA project into a single XLIFF file, so you
can translate the XLIFF file, then transform the translated XLIFF back into
DITA. It is designed to work with the DITA Open Toolkit 1.8.
Two versions of each plugin are provided:
* The `v12` variants generate or convert from the XLIFF version 1.2 format
<http://docs.oasis-open.org/xliff/xliff-core/xliff-core.html>
* The `v2` plugins create and read XLIFF version 2.0
<http://docs.oasis-open.org/xliff/xliff-core/v2.0/cs01/xliff-core-v2.0-cs01.html>
In the instructions below, `-v*` is used to refer to either the v2 or v1.2
versions of each plugin, such as `plugins/xliff-v2` or `plugins/xliff-v1.2`.
Choose the appropriate plugin depending on the XLIFF version supported by your
localization service provider or translation toolchain.
Installing the Plugins
======================
1. Download the latest distribution package for the plugins from:
<http://sourceforge.net/projects/ditaxliff/files/latest/download>.
2. Unzip the package to the `plugins` directory of your DITA-OT installation.
3. From the root directory of your DITA-OT installation, run the start command
for your operating system (either `startcmd.bat` or `startcmd.sh`).
4. In the `startcmd` environment, run the following command to integrate the
new plug-ins into your toolkit installation:
ant -f integrator.xml
Cleaning the Output Folders
===========================
To ensure reliable results, you need to clear out the output directory each time
you run one of the conversions.
On Windows systems, you can do this with the `clean.bat` files that are included
in the plugin distribution. You will need to change the extension back to .bat
to make them work (the .txt extension was added to work around over-zealous
virus checkers).
Take the .txt extensions off the following files:
* `ditafromxliff-v12/out/samples/ditafromxliff12/must-clean4each-round.bat.txt`
* `ditafromxliff-v2/out/samples/ditafromxliff/must-clean4each-round.bat.txt`
* `xliff-v1.2/clean.bat.txt`
* `xliff-v2/clean.bat.txt`
Running the Conversions
=======================
These instructions will provide a starting point. You can use the samples and
just leave everything else as is. Or you can use your own DITA sample projects
and do more robust testing. To do that you will need to edit the integrator and
build files.
DITA to XLIFF sample
--------------------
1. Go to the `plugins/xliff-v*` directory of your DITA-OT installation,
depending on the XLIFF version you want to generate.
2. In the DITA-OT command window, execute: `ant -f integrator.xml`.
(You only need to do this once.)
3. Look at the `sample.ditamap` file in the `samples/guitars` folder.
The sample build file points to this map in the `args.input` property.
4. In the `xliff-v*` directory, execute `ant -f build_dita2xliff.xml`.
5. Go to the `xliff-v*/out/samples/xliff` folder.
Note the `d_x.xml` file. This is a valid XLIFF file that has all your maps,
topics, and required structure to translate and reassemble your DITA
project. Feel free to translate it with your favorite XLIFF editor.
Note: if your CAT tool uses custom extensions, you may need to include its
XML Schema in the XLIFF to DITA step.
6. Change the name of the translated file to `d_x_translated.xml`, and place
it in the `plugins/ditafromxliff-v*/in` directory.
XLIFF to DITA sample
--------------------
1. Go to the `plugins/ditafromxliff-v*/in` directory, depending on the XLIFF
version you generated in the sample above.
2. In the DITA-OT command window, execute: `ant -f integrator.xml`.
(You only need to do this once.)
3. Take a look at the `d_x_translated.xml` file (the same file you translated).
The build file is pointed at this XLIFF file. (Saxon 9 uses the schemas in
this folder to validate the XLIFF file.)
4. In `plugins/ditafromxliff-v*`, execute `ant -f build_ditafromxliff.xml`.
5. Go to the `ditafromxliff-v*/out/samples/ditafromxliff` directory.
Look in the `translated` folder. You will find your translated DITA project.
6. SMALL BUG: If you want to re-run this step, you must first remove the
`deleteme.txt` file (or run the `must-clean4each-round.bat` script).
DITA to XLIFF (your files)
--------------------------
To run the conversions on your own projects, you must edit a few files.
1. RECOMMENDED: Copy the source files for your project to a new subfolder in
the `plugins/xliff-v*/samples` folder (i.e. `xliff-v*/samples/my-project`).
2. Edit the value of the `args.input` property on line 27 of the Ant build
script (`xliff-v*/build_dita2xliff.xml`) to point to your map.
Change the line that looks like this:
<property name="args.input" value="samples/guitars/sample.ditamap"/>
to something like this:
<property name="args.input" value="samples/my-project/my-map.ditamap"/>
3. Then follow the remaining steps as listed above for DITA to XLIFF sample.
XLIFF to DITA (your files)
--------------------------
1. Translate the XLIFF file that was generated by the `xliff-v*` plugin.
2. RECOMMENDED: Change the name of the translated file to `d_x_translated.xml`,
and place it in the `plugins/ditafromxliff-v*/in` directory.
3. Then follow the remaining steps as listed above for XLIFF to DITA sample.
Note: To ensure that Saxon 9 can validate the XLIFF file, make sure the schemas
are available in the `in` folder.
Note: If you want to change the file names or directory structure, you will need
to edit the `integrator.xml` file, and the `build_ditafromxliff.xml` file.
Known Limitations (I'm working on these)
========================================
1. You must delete the output file from the `out` directory each time you want
to run `ditafromxliff`.
2. If your main map links to maps or topics that are not in folders adjacent
to or below the main map, the results will work, but the nesting will be a
little weird. I am working on a scheme that counts the levels of
difference, and builds a deep hierarchy to accommodate.
Dependencies
============
XLIFF 2.0
The 1.8 plugin depends on:
plugins/xliff-v2/integrator.xml plugins/xliff-v2/plugin.xml
plugins/xliff-v2/build_dita2xliff.xml plugins/xliff-v2/xsl/d2x.xsl
plugins/ditafromxliff-v2/integrator.xml plugins/ditafromxliff-v2/plugin.xml
plugins/ditafromxliff-v2/build_ditafromxliff.xml
plugins/ditafromxliff-v2/xsl/x2d.xsl
XLIFF 1.2
The 1.8 plugin depends on:
plugins/xliff-v1.2/integrator.xml plugins/xliff-v1.2/plugin.xml
plugins/xliff-v1.2/build_dita2xliff.xml plugins/xliff-v1.2/xsl/d2x.xsl
plugins/ditafromxliff-v1.2/integrator.xml
plugins/ditafromxliff-v1.2/plugin.xml
plugins/ditafromxliff-v1.2/build_ditafromxliff.xml
plugins/ditafromxliff-v1.2/xsl/x2d.xsl
---
Based on `DITA-XLIFF-RT-4X2-readme.txt`, last modified 2014-04-26 17:52
