Overview

The iSymphony server contains an internationalization framework that allows creating new language packs for languages and regions. This document outlines the process of setting up a custom language pack for the server.

Default Language Files

The default language files are located in the i18n directory in the base installation directory. For a standard installation that is /opt/isymphony3/server/i18n. Inside the .zip archive you will find two directories: com.xmlnamespace.panel.client.i18n.en-us for the iSymphony Client and com.xmlnamespace.panel.admin.i18n.en-us for the iSymphony Admin. Each directory will contain one or more files. The files consist of key value pairs separated by an equals sign, with the key on the left and the value on the right. The value is the part that needs to be translated.

Example

Default:

com_xmlnamespace_panel_client_module_dashboard_widget_type_CoreWidgetTypeProvider_UsersDescriptionLabel=Display the status of other users in the system.

Translated to Dutch:

com_xmlnamespace_panel_client_module_dashboard_widget_type_CoreWidgetTypeProvider_UsersDescriptionLabel=De status van iedere andere gebruiker tonen

New Language Files

Using the default language files translate all of the values in the files to create the new language file. The new file needs to be named as follows:

File Naming Convention

.*messages_[a-zA-Z]{2}-(?:[a-zA-Z]{2})?.properties.

Which reads as:

Any string followed by messages_ followed by two alpha characters followed by - followed by two optional alpha characters followed by .properties.

Ex. client-messages_en-us.properties

Ex. client-messages_fr.properties

iSymphony uses ISO 639-1 for language codes and ISO 3166-1 for region codes in the I18N system. These standards use two characters for the language code and two characters for the region code. For example, the default English language pack has a code of en-us. Using the ISO system is optional for custom language packs, however, if the locale does not match what the browser reports then you will need to manually specify the locale in the URL to use the language.

Restricted Names

There are two restricted language/country combinations that will throw errors if used:

No language and no locale: client-messges.properties

The en-us locale: client-messages_en-us.properties

These are both reserved for the default language pack.

The translated key value pairs may be placed into a single file or into a multiple files. Any file that has the same language and region code will be loaded into the same language pack. Using the same key multiple times in the same language pack will result in indeterministic behavior (the last key/value to load will be used). If a region is not specified then the language pack will use only the language code.

To load the new language pack into iSymphony:

Place the client files in the client servlet i18n folder: /opt/isymphony3/server/conf/client/i18n/

Place the admin files in the admin servlet i18n folder: /opt/isymphony3/server/conf/administrator/i18n/

The server will need to be restarted to load the new language files.

Using Language Pack

When accessing iSymphony the browser's provided locale will be used to select the language pack to load. If a matching language pack is not found then the default language pack will be used. To load a specific language pack you can add the following to the iSymphony URL: "?restartApplication&locale=en_us". The restartApplication parameter will cause the browser to reinitialize the session and will result in the new parameter being used. The locale parameter specifies the language code followed by the country code. The language code and country code should match the language and country code used on the translated files for the language pack.