translator-guide.html 5.07 KB
Newer Older
Matt Tucker's avatar
Matt Tucker committed
1 2 3 4
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">

<html>
<head>
5
<title>Openfire: Translator Guide</title>
6
<link href="style.css" rel="stylesheet" type="text/css">
Matt Tucker's avatar
Matt Tucker committed
7 8 9
</head>
<body>

10
<div id="pageContainer">
Matt Tucker's avatar
Matt Tucker committed
11 12 13

<a name="top"></a>

14 15 16 17 18 19 20 21 22 23 24
	<div id="pageHeader">
		<div id="logo"></div>
		<h1>Translator Guide</h1>
	</div>
	<div class="navigation">
		<a href="index.html">&laquo; Back to documentation index</a>
	</div>
	
	<div id="pageBody">


Matt Tucker's avatar
Matt Tucker committed
25 26 27
<h2>Introduction</h2>

<p>
28
The Openfire admin console can be easily translated into other languages. This document
Matt Tucker's avatar
Matt Tucker committed
29 30 31
provides instructions for those that wish to make translations.
</p>
<p>
32
All text in the Openfire admin console is stored in a resource
Matt Tucker's avatar
Matt Tucker committed
33 34 35
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).
Matt Tucker's avatar
Matt Tucker committed
36 37 38 39 40 41 42 43 44 45 46
Key/value pairs in the English resource bundle might look like the following:
<pre>
    skin.yes=Yes
    skin.no=No
    skin.topic=Topic
    skin.message=Message
</pre>

The German resource bundle would contain the same keys, but different values:
<br>
<pre>
47

Matt Tucker's avatar
Matt Tucker committed
48 49 50 51 52 53 54 55 56 57 58
    skin.yes=<i>Ja</i>
    skin.no=<i>Nein</i>
    skin.topic=<i>Thema</i>
    skin.message=<i>Beitrag</i>
</pre>

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

<h2>Construct a Resource Bundle</h2>

59 60
<p>To start, make a copy of the default (English) locale file "openfire_i18n.properties".
It can be found in the <tt>resources\i18n</tt> directory of your Openfire
Matt Tucker's avatar
Matt Tucker committed
61 62
installation. Note: the files found in <tt>resources\i18n</tt> are copies of the
real resource bundles used by the application (the real resource bundles are contained
63 64
in the openfire.jar file). Editing the resource files in the <tt>resources\i18n</tt>
directory will not affect your running copy of Openfire.</p>
Matt Tucker's avatar
Matt Tucker committed
65

Matt Tucker's avatar
Matt Tucker committed
66
<p>Next, you'll need to rename the file to match the locale that you're making a
67
translation for. The syntax of the name is "openfire_i18n_[lang]_[country].properties".
Matt Tucker's avatar
Matt Tucker committed
68
However, the country code should be used in most cases. For example, the German resource
69
bundle should be named "openfire_i18n_de.properties" because
Matt Tucker's avatar
Matt Tucker committed
70
"de" is the language code for German. For French, the file would be called
71
"openfire_i18n_fr.properties". A list of language codes can
Matt Tucker's avatar
Matt Tucker committed
72 73 74 75
be found at:
<a href="http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt"
 target="_new">http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt</a>.
 Some locales require a combination of language and country code. For example
76 77
 simplified Chinese would have the name "openfire_i18n_zh_CN.properties"
 while traditional Chinese would have the name "openfire_i18n_zh_TW.properties".</p>
Matt Tucker's avatar
Matt Tucker committed
78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93

<h2>Translate the Resource Bundle</h2>

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

<p>When translating from English, you may need to use special characters
for your language (for example, Germans use characters like &auml;,
&uuml;, or &szlig;). 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:</p>

<pre>
94
    native2ascii -encoding XXX my_translation.properties openfire_i18n_YY.properties
Matt Tucker's avatar
Matt Tucker committed
95 96 97 98 99 100 101 102 103 104 105 106 107
                               ^                         ^
                               input file                output file
</pre>

<p>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
<a href="http://java.sun.com/j2se/1.3/docs/guide/intl/encoding.doc.html" target="_new">Supported Encodings</a>
document. For example, if you created your translation using UTF-8 as your encoding and
you are making a Simplified Chinese translation:</p>

<pre>
108
    native2ascii -encoding UTF8 my_translation.properties openfire_i18n_zh_CN.properties
Matt Tucker's avatar
Matt Tucker committed
109 110 111 112 113
 </pre>

<h2>Testing Your Translation</h2>

<p>To test your translation, copy the translated resource bundle file (example,
114 115
openfire_i18n_de.properties) to the <tt>lib/</tt> directory of your Openfire
installation. Make sure Openfire is stopped and then edit the <tt>conf/openfire.xml</tt>
Matt Tucker's avatar
Matt Tucker committed
116
file. Set the <tt>locale</tt> property to match your new resource
117
bundle such as "de" or "zh_CN". Start Openfire and the admin console
Matt Tucker's avatar
Matt Tucker committed
118
should now be using your translation.  If you still see English text you may have
Matt Tucker's avatar
Matt Tucker committed
119
named your bundle incorrectly or used the wrong value for the <tt>locale</tt>
Matt Tucker's avatar
Matt Tucker committed
120 121
property.</p>

122
<p>Once your translation is complete and tested, please submit it to the Openfire
Matt Tucker's avatar
Matt Tucker committed
123
developers so that others can enjoy it in the next release!</p>
Matt Tucker's avatar
Matt Tucker committed
124

125 126 127 128 129 130
<br>
<br>

	</div>

</div>
Matt Tucker's avatar
Matt Tucker committed
131 132 133

</body>
</html>