<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>singapore - Translation</title>
<link rel="stylesheet" type="text/css" href="docstyle.css" />
</head>

<body>

<h1>singapore - Translation</h1>

<ul>
  <li><a href="#intro">Introduction</a></li>
  <li><a href="#requirements">Requirements</a></li>
  <li><a href="#update">Updating a translation</a></li>
  <li><a href="#new">Starting a new translation</a></li>
  <li><a href="#header">Filling in the header section</a></li>
  <li><a href="#plurals">Plural forms</a></li>
  <li><a href="#links">Useful links</a></li>
  <li><a href="Readme.html">General readme</a></li>
  <li><a href="Advanced.html">Advanced features</a></li>
  <li><a href="Development.html">Developer documentation</a></li>
</ul>


<h2><a name="intro">Introduction</a></h2>

<p>Thank you for taking an interest in open source development!
Translating singapore is a matter of editing a single file and 
then running a script on it. What could be simpler?</p>

<p>Language strings are stored in standard GNU Gettext PO (portable object) 
files which means you can (at least in theory <a href="#foot1" name="note1"><sup>1</sup></a>) 
use all currently available PO editors such as 
<a href="http://poedit.sourceforge.net/">poEdit</a> to make your 
translations.</p>

<p>For added convenience strings for each language are split into two sections:
one for normal gallery operation and another for strings that are only used in
admin mode. This means that admin strings are not needlessly loaded for every
page and also that translators have the choice of only translating the standard 
strings or going the whole way and translating the admin strings too.</p>

<p>It is a good idea for all translators and potential translators to join the 
<a href="http://lists.sourceforge.net/lists/listinfo/singapore-devel">development 
mailing list</a>. Use this, the 
<a href="http://singapore.sourceforge.net/forum/viewforum.php?f=6">internationalisation forum</a>
and the 
<a href="http://sourceforge.net/tracker/?atid=611769&group_id=77687">translations tracker</a>
to interact with other translators and developers.</p>

<p class="boxed"><a href="#note1" name="foot1">1</a>The reason for the "in theory" 
is that many PO editors do not support the plural forms that singapore makes use 
of - even though they are defined and supported by GNU Gettext. poEdit does 
support plural forms since v1.3 and is highly recommended. Alternatively it is 
just as easy to use a standard text editor to make your translations.</p>

<h2><a name="requirements">Requirements</a></h2>

<p>No further software is required for using the multilanguage capabilities of 
singapore. However the extract and merge tools use xgettext and msgmerge 
respectively. Both these programs are part of GNU Gettext which is already 
installed on most Linux distributions. A package of the relevant gettext 
binaries for Windows is available here: 
<a href="http://singapore.sourceforge.net/binaries/singapore-gettext-Win32.zip">http://singapore.sourceforge.net/binaries/singapore-gettext-Win32.zip</a>.
The path to xgettext is stored in <code>tools/extract.php</code> and the path to 
msgmerge is stored in <code>tools/merge.php</code>. However if the gettext programs 
are in your PATH or in the <code>tools/</code> directory itself then you do not 
need to edit anything.</p>


<h2><a name="update">Updating a translation</a></h2>

<p>Each singapore release requires the language files to be updated slightly. 
First make sure you have the latest available translation (the 
<a href="http://sourceforge.net/tracker/?atid=611769&group_id=77687">translations tracker</a>
is a good place to check for this). Now you need to merge in the new untranslated 
strings and remove the obsolete ones (this may have already been done 
but there's no harm in doing it again). Place the old PO file in the locale 
directory of an installation of the latest version of singapore and use the 
<a href="../tools/merge.php">merge</a> script provided.</p>

<p>Now proceed translating the strings as described below. Finally, attach the 
updated PO file to the appropriate tracker item making sure to state which 
version of singapore it is for.</p>


<h2><a name="new">Starting a new translation</a></h2>

<p>The very first thing to do is submit a tracker item on the 
<a href="http://sourceforge.net/tracker/?atid=611769&group_id=77687">translations tracker</a>
to inform people of your intentions so that two or more people do not needlessly 
spend time translating the same files for the same language. Once you have 
completed your translations you can attach the files to the tracker item.</p>

<p>All language files are kept in a single directory (<code>locale/</code> by
default). They are named as follows:</p>

<ul>
  <li><code>singapore.pot</code> - 
  untranslated standard language strings template in PO format</li>
  <li><code>singapore.admin.pot</code> - 
  untranslated admin language strings template in PO format</li>
  <li><code>singapore.<em>LANG</em>.po</code> - 
  translated standard language strings in PO format</li>
  <li><code>singapore.admin.<em>LANG</em>.po</code> - 
  translated admin language strings in PO format</li>
  <li><code>singapore.<em>LANG</em>.pmo</code> - 
  translated standard strings as compiled PHP serialized object</li>
  <li><code>singapore.admin.<em>LANG</em>.pmo</code> - 
  translated admin strings as compiled PHP serialized object</li>
</ul>

<p>where <code><em>LANG</em></code> represents the ISO639 language code of the chosen 
language (e.g. <code>de</code> for German, <code>en</code> for English, 
<code>en-gb</code> for English (United Kingdom)). A more comprehensive list of 
language codes may be found here: 
<a href="http://www.rickbull.co.uk/tutorials/HTML/Useful%20Information/language_codes.php">http://www.rickbull.co.uk/tutorials/HTML/Useful%20Information/language_codes.php</a></p>

<p>Start by copying a PO template file (<code>singapore.pot</code> if you
are translating the standard strings or <code>singapore.admin.pot</code> if you 
are translating the admin strings) and naming it appropriately for your language 
as described above. Now open the file in your chosen PO editor or a plain text 
editor and set about translating the strings.</p>

<p>You also need to fill in certain parts of the <a href="#header">PO file 
header</a>. You may do this at any stage of the translation.</p>

<p>NOTES:</p>

<ol>
  <li>Strings in the form "crumb line|You are here:"<br />
  In these cases the text up to and including the vertical bar, |, should NOT 
  be included in the translation. They are simply hints for the translator.</li>
  
  <li>Strings in the form "Showing %s-%s of %s"<br />
  In these cases each %s will be replaced at runtime by a number or string in 
  order from left to right according to the rules of <code>printf()</code>.
  Essentially each %s is a placeholder and so needs to be present at the 
  appropriate place in the translated string.<br />
  However some languages may require the order of the arguments to be changed. 
  For example if instead of "Showing 1-10 of 15" you want to say 
  "Out of 15 objects 1-10 are shown" then you must use the argument swapping 
  syntax of <code>printf()</code>. More details on this may be found here: 
  <a href="http://www.php.net/sprintf">http://www.php.net/sprintf</a></li>
  
  <li>Strings with plurals<br />
  You must correctly specify the <a href="#plurals">Plural-forms</a> header field
  in order to make use of plural forms. Put each plural in its own 
  <code>msgstr[<em>x</em>]</code> where x is a number between 0 (inclusive) and 
  the nplurals number you specified in the header (see examples below).</li>

  <li>Using a text-editor<br />
  When translating an entry you must leave the English language strings 
  (those on lines starting <code>msgid</code>) untouched and insert the 
  translated strings between the double-quotes on the following lines (those 
  starting <code>msgstr</code> or <code>msgstr[<em>x</em>]</code> in the case of
  plurals).</li>
  
  <li>Obsolete entries<br />
  When updating a PO file, obsolete entries (i.e. those strings which appeared 
  in the previous version but do not in the current version) are placed at the 
  end of the PO file and prepended by <code>#~</code>. There is no need to 
  translate these entries as they are ignored by the compiler.</li>
</ol>

<p>Once you have translated all the strings and filled in the header, you need 
to compile the PO file into a PHP serialized object file for use with
singapore. Do this using the <a href="../tools/compile.php">compile</a> script 
provided in the <code>tools/</code> directory of the singapore distribution.</p>

<p>And that's it!</p>

<p>Now go and attach your translated PO file(s) to the tracker item you created 
before starting the translation so that everyone else can make use of it.</p>

<h2>Examples</h2>

<p>The following string
<pre class="boxed">
# File: ../includes/singapore.class.php, line: 247
#, c-format
msgid "Page created in %s seconds"
msgstr ""
</pre>
when translated into French becomes
<pre class="boxed">
# File: ../includes/singapore.class.php, line: 247
#, c-format
msgid "Page created in %s seconds"
msgstr "Page créée en %s secondes"
</pre>

and the following string
<pre class="boxed">
# File: ../includes/admin.class.php, line: 173
msgid "admin bar|Edit image"
msgstr ""
</pre>
when translated into Italian becomes
<pre class="boxed">
# File: ../includes/admin.class.php, line: 173
msgid "admin bar|Edit image"
msgstr "Modifica l'immagine"
</pre>

and the following string
<pre class="boxed">
# File: ../includes/singapore.class.php, line: 530
#, c-format
msgid "%s gallery"
msgid_plural "%s galleries"
msgstr[0] ""
</pre>
when translated into Spanish becomes
<pre class="boxed">
# File: ../includes/singapore.class.php, line: 530
#, c-format
msgid "%s gallery"
msgid_plural "%s galleries"
msgstr[0] "%s galería"
msgstr[1] "%s galerías"
</pre>

</p>

<h2><a name="header">Filling in the header section</a></h2>

<p class="note">NOTE: This section is mainly copied from the 
<a href="http://www.gnu.org/manual/gettext/html_chapter/gettext_5.html#SEC35">section 5.2</a> 
of the GNU Gettext manual.</p>

<p>The initial comments "SOME DESCRIPTIVE TITLE", "YEAR" and
"FIRST AUTHOR &lt;EMAIL@ADDRESS&gt;, YEAR" ought to be replaced by
sensible information.</p>

<h3>The following fields must be filled in correctly:</h3>

<dl>
<dt>Content-Type</dt>
  <dd>Replace <samp>ISO-8859-1</samp> with the
  character encoding used for your language, in your locale, or
  UTF-8. This field is needed for correct operation of the
  <code>msgmerge</code> program, as well
  as for users whose locale's character encoding differs from yours. 
  
  
  <p>The following encodings are frequently used for the corresponding
  languages.</p>
  
  <ul>
    <li><code>ISO-8859-1</code> for Afrikaans, Albanian, Basque,
    Catalan, Dutch, English, Estonian, Faroese, Finnish, French,
    Galician, German, Greenlandic, Icelandic, Indonesian, Irish,
    Italian, Malay, Norwegian, Portuguese, Spanish, Swedish,</li>
    
    <li><code>ISO-8859-2</code> for Croatian, Czech, Hungarian,
    Polish, Romanian, Serbian, Slovak, Slovenian,</li>
    
    <li><code>ISO-8859-3</code> for Maltese,</li>
    
    <li><code>ISO-8859-5</code> for Macedonian, Serbian,</li>
    
    <li><code>ISO-8859-6</code> for Arabic,</li>
    
    <li><code>ISO-8859-7</code> for Greek,</li>
    
    <li><code>ISO-8859-8</code> for Hebrew,</li>
    
    <li><code>ISO-8859-9</code> for Turkish,</li>
    
    <li><code>ISO-8859-13</code> for Latvian, Lithuanian,</li>
    
    <li><code>ISO-8859-15</code> for Basque, Catalan, Dutch, English,
    Finnish, French, Galician, German, Irish, Italian, Portuguese,
    Spanish, Swedish,</li>
    
    <li><code>KOI8-R</code> for Russian,</li>
    
    <li><code>KOI8-U</code> for Ukrainian,</li>
    
    <li><code>CP1251</code> for Bulgarian, Byelorussian,</li>
    
    <li><code>GB2312</code>, <code>GBK</code>, <code>GB18030</code>
    for simplified writing of Chinese,</li>
    
    <li><code>BIG5</code>, <code>BIG5-HKSCS</code> for traditional
    writing of Chinese,</li>
    
    <li><code>EUC-JP</code> for Japanese,</li>
    
    <li><code>EUC-KR</code> for Korean,</li>
    
    <li><code>TIS-620</code> for Thai,</li>
    
    <li><code>UTF-8</code> for any language, including those listed
    above.</li>
  </ul>
  
  <p>The character encoding name can be written in either upper or
  lower case. Usually upper case is preferred.</p>
  </dd>
  
  <dt>Plural-Forms</dt>
  <dd>See the <a href="#plurals">plural forms</a> section.</dd>

</dl>

<h3>The following fields should be filled in:</h3>

<dl>
  <dt>Project-Id-Version</dt>
  <dd>This is the name and version of the package.</dd>
  
  <dt>Last-Translator</dt>
  <dd>Fill in your name and email address (without double
  quotes).</dd>
  
  <dt>Language-Team</dt>
  <dd>Fill in the English name of the language followed by the native name
  of the language in brackets. E.g. <i>"Language-Team: German (Deutsch)\n"</i><br />
  Note this is different from the GNU specification but is required in order 
  for the language flipper function to work.
  </dd>
</dl>

<h3>The following fields may be left alone:</h3>

<dl>
  <dt>POT-Creation-Date</dt>
  <dd>This has already been filled in by <code>xgettext</code>.</dd>
  
  <dt>PO-Revision-Date</dt>
  <dd>You don't need to fill this in. It should be filled by the editor when 
  you save the file.</dd>
  
  <dt>Content-Transfer-Encoding</dt>
  <dd>Set this to <code>8bit</code>.</dd>
</dl>

<h2><a name="plurals">Plural forms</a></h2>

<p class="note">NOTE: This section is mainly copied from the 
<a href="http://www.gnu.org/manual/gettext/html_chapter/gettext_10.html#SEC150">section 10.2.5</a> 
of the GNU Gettext manual.</p>


<p>The Plural-forms field in the PO header is used to calculate which plural 
form of a word to use. In English there are only two plural forms but other 
languages have only one or as many as four.</p>

<p>Please check the list below to see if your language is listed. If it is 
then use the corresponding string. If not then you can either write it yourself 
(details below and in the gettext manual) or email a member of the team 
describing how your langauge works (e.g. (not real) 0 car, 1-2 cars, 3 caren, 5+ carii)
and we will write one for you.

<dl>
  <dt>Only one form:</dt>
  <dd>Some languages only require one single form. There is no
  distinction between the singular and plural form. An appropriate
  header entry would look like this: 
  <pre>Plural-Forms: nplurals=1; plural=0;</pre>
  <p>Languages with this property include:</p>
  
  <dl>
    <dt>Finno-Ugric family</dt>
    <dd>Hungarian</dd>
    
    <dt>Asian family</dt>
    <dd>Japanese, Korean</dd>
    
    <dt>Turkic/Altaic family</dt>
    <dd>Turkish</dd>
  </dl>
  </dd>
  
  <dt>Two forms, singular used for one only</dt>
  <dd>This is the form used in most existing programs since it is
  what English is using. A header entry would look like this: 
  <pre>Plural-Forms: nplurals=2; plural=n==1 ? 0 : 1;</pre>
  
  <p>Languages with this property include:</p>
  <dl>
    <dt>Germanic family</dt>
    <dd>Danish, Dutch, English, German, Norwegian, Swedish</dd>
    
    <dt>Finno-Ugric family</dt>
    <dd>Estonian, Finnish</dd>
    
    <dt>Latin/Greek family</dt>
    <dd>Greek</dd>
    
    <dt>Semitic family</dt>
    <dd>Hebrew</dd>
    
    <dt>Romanic family</dt>
    <dd>Italian, Portuguese, Spanish</dd>
    
    <dt>Artificial</dt>
    <dd>Esperanto</dd>
  </dl>
  </dd>
  
  <dt>Two forms, singular used for zero and one</dt>
  <dd>Exceptional case in the language family. The header entry would be: 
  <pre>Plural-Forms: nplurals=2; plural=n&gt;1;</pre>
  
  <p>Languages with this property include:</p>
  
  <dl>
    <dt>Romanic family</dt>
    <dd>French, Brazilian Portuguese</dd>
  </dl>
  </dd>
  
  <dt>Three forms, special case for zero</dt>
  <dd>The header entry would be: 
  <pre>Plural-Forms: nplurals=3; plural=n%10==1 &amp;&amp; n%100!=11 ? 0 : n != 0 ? 1 : 2;</pre>
  
  <p>Languages with this property include:</p>
  
  <dl>
    <dt>Baltic family</dt>
    <dd>Latvian</dd>
  </dl>
  </dd>
  
  <dt>Three forms, special cases for one and two</dt>
  <dd>The header entry would be: 
  <pre>Plural-Forms: nplurals=3; plural=n==1 ? 0 : n==2 ? 1 : 2;</pre>
  
  <p>Languages with this property include:</p>
  
  <dl>
    <dt>Celtic</dt>
    <dd>Gaeilge (Irish)</dd>
  </dl>
  </dd>
  
  <dt>Three forms, special case for numbers ending in 1[2-9]</dt>
  <dd>The header entry would look like this: 
  <pre>Plural-Forms: nplurals=3; plural=n%10==1 &amp;&amp; n%100!=11 ? 0 : n%10&gt;=2 &amp;&amp; (n%100&lt;10 || n%100&gt;=20) ? 1 : 2;</pre>
  
  <p>Languages with this property include:</p>
  
  <dl>
    <dt>Baltic family</dt>
    <dd>Lithuanian</dd>
  </dl>
  </dd>
  
  <dt>Three forms, special cases for numbers ending in 1 and 2, 3,
  4, except those ending in 1[1-4]</dt>
  
  <dd>The header entry would look like this: 
  <pre>Plural-Forms: nplurals=3; plural=n%10==1 &amp;&amp; n%100!=11 ? 0 : n%10&gt;=2 &amp;&amp; n%10&lt;=4 &amp;&amp; (n%100&lt;10 || n%100&gt;=20) ? 1 : 2;</pre>
  <p>Languages with this property include:</p>
  
  <dl>
    <dt>Slavic family</dt>
    <dd>Croatian, Czech, Russian, Slovak, Ukrainian</dd>
  </dl>
  </dd>
  
  <dt>Three forms, special case for one and some numbers ending in
  2, 3, or 4</dt>
  
  <dd>The header entry would look like this: 
  <pre>Plural-Forms: nplurals=3; plural=n==1 ? 0 : n%10&gt;=2 &amp;&amp; n%10&lt;=4 &amp;&amp; (n%100&lt;10 || n%100&gt;=20) ? 1 : 2;</pre>
  <p>Languages with this property include:</p>
  
  <dl>
    <dt>Slavic family</dt>
    <dd>Polish</dd>
  </dl>
  </dd>
  
  <dt>Four forms, special case for one and all numbers ending in
  02, 03, or 04</dt>
  
  <dd>The header entry would look like this: 
  <pre>Plural-Forms: nplurals=4; plural=n%100==1 ? 0 : n%100==2 ? 1 : n%100==3 || n%100==4 ? 2 : 3;</pre>
  <p>Languages with this property include:</p>
  
  <dl>
    <dt>Slavic family</dt>
    <dd>Slovenian</dd>
  </dl>
  </dd>
</dl>

<h3>How the Plural-forms header works:</h3>

<p>The <code>nplurals</code> value must be a decimal number which
specifies how many different plural forms exist for this
language. The string following <code>plural</code> is an
expression which is using the C language syntax. Exceptions are
that no negative numbers are allowed, numbers must be decimal,
and the only variable allowed is <code>n</code>. This expression
will be evaluated whenever one of the plural functions is called. 
The numeric value passed to
these functions is then substituted for all uses of the variable
<code>n</code> in the expression. The resulting value then must
be greater or equal to zero and smaller than the value given as
the value of <code>nplurals</code>.</p>

<h2><a name="links">Useful links</a></h2>

<ul>
  <li><a href="http://singapore.sourceforge.net/forum/viewforum.php?f=6">singapore i18n forum</a></li>
  <li><a href="http://www.gnu.org/software/gettext/">GNU Gettext homepage</a></li>
  <li><a href="http://www.gnu.org/manual/gettext/">GNU Gettext manual</a> - lots 
    of technical information about the PO format</li>
  <li><a href="http://poedit.sourceforge.net/">poEdit</a> - an open source cross-platform PO editor</li>
  <li><a href="http://www.gtranslator.org/">gTranslator</a> - a PO editor for GNOME</li>
  <li><a href="http://i18n.kde.org/tools/kbabel/">KBabel</a> - a PO editor for KDE</li>
</ul>


<p><em>$Date: 2004/11/01 08:17:33 $</em></p>

</body>
</html>