1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
5 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
6 <title>Neverball translation guidelines</title>
10 <h1>Neverball translation guidelines</h1>
12 <h2>About this document</h2>
14 <p>This document contains information for people who are interested in
15 translating <a href="http://neverball.org/">Neverball</a> (and Neverputt)
16 to their language of choice.</p>
18 <p>If you have any questions after reading this document, do not hesitate
19 to <a href="http://www.nevercorner.net/forum/" title="Neverforum">ask
20 them</a>, so that this document can be further improved.</p>
22 <h2>General information</h2>
24 <p>Neverball is internationalised using the <a
25 href="http://www.gnu.org/software/gettext/">GNU Gettext
26 internationalisation library</a>. In this approach, translators
27 typically work with PO files containing "message identifiers" (source text)
28 and "message strings" (translations of the source text).</p>
30 <h2 id="tools">Tools</h2>
32 <p>It is advisable to use a dedicated PO editing tool instead of editing
33 the files manually. By doing so, you will ensure that files remain in a
34 valid format and encoding, and source text is not accidentally modified,
35 and it will also minimise the time required for translation.</p>
37 <p>Listed below are few of such editing tools. There are also custom modes
38 and plugins available for Vim and Emacs and probably your own favourite
39 extensible text editor.</p>
47 <p><a href="http://www.poedit.net/">Poedit</a> is a multi-platform PO
48 file editor. If you are using Microsoft Windows, Poedit is likely to
49 be your only option. The interface is straight-forward and the editor
50 is easy-to-use. It appears to lack documentation for key bindings,
51 however, and plural forms for your language will have to be entered
52 manually (if needed).<p>
60 <p><a href="http://kbabel.kde.org/">KBabel</a> is an advanced PO
61 editor for KDE. It is so advanced, in fact, that this author gave up
62 trying it out during the initial set-up... Can be overwhelming and may
63 require some time to become familiar with.<p>
71 <p><a href="http://gtranslator.sourceforge.net/">gtranslator</a> is a
72 PO file editor for the GNOME desktop environment. While being one of
73 the easiest-to-use editors from those mentioned here, it unfortunately
74 has a critical bug (up until version 1.1.7 as of this writing) and does
75 not handle certain message identifiers correctly. Therefore it is
76 <strong>not usable with Neverball</strong> at the moment.<p>
84 <p>First, if there is already a translation for your language, contact the
85 current translator (or translation team), as indicated in the respective PO
86 file. A list of current translations is available in the <a
87 href="https://s.snth.net/svn/neverball/trunk/po/">"po"
88 subdirectory of the source code tree</a>.</p>
90 <p>If your language does not yet have a translation, download the
91 translation template file "neverball.pot". Then, translate it.</p>
93 <p>Important remarks:</p>
97 <li>The text encoding must be UTF-8.</li>
99 <li>Never edit the source text. (Using a <a href="#tools">dedicated PO
100 editor</a> can sometimes help resist the temptation.) If you find
101 errors or have any suggestions on how to improve the source text,
102 please contact the developers (preferably by posting a message on the
105 <li>Some strings are "contextualised", in order to allow different
106 translations for identical message identifiers. These strings are in
107 the form of "xxx^yyy", where "xxx" is the context and "yyy" is the
108 string to translate. The translations of such strings must have the
109 context prefix removed and must <em>only</em> contain the translation
114 <p>After completing the translation, send us the translated file. You can
115 open a new thread in the forum and either link the PO file from there or
116 send the file to one of the developers.</p>
118 <h2>(In)Frequently Asked Questions</h2>
122 <dt>What to do with the sentences in French in the source text?</dt>
126 <p>The currently accepted practice is to copy the French text verbatim
127 (untranslated) and only translate the parts in English.<p>
131 <dt>Why <em>are</em> there sentences in French in the source text?</dt>
135 <p>The French text comes from the intro messages of most of Mehdi's
136 levels. What can probably be assumed to be the the first attempts to
137 introduce i18n in Neverball is now seen as a sort of a "trade mark" for
138 Mehdi's levels. In any case, this is an exception, not the norm, and
139 these days mappers are expected to just stick with the "real deal" and
140 use Gettext to do the localisation.</p>
144 <dt>How to deal with plural forms?</dt>
148 <p>A good description of <a
149 href="http://www.gnu.org/software/gettext/manual/html_node/Plural-forms.html">Gettext
150 plural form handling</a> is available in the Gettext documentation.
151 It is somewhat technical in nature, however, it is advisable to read
152 the entire section to gain a good understanding of the concept. Below
153 is a short (but not necessarily easier to understand) summary.</p>
155 <p>PO entries involving plural forms typically look like this (example
156 taken from the Finnish translation):</p>
158 <pre>#: ball/st_goal.c:157
160 msgid "%d new bonus level"
161 msgid_plural "%d new bonus levels"
162 msgstr[0] "%d uusi bonuskenttä"
163 msgstr[1] "%d uutta bonuskenttää"</pre>
165 <p>The number of "msgstr[x]" lines depends on how many plural forms
166 there are in your language. The number of plural forms is in turn
167 specified in the Plural-Forms header at the top of the PO file:</p>
169 <pre>"Plural-Forms: nplurals=2; plural=(n != 1);\n"</pre>
171 <p>Here "nplurals" is the number of plural forms and "plural" is an
172 expression used to determine the plural form of the number "n". (See
173 the Gettext documentation for details and limitations.)</p>
175 <p>Each "msgstr[x]" should contain the translation using the plural
176 form "x" where "x" corresponds to a value of the plural expression.</p>