# Translator Guide

## Introduction

The Openfire admin console can be easily translated into other languages. This document provides instructions for those that wish to make translations.

All text in the Openfire admin console is stored in a resource bundle. A resource bundle is a file containing key/value pairs. Words and phrases are represented using keys. The correct values are retrieved based on locale settings (English values are used for English locales, French values for French locales, etc). Key/value pairs in the English resource bundle might look like the following:

        skin.yes=Yes
        skin.no=No
        skin.topic=Topic
        skin.message=Message

The German resource bundle would contain the same keys, but different values:

        skin.yes=Ja
        skin.no=Nein
        skin.topic=Thema
        skin.message=Beitrag

Making your own translation involves copying the English resource bundle, renaming the file, then translating its contents.

## Construct a Resource Bundle

To start, make a copy of the default (English) locale file "openfire_i18n.properties". It can be found in the `resources\i18n` directory of your Openfire installation. Note: the files found in `resources\i18n` are copies of the real resource bundles used by the application (the real resource bundles are contained in the openfire.jar file). Editing the resource files in the `resources\i18n` directory will not affect your running copy of Openfire.

Next, you'll need to rename the file to match the locale that you're making a translation for. The syntax of the name is "openfire_i18n_[lang]_[country].properties". However, the country code should be used in most cases. For example, the German resource bundle should be named "openfire_i18n_de.properties" because "de" is the language code for German. For French, the file would be called "openfire_i18n_fr.properties". A list of language codes can be found at: http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt. Some locales require a combination of language and country code. For example simplified Chinese would have the name "openfire_i18n_zh_CN.properties" while traditional Chinese would have the name "openfire_i18n_zh_TW.properties".

## Translate the Resource Bundle

Next, use your favorite text editor to translate the English values into your language. The key names must not be changed.

When translating from English, you may need to use special characters for your language (for example, Germans use characters like ä, ü, or ß). Unfortunately, all resource bundle files must be saved in ASCII format which doesn't allow for international characters. We recommend working on your translation in a text editor that supports all characters in your language. After finishing your translation, use the "native2ascii" tool (bundled with Java) to convert international characters to the ASCII format. To use the native2ascii tool:

        native2ascii -encoding XXX my_translation.properties openfire_i18n_YY.properties
                                   ^                         ^
                                   input file                output file

The "-encoding XXX" parameter is optional. If you don't specify it, Java will use the default encoding value, taken from System property "file.encoding". If you do specify an encoding (XXX), it must be taken from the first column of the table of supported encodings in the Supported Encodings document. For example, if you created your translation using UTF-8 as your encoding and you are making a Simplified Chinese translation:

        native2ascii -encoding UTF8 my_translation.properties openfire_i18n_zh_CN.properties

## Testing Your Translation

To test your translation, copy the translated resource bundle file (example, openfire_i18n_de.properties) to the `lib/` directory of your Openfire installation. Make sure Openfire is stopped and then edit the `conf/openfire.xml` file. Set the `locale` property to match your new resource bundle such as "de" or "zh_CN". Start Openfire and the admin console should now be using your translation. If you still see English text you may have named your bundle incorrectly or used the wrong value for the `locale` property.

Once your translation is complete and tested, please submit it to the Openfire developers so that others can enjoy it in the next release!