Localization

DITA-OT supports more than 40 languages. The full list of supported languages (and their codes) is available here: https://www.dita-ot.org/dev/topics/globalization-languages.

There are two ways to switch the labels to a specific language:

Set the @xml:lang attribute on the DITA maps and/or topics root element with one of the supported values (e.g. de, fr-FR, ru, zh-CN).
Set the default.language parameter in the transformation dialog box to the desired language code.

You can create language-dependent CSS rules in your customization CSS by adding rules using the :lang pseudo-class (see https://developer.mozilla.org/en-US/docs/Web/CSS/:lang).

Tip: It is recommended that you do this customization on a DITA-OT distribution deployed outside of the Oxygen installation. Otherwise, you will lose the customization when upgrading Oxygen. You can contact the Oxygen support team to ask for the Oxygen Publishing Engine package.

If the label you want to modify is not available from the CSS, you need to modify the XML strings. The default XML strings are available at the following three locations:

DITA-OT-DIR/plugins/org.dita.base/xsl/common
DITA-OT-DIR/plugins/org.dita.pdf2/cfg/common/vars
DITA-OT-DIR/plugins/com.oxygenxml.pdf.css/resources/localization

How to Customize CSS Strings

Some of the labels come from CSS files located in the DITA-OT-DIR/plugins/com.oxygenxml.pdf.css/css/print/i18n directory. These strings can be overridden directly from a custom CSS stylesheet. Simply identify (by debugging the CSS) and copy the rules that apply on your content and change their values. For example:

*[class ~= "toc/title"][empty]:before {
  content: "Agenda";
}

/* Title of the TOC page */
*[class ~= "toc/title"][empty]:lang(es):before {
  content: "Contenidos";
}

Note: If you want to use a language without a corresponding p-i18n-xx.css stylesheet, follow these instructions:

Copy one of the available stylesheets (located in the DITA-OT-DIR/plugins/com.oxygenxml.pdf.css/css/print/i18n directory) into your CSS customization (other than the English one because it does not have the :lang pseudo-class since it is the default language).
For each rules, replace the :lang(xx) pseudo-class with your expected language code, then replace each property value with the expected label.

How to Modify Existing Strings

To modify the generated text, you need to create a DITA-OT extension plugin that uses the dita.xsl.strings extension point. The following example uses English, but you can adapt it for any language:

In the DITA-OT-DIR\plugins\ folder, create a folder for this plugin (for example, com.oxygenxml.pdf.css.localization).

Create a plugin.xml file (in the folder you created in step 1) that specifies the extension points, your parameter file, and your customization stylesheet. For example:

<plugin id="com.oxygenxml.pdf.css.localization">
  <require plugin="com.oxygenxml.pdf.css"/>

  <feature extension="dita.xsl.strings" file="pdf-extension-strings.xml"/>
</plugin>

Create a pdf-extension-strings.xml file with the following content:

<langlist>
  <lang xml:lang="en"     filename="strings-en-us.xml"/>
  <lang xml:lang="en-us"  filename="strings-en-us.xml"/>
</langlist>

Create an empty strings-en-us.xml file and copy the strings you want to change from the default files into it. Make sure you leave the @id attribute unchanged because this is the key used to look up the string. Then replace their values:
```
<variables>
  <variable id="Figure">Fig</variable>
  <variable id="Table">Array</variable>
</variables>
```
Use the Integrate/Install DITA-OT Plugins transformation scenario found in the DITA Map section in the Configure Transformation Scenario(s) dialog box.
Run the DITA Map PDF - based on HTML5 & CSS transformation scenario.

How to Add New Strings

Some strings are not translated in all languages. In this case, they will appear in English. To add a new language for a given string, you need to create a DITA-OT extension plugin that uses the dita.xsl.strings extension point. The following example uses Polish, but you can adapt it for any language:

In the DITA-OT-DIR\plugins\ folder, create a folder for this plugin (for example, com.oxygenxml.pdf.css.localization).

Create a plugin.xml file (in the folder you created in step 1) that specifies the extension points, your parameter file, and your customization stylesheet. For example:

<plugin id="com.oxygenxml.pdf.css.localization">
  <require plugin="com.oxygenxml.pdf.css"/>

  <feature extension="dita.xsl.strings" file="pdf-extension-strings.xml"/>
</plugin>

Create a pdf-extension-strings.xml file with the following content:

<langlist>
  <lang xml:lang="pl"     filename="strings-pl-pl.xml"/>
  <lang xml:lang="pl-pl"  filename="strings-pl-pl.xml"/>
</langlist>

Copy the PDF strings file (DITA-OT-DIR\plugins\org.dita.pdf2\cfg\common\vars\en.xml) to your plugin directory and rename it as strings-pl-pl.xml.
Copy the common DITA-OT strings defined in the DITA-OT-DIR\plugins\org.dita.base\xsl\common\strings-en-us.xml file into the file created at step 4.

Copy the PDF-CSS-HTML5 strings defined in the DITA-OT-DIR\plugins\com.oxygenxml.pdf.css\resources\localization\strings-en-us.xml file into the file created in step 4. Translate the content of each <variable> element (make sure to leave the @id attribute unchanged).

<variables>
  <variable id="Figure">Polish word for 'Figure'</variable>
  <variable id="Table">Polish word for 'Table'</variable>
  ...
  <variable id="Table of Contents">Polish word for 'Table of Contents'</variable>
  ...
  <variable id="Continued">(ciąg dalszy)</variable>
</variables>

Use the Integrate/Install DITA-OT Plugins transformation scenario found in the DITA Map section in the Configure Transformation Scenario(s) dialog box.
Run the DITA Map PDF - based on HTML5 & CSS transformation scenario.