How to Localize the Interface of WebHelp Responsive Output

Oxygen XML WebHelp Responsive plugin comes with support for the following built-in languages: English, French, German, Japanese, and Chinese. It is possible to edit existing localization strings or add a new language.

Static labels used in the WebHelp output are stored in translation files that have the strings-lang1-lang2.xml name format, where lang1 and lang2 are ISO language codes. For example, the US English labels are kept in the strings-en-us.xml file.

These translation files are collected from two locations:

DITA-OT-DIR/plugins/org.dita.base/xsl/common folder - DITA-OT's default translations (generated text for <note>, <fig>, and <table> elements).
DITA-OT-DIR/plugins/com.oxygenxml.webhelp.responsive/oxygen-webhelp/resources/localization folder - These translations are contributed by the WebHelp plugin and extend the default ones provided by DITA-OT. The labels defined in this folder take precedence over the DITA-OT defaults.

There are two major reasons you may want to use modify the translation files: to modify the existing strings or to translate to a new language.

Edit online

Modifying the Existing Strings

DITA-OT XSLT Extensions

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

Create a com.oxygenxml.webhelp.localization plugin directory inside the DITA-OT-DIR/plugins/ location.

Create a plugin.xml file inside that com.oxygenxml.webhelp.localization directory with the following content:

<plugin id="com.oxygenxml.webhelp.localization">
    <require plugin="com.oxygenxml.webhelp.responsive"/>

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

Create a webhelp-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 translation 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="Draft comment">ADDRESS THIS DRAFT COMMENT</variable>
</variables>
```
In the DITA-OT-DIR/bin directory of the DITA Open Toolkit, run one of the following scripts, depending on your operating system:
- Windows
- Linux/macOS
DITA-OT-DIR/bin/dita.bat --install
sh DITA-OT-DIR/bin/dita --install

Edit online

Adding a New Language

DITA-OT Customization

To add a new language for WebHelp transformations, you need to create a DITA-OT extension plugin that uses the dita.xsl.strings extension point. The following sample procedure is for adding translation files for the Polish language, but you can adapt it for any language:

Create a com.oxygenxml.webhelp.localization plugin directory inside the DITA-OT-DIR/plugins/ location.

Create a plugin.xml file inside that com.oxygenxml.webhelp.localization directory with the following content:

<plugin id="com.oxygenxml.webhelp.localization">
    <require plugin="com.oxygenxml.webhelp.responsive"/>
  
    <feature extension="dita.xsl.strings" file="webhelp-extension-strings.xml"/>
</plugin>

Create a webhelp-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 WebHelp strings file (DITA-OT-DIR/plugins/com.oxygenxml.webhelp.responsive/oxygen-webhelp/resources/localization/strings-en-us.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. It defines a set generated text available for HTML-based transformations (such as <note>, <fig>, and <table> elements). Translate the content of each <variable> element (make sure to leave the @id attribute unchanged).

<variables>
  ...
  <variable id="webhelp.content" js="true" php="false">Polish word for 'Content'.</variable>
  <variable id="webhelp.search" js="true" php="false">Polish word for 'Search'</variable>
  ...
  <variable id="Figure">Polish word for 'Figure'</variable>
  <variable id="Table">Polish word for 'Table'</variable>
  ...
</variables>

In the DITA-OT-DIR/bin directory of the DITA-OT, run one of the following scripts, depending on your operating system:
- Windows
- Linux/macOS
DITA-OT-DIR/bin/dita.bat --install
sh DITA-OT-DIR/bin/dita --install