Tutorial: Automating DITA XML multilingual documentation projects management

DITA XML is a great tool for managing technical documentation. However, multilingual projects require creating a distinct .ditamap (table of contents) file for each language. This can lead to inconsistant multilingual versions. Fortunately, this problem can be solved with an appropriate methodology and a publishing script for the DITA Open Toolkit open-source publishing system.

DITA XML multilingual documentation projects methodology:

  1. The .ditamap file must not include navtitle sections, which contain a hard-coded title instead of extracting the title from the corresponding DITA section, and can therefore not be shared accross distinct language versions.
  2. As soon as you start the DITA project, save content (.dita) files in language-specific directories. For instance :

    └── product
        └── en_US
            ├── images
            ├── tasks
            └── topics

    instead of:

    └── product
        ├── images
        ├── tasks
        └── topics

  3. In the .ditamap file, replace all instances of the language directory by a unique transitional chain of characters, for instance, @language-code@:

    <topicref href="@language-code@/topics/managing-rights.dita"/>

    instead of:

    <topicref href="en_US/topics/managing-rights.dita"/>

  4. To publish target files, you can now:

    • Edit the default.locale value in demo/fo/build.xml
    • Replace the unique transitional chain of characters by the language directory name in the .ditamap file
    • Edit the language parameter (xml:lang) in the .ditamap file and in the DITA content files
    • For PDF target files, edit the page size (US letter or A4, for instance) depending on the target language
    • Publish target files
    • Restore orignal values in source files.
    • Fortunately, this can be easily automated, for instance with the following Bash (Linux) script. This script requires that:

      • You have installed DITA Open Toolkit
      • Your DITA XML project is based on a single .ditamap file
      • The DITA content files extension is .dita
      • The language directory names are the same as language codes supported by Dita Open Toolkit (en_US or fr_FR, for instance)
      • The DITA content files are located in language directories subdirectories (en_US/tasks/ and en_US/topics/, for instance).

      Values currently supported for PDF page sizes are en_US (US letter) and fr_FR (A4).

      This script can of course be easily adapted.

      Disclaimer: This script is provided ‘as-is’, without warranty of any kind. The author makes no express or implied guarantee that this code is free from defects, or fit for a particular purpose. The author will not be held responsible for damages arising from the use of the script. Please make sure backing up all your files before using this script, for instance under a Version Control System. Make sure you can restore all files easily if anything goes wrong.

      To use this script:

      1. Download the multilingual DITA XML publishing script in the directory where the .ditamap project file is located.
      2. Open a terminal, cd to the directory where the .ditamap project file is located, then enter:
        sudo chmod +x dita2target.sh
      3. Enter:
        mkdir out

        to create the target directory, then enter:

        ./dita2target.sh <ditamap file> <language directory name> <target format>

        to publish target files.

        The target format argument accepts values supported by DITA Open Toolkit.

        For instance:

        ./dita2target.sh firewall.ditamap en_US pdf2

        The firewall.pdf file is then published in the out directory.

One thought on “Tutorial: Automating DITA XML multilingual documentation projects management

  1. You may also use an entity:-

    if you add a LanguageCode entity (example below):-

    <!DOCTYPE bookmap PUBLIC "-//OASIS//DTD DITA 1.2 BookMap//EN"
    "bookmap.dtd" []>

Leave a Reply

Your email address will not be published. Required fields are marked *