vcs.maemo.org Git - neverball/blob - doc/translations.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
   2 <html>
   3
   4 <head>
   5     <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
   6     <title>Neverball translation guidelines</title>
   7 </head>
   8
   9 <body>
  10     <h1>Neverball translation guidelines</h1>
  11
  12     <h2>About this document</h2>
  13
  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>
  17
  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>
  21
  22     <h2>General information</h2>
  23
  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>
  29
  30     <h2 id="tools">Tools</h2>
  31
  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>
  36
  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>
  40
  41     <dl>
  42
  43         <dt>Poedit</dt>
  44
  45         <dd>
  46
  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>
  53
  54         </dd>
  55
  56         <dt>KBabel</dt>
  57
  58         <dd>
  59
  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>
  64
  65         </dd>
  66
  67         <dt>gtranslator</dt>
  68
  69         <dd>
  70
  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>
  77
  78         </dd>
  79
  80     </dl>
  81
  82     <h2>Instructions</h2>
  83
  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>
  89
  90     <p>If your language does not yet have a translation, download the
  91     translation template file "neverball.pot".  Then, translate it.</p>
  92
  93     <p>Important remarks:</p>
  94
  95     <ul>
  96
  97         <li>The text encoding must be UTF-8.</li>
  98
  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
 103         forum).</li>
 104
 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
 110         of "yyy".</li>
 111
 112     </ul>
 113
 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>
 117
 118     <h2>(In)Frequently Asked Questions</h2>
 119
 120     <dl>
 121
 122         <dt>What to do with the sentences in French in the source text?</dt>
 123
 124         <dd>
 125
 126         <p>The currently accepted practice is to copy the French text verbatim
 127         (untranslated) and only translate the parts in English.<p>
 128
 129         </dd>
 130
 131         <dt>Why <em>are</em> there sentences in French in the source text?</dt>
 132
 133         <dd>
 134
 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>
 141
 142         </dd>
 143
 144         <dt>How to deal with plural forms?</dt>
 145
 146         <dd>
 147
 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>
 154
 155         <p>PO entries involving plural forms typically look like this (example
 156         taken from the Finnish translation):</p>
 157
 158         <pre>#: ball/st_goal.c:157
 159 #, c-format
 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>
 164
 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>
 168
 169         <pre>"Plural-Forms: nplurals=2; plural=(n != 1);\n"</pre>
 170
 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>
 174
 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>
 177
 178         </dd>
 179
 180     </dl>
 181
 182 </body>
 183 </html>
 184