Localizing Frameworks

Oxygen XML Author Eclipse plugin 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.

To localize the content of a framework, follow this procedure:

Create a translation.xml file that contains all the translation (key, value) mappings. The translation.xml has the following format:

<translation>
    <languageList>
        <language description="English" lang="en_US"/>
        <language description="German" lang="de_DE"/>
        <language description="French" lang="fr_FR"/>
    </languageList>
    <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>
    </key>  
......................
</translation>

Oxygen XML Author Eclipse plugin 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.

The translation.xml file must be stored in a directory named i18n located in the framework folder. You also need to add a reference to the i18n directory in the Classpath list corresponding to the edited document type.

Note: If you are working with an extension of a framework, you have to add the reference to your directory after (below) the reference to the i18n directory for the base directory:
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 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.
Next, open the translation.xml file and edit the translation entry if it exists or create one if it does not exist. This is an example of 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>
    </key>
```
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:
```
title:before{
    content:"${i18n(title.key)} : ";
}
```
Tip: You can enter any language you want in the <languagelist> tag and any number of keys.

DocBook Example:

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 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.