Localizing Frameworks

Oxygen XML Author supports framework localization (translating framework actions, buttons, and menu entries to various languages). This lets you develop and distribute a framework to users that speak other languages without changing the distributed framework. Changing the language used in Oxygen XML Author in the Global preferences page is enough to set the right language for each framework.

To localize the content of a framework, create a translation.xml file that contains all the translation (key, value) mappings. The translation.xml has the following format:

        <language description="English" lang="en_US"/>
        <language description="German" lang="de_DE"/>
        <language description="French" lang="fr_FR"/>
    <key value="list">
        <comment>List menu item name.</comment>
        <val lang="en_US">List</val>
        <val lang="de_DE">Liste</val>
        <val lang="fr_FR">Liste</val>

Oxygen XML Author matches the GUI language with the language set in the translation.xml file. If this language is not found, the first available language declared in the languagelist tag for the corresponding framework is used.

Add the directory where this file is located to the Classpath list corresponding to the edited document type.

After you create this file, you can use the keys defined in it to customize the name and description of the following:
  • Actions
  • Menu entries
  • Contextual menus
  • Toolbars
  • Static CSS content

For example, if you want to localize the bold action, open the Preferences dialog box (Options > Preferences) and go to Document Type Association. Use the New or Edit button to open the Document type configuration dialog box, go to Author > Actions, and rename the bold action to ${i18n(translation_key)}. Actions with a name format other than ${i18n(translation_key)} are not localized. Translation_key corresponds to the key from the translation.xml file.

Now open the translation.xml file and edit the translation entry if it exists or create one if it does not exist. This example presents an entry in the translation.xml file:

<key value="translation_key">
        <comment>Bold action name.</comment>
        <val lang="en_US">Bold</val>
        <val lang="de_DE">Bold</val>
        <val lang="fr_FR">Bold</val>

To use a description from the translation.xml file in the Java code used by your custom framework, use the new ro.sync.ecss.extensions.api.AuthorAccess.getAuthorResourceBundle() API method to request the associated value for a certain key. This allows all the dialog boxes that you present from your custom operations to have labels translated in multiple languages.

You can also reference a key directly in the CSS content:
    content:"${i18n(title.key)} : ";
Note: You can enter any language you want in the languagelist tag and any number of keys.

The translation.xml file for the DocBook framework is located here:[OXYGEN_INSTALL_DIR]/frameworks/docbook/i18n/translation.xml. In the Classpath list corresponding to the DocBook document type the following entry was added: ${framework}/i18n/.

To see how the DocBook actions are defined to use these keys for their name and description, open the Preferences dialog box (Options > Preferences) and go to Document Type Association > Author > Actions. If you look in the Java class ro.sync.ecss.extensions.docbook.table.SADocbookTableCustomizerDialog available in the oxygen-sample-framework module of the Oxygen SDK Maven archetype, you can see how the new ro.sync.ecss.extensions.api.AuthorResourceBundle API is used to retrieve localized descriptions for various keys.