# singapore - Translation

- Introduction
- Requirements
- Updating a translation
- Starting a new translation
- Filling in the header section
- Plural forms
- Useful links
- General readme
- Advanced features
- Developer documentation

## Introduction

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?

Language strings are stored in standard GNU Gettext PO (portable object) files which means you can (at least in theory 1) use all currently available PO editors such as poEdit to make your translations.

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.

It is a good idea for all translators and potential translators to join the development mailing list. Use this, the internationalisation forum and the translations tracker to interact with other translators and developers.

1The 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.

## Requirements

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: http://singapore.sourceforge.net/binaries/singapore-gettext-Win32.zip. The path to xgettext is stored in `tools/extract.php` and the path to msgmerge is stored in `tools/merge.php`. However if the gettext programs are in your PATH or in the `tools/` directory itself then you do not need to edit anything.

## Updating a translation

Each singapore release requires the language files to be updated slightly. First make sure you have the latest available translation (the translations tracker 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 merge script provided.

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.

## Starting a new translation

The very first thing to do is submit a tracker item on the translations tracker 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.

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

- `singapore.pot` - untranslated standard language strings template in PO format
- `singapore.admin.pot` - untranslated admin language strings template in PO format
- `singapore.LANG.po` - translated standard language strings in PO format
- `singapore.admin.LANG.po` - translated admin language strings in PO format
- `singapore.LANG.pmo` - translated standard strings as compiled PHP serialized object
- `singapore.admin.LANG.pmo` - translated admin strings as compiled PHP serialized object

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

Start by copying a PO template file (`singapore.pot` if you are translating the standard strings or `singapore.admin.pot` 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.

You also need to fill in certain parts of the PO file header. You may do this at any stage of the translation.

NOTES:

1. Strings in the form "crumb line|You are here:"
   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.
2. Strings in the form "Showing %s-%s of %s"
   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 `printf()`. Essentially each %s is a placeholder and so needs to be present at the appropriate place in the translated string.
   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 `printf()`. More details on this may be found here: http://www.php.net/sprintf
3. Strings with plurals
   You must correctly specify the Plural-forms header field in order to make use of plural forms. Put each plural in its own `msgstr[x]` where x is a number between 0 (inclusive) and the nplurals number you specified in the header (see examples below).
4. Using a text-editor
   When translating an entry you must leave the English language strings (those on lines starting `msgid`) untouched and insert the translated strings between the double-quotes on the following lines (those starting `msgstr` or `msgstr[x]` in the case of plurals).
5. Obsolete entries
   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 `#~`. There is no need to translate these entries as they are ignored by the compiler.

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 compile script provided in the `tools/` directory of the singapore distribution.

And that's it!

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.

## Examples

The following string

    # File: ../includes/singapore.class.php, line: 247
    #, c-format
    msgid "Page created in %s seconds"
    msgstr ""

when translated into French becomes

    # File: ../includes/singapore.class.php, line: 247
    #, c-format
    msgid "Page created in %s seconds"
    msgstr "Page créée en %s secondes"

and the following string

    # File: ../includes/admin.class.php, line: 173
    msgid "admin bar|Edit image"
    msgstr ""

when translated into Italian becomes

    # File: ../includes/admin.class.php, line: 173
    msgid "admin bar|Edit image"
    msgstr "Modifica l'immagine"

and the following string

    # File: ../includes/singapore.class.php, line: 530
    #, c-format
    msgid "%s gallery"
    msgid_plural "%s galleries"
    msgstr[0] ""

when translated into Spanish becomes

    # 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"

## Filling in the header section

NOTE: This section is mainly copied from the section 5.2 of the GNU Gettext manual.

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

### The following fields must be filled in correctly:

Content-Type
  Replace `ISO-8859-1` with the character encoding used for your language, in your locale, or UTF-8. This field is needed for correct operation of the `msgmerge` program, as well as for users whose locale's character encoding differs from yours.

  The following encodings are frequently used for the corresponding languages.

  - `ISO-8859-1` for Afrikaans, Albanian, Basque, Catalan, Dutch, English, Estonian, Faroese, Finnish, French, Galician, German, Greenlandic, Icelandic, Indonesian, Irish, Italian, Malay, Norwegian, Portuguese, Spanish, Swedish,
  - `ISO-8859-2` for Croatian, Czech, Hungarian, Polish, Romanian, Serbian, Slovak, Slovenian,
  - `ISO-8859-3` for Maltese,
  - `ISO-8859-5` for Macedonian, Serbian,
  - `ISO-8859-6` for Arabic,
  - `ISO-8859-7` for Greek,
  - `ISO-8859-8` for Hebrew,
  - `ISO-8859-9` for Turkish,
  - `ISO-8859-13` for Latvian, Lithuanian,
  - `ISO-8859-15` for Basque, Catalan, Dutch, English, Finnish, French, Galician, German, Irish, Italian, Portuguese, Spanish, Swedish,
  - `KOI8-R` for Russian,
  - `KOI8-U` for Ukrainian,
  - `CP1251` for Bulgarian, Byelorussian,
  - `GB2312`, `GBK`, `GB18030` for simplified writing of Chinese,
  - `BIG5`, `BIG5-HKSCS` for traditional writing of Chinese,
  - `EUC-JP` for Japanese,
  - `EUC-KR` for Korean,
  - `TIS-620` for Thai,
  - `UTF-8` for any language, including those listed above.

  The character encoding name can be written in either upper or lower case. Usually upper case is preferred.

Plural-Forms
  See the plural forms section.

### The following fields should be filled in:

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

### The following fields may be left alone:

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

## Plural forms

NOTE: This section is mainly copied from the section 10.2.5 of the GNU Gettext manual.

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.

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.

Only one form:
  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:

      Plural-Forms: nplurals=1; plural=0;

  Languages with this property include:

  Finno-Ugric family
    Hungarian
  Asian family
    Japanese, Korean
  Turkic/Altaic family
    Turkish
Two forms, singular used for one only
  This is the form used in most existing programs since it is what English is using. A header entry would look like this:

      Plural-Forms: nplurals=2; plural=n==1 ? 0 : 1;

  Languages with this property include:

  Germanic family
    Danish, Dutch, English, German, Norwegian, Swedish
  Finno-Ugric family
    Estonian, Finnish
  Latin/Greek family
    Greek
  Semitic family
    Hebrew
  Romanic family
    Italian, Portuguese, Spanish
  Artificial
    Esperanto
Two forms, singular used for zero and one
  Exceptional case in the language family. The header entry would be:

      Plural-Forms: nplurals=2; plural=n>1;

  Languages with this property include:

  Romanic family
    French, Brazilian Portuguese
Three forms, special case for zero
  The header entry would be:

      Plural-Forms: nplurals=3; plural=n%10==1 && n%100!=11 ? 0 : n != 0 ? 1 : 2;

  Languages with this property include:

  Baltic family
    Latvian
Three forms, special cases for one and two
  The header entry would be:

      Plural-Forms: nplurals=3; plural=n==1 ? 0 : n==2 ? 1 : 2;

  Languages with this property include:

  Celtic
    Gaeilge (Irish)
Three forms, special case for numbers ending in 1[2-9]
  The header entry would look like this:

      Plural-Forms: nplurals=3; plural=n%10==1 && n%100!=11 ? 0 : n%10>=2 && (n%100<10 || n%100>=20) ? 1 : 2;

  Languages with this property include:

  Baltic family
    Lithuanian
Three forms, special cases for numbers ending in 1 and 2, 3, 4, except those ending in 1[1-4]
  The header entry would look like this:

      Plural-Forms: nplurals=3; plural=n%10==1 && n%100!=11 ? 0 : n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2;

  Languages with this property include:

  Slavic family
    Croatian, Czech, Russian, Slovak, Ukrainian
Three forms, special case for one and some numbers ending in 2, 3, or 4
  The header entry would look like this:

      Plural-Forms: nplurals=3; plural=n==1 ? 0 : n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2;

  Languages with this property include:

  Slavic family
    Polish
Four forms, special case for one and all numbers ending in 02, 03, or 04
  The header entry would look like this:

      Plural-Forms: nplurals=4; plural=n%100==1 ? 0 : n%100==2 ? 1 : n%100==3 || n%100==4 ? 2 : 3;

  Languages with this property include:

  Slavic family
    Slovenian

### How the Plural-forms header works:

The `nplurals` value must be a decimal number which specifies how many different plural forms exist for this language. The string following `plural` 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 `n`. 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 `n` in the expression. The resulting value then must be greater or equal to zero and smaller than the value given as the value of `nplurals`.

## Useful links

- singapore i18n forum
- GNU Gettext homepage
- GNU Gettext manual - lots of technical information about the PO format
- poEdit - an open source cross-platform PO editor
- gTranslator - a PO editor for GNOME
- KBabel - a PO editor for KDE

$Date: 2004/11/01 08:17:33 $