Edit online

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

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:

  1. Create a com.oxygenxml.webhelp.localization plugin directory inside the DITA-OT-DIR/plugins/ location.
  2. 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>
  3. 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>
  4. Copy the strings you want to change from the translation files to the strings-en-us.xml file. Make sure you leave the name attribute unchanged because this is the key used to look up the string. A sample content might be: 
    <strings xml:lang="en-US">
  <str name="Figure">Fig</str>
  <str name="Draft comment">ADDRESS THIS DRAFT COMMENT</str>
</strings>
  5. In the DITA-OT-DIR/bin directory of the DITA Open Toolkit, run one of the following scripts, depending on your operating system:
Edit online

Adding a New Language

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:

  1. Create a com.oxygenxml.webhelp.localization plugin directory inside the DITA-OT-DIR/plugins/ location.
  2. 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>
  3. 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>
  4. 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.
  5. In the strings-pl-pl.xml file, change the @xml:lang attribute on the root element that conforms with the new language. 
    <strings xml:lang="pl-PL">
  ...
</strings>
  6. Translate the content of each <str> element (make sure to leave the name attribute unchanged). 
    <strings xml:lang="pl-PL">
...
 <str name="webhelp.content" js="true" php="false">Polish translation for 'Content'.</str>
 <str name="webhelp.search" js="true" php="false">Polish translation for 'Search'</str>
...
</strings>
  7. Copy the common DITA-OT strings defined in the DITA-OT-DIR/plugins/org.dita.base/xsl/common/strings-en-us.xml file. It defines a set generated text available for HTML-based transformations (such as <note>, <fig>, and <table> elements). Translate the content of each <str> element. 
    <strings xml:lang="pl-PL">
...
 <str name="webhelp.content" js="true" php="false">Polish translation for 'Content'.</str>
 <str name="webhelp.search" js="true" php="false">Polish translation for 'Search'</str>
...
 <str name="Figure">Polish translation for 'Figure'</str>
 <str name="Table">Polish translation for 'Table'</str>
...
</strings>
  8. In the DITA-OT-DIR/bin directory of the DITA-OT, run one of the following scripts, depending on your operating system: