# Neverball translation guidelines

## About this document

This document contains information for people who are interested in translating Neverball (and Neverputt) to their language of choice.

If you have any questions after reading this document, do not hesitate to ask them, so that this document can be further improved.

## General information

Neverball is internationalised using the GNU Gettext internationalisation library. In this approach, translators typically work with PO files containing "message identifiers" (source text) and "message strings" (translations of the source text).

## Tools

It is advisable to use a dedicated PO editing tool instead of editing the files manually. By doing so, you will ensure that files remain in a valid format and encoding, and source text is not accidentally modified, and it will also minimise the time required for translation.

Listed below are few of such editing tools. There are also custom modes and plugins available for Vim and Emacs and probably your own favourite extensible text editor.

Poedit

  Poedit is a multi-platform PO file editor. If you are using Microsoft Windows, Poedit is likely to be your only option. The interface is straight-forward and the editor is easy-to-use. It appears to lack documentation for key bindings, however, and plural forms for your language will have to be entered manually (if needed).

KBabel

  KBabel is an advanced PO editor for KDE. It is so advanced, in fact, that this author gave up trying it out during the initial set-up... Can be overwhelming and may require some time to become familiar with.

gtranslator

  gtranslator is a PO file editor for the GNOME desktop environment. While being one of the easiest-to-use editors from those mentioned here, it unfortunately has a critical bug (up until version 1.1.7 as of this writing) and does not handle certain message identifiers correctly. Therefore it is not usable with Neverball at the moment.

## Instructions

First, if there is already a translation for your language, contact the current translator (or translation team), as indicated in the respective PO file. A list of current translations is available in the "po" subdirectory of the source code tree.

If your language does not yet have a translation, download the translation template file "neverball.pot". Then, translate it.

Important remarks:

- The text encoding must be UTF-8.
- Never edit the source text. (Using a dedicated PO editor can sometimes help resist the temptation.) If you find errors or have any suggestions on how to improve the source text, please contact the developers (preferably by posting a message on the forum).
- Some strings are "contextualised", in order to allow different translations for identical message identifiers. These strings are in the form of "xxx^yyy", where "xxx" is the context and "yyy" is the string to translate. The translations of such strings must have the context prefix removed and must only contain the translation of "yyy".

After completing the translation, send us the translated file. You can open a new thread in the forum and either link the PO file from there or send the file to one of the developers.

## (In)Frequently Asked Questions

What to do with the sentences in French in the source text?

  The currently accepted practice is to copy the French text verbatim (untranslated) and only translate the parts in English.

Why are there sentences in French in the source text?

  The French text comes from the intro messages of most of Mehdi's levels. What can probably be assumed to be the the first attempts to introduce i18n in Neverball is now seen as a sort of a "trade mark" for Mehdi's levels. In any case, this is an exception, not the norm, and these days mappers are expected to just stick with the "real deal" and use Gettext to do the localisation.

How to deal with plural forms?

  A good description of Gettext plural form handling is available in the Gettext documentation. It is somewhat technical in nature, however, it is advisable to read the entire section to gain a good understanding of the concept. Below is a short (but not necessarily easier to understand) summary.

  PO entries involving plural forms typically look like this (example taken from the Finnish translation):

      #: ball/st_goal.c:157
      #, c-format
      msgid "%d new bonus level"
      msgid_plural "%d new bonus levels"
      msgstr[0] "%d uusi bonuskenttä"
      msgstr[1] "%d uutta bonuskenttää"

  The number of "msgstr[x]" lines depends on how many plural forms there are in your language. The number of plural forms is in turn specified in the Plural-Forms header at the top of the PO file:

      "Plural-Forms: nplurals=2; plural=(n != 1);\n"

  Here "nplurals" is the number of plural forms and "plural" is an expression used to determine the plural form of the number "n". (See the Gettext documentation for details and limitations.)

  Each "msgstr[x]" should contain the translation using the plural form "x" where "x" corresponds to a value of the plural expression.