3.9. Translations in PivotX

For the impatient:

If you need to know more, read on...

Internationalization and localization are terms used to describe the effort to make PivotX (and other such projects) available in languages other than English, for people from different locales, who use different dialects and local preferences.

The process of localizing a program has two steps. The first step is when the program's developers provide a mechanism and method for the eventual translation of the program and its interface to suit local preferences and languages for users worldwide. PivotX developers have done this, so in theory, PivotX can be used in any language.

The second step is the actual localization, the process by which the text on the page and other settings are translated and adapted to another language and culture, using the framework prescribed by the developers of the software. PivotX has already been localized into many languages - see below.

About Locales

A locale is a combination of language and regional dialect. Usually locales correspond to countries, as is the case with Portuguese (Portugal) and Portuguese (Brazil). You can do a translation for any locale you wish, even other English locales such as Canadian English or Australian English, to adjust for regional spelling and idioms. The default locale of PivotX is U.S. English (kind of).

Currently (up until release 2.2), PivotX works with plain languages, not locales. We'll add locales when there is a need for it, i.e., when we get two translations for the same language which are different because they are for different countries.

Localization Technology

PivotX's developers chose to use the GNU gettext localization framework to provide localization infrastructure to PivotX. gettext is a mature, widely used framework for modular translation of software, and is the de facto standard for localization in the open source/free software realm. It should be noted that PivotX isn't using the gettext in the OS (which requires you to enable locales in the OS), but rather an implementation of gettext in PHP.

Gettext uses message-level translation - that is, every 'message' displayed to users is translated individually, whether it be a paragraph or a single word. In PiovtX, such 'messages' are generated, translated, and used by the PivotX PHP files via two PHP functions. __() is used when the message is passed as an argument to another function; _e() is used to write the message directly to the page. In the templates, PivotX uses [[t]]Message to be translated[[/t]]

Currently (as of PivotX 2.2), PivotX doesn't support translations for user contributed extensions.

The gettext framework takes care of most of PivotX. However, there are a few places in the PivotX distribution where gettext cannot be used, for example in JavaScript files, hence the possibility for some English text even if PivotX is 100% translated to your language.

Gettext files

There are three types of files used in the gettext translation framework. These files are used and/or generated by translation tools during the translation process, as follows:

Translation Tools

There are various tools available to aid in translating. You may use whichever you prefer.

PivotX isn't available at Launchpad yet.

Many translators have found Rosetta (Launchpad) to be a good starting point, but once it comes to proofreading the entire list of translations, many have opted to switch hand-editing the PO file or using a program like poEdit or KBabel, since the Rosetta UI lacks a search feature and other things that become essential when proofreading and editing.

Translating With Tools (like poEdit)

  1. Download and install the tool (Poedit).

  2. Download the current PO file for your language or the official PivotX POT file (pivot.pot). If you are translating a new language, copy pivot.pot to xy.po where xy is a two-letter language code that you can find for example by looking in langs/codes/en.php.

  3. Open the file in Poedit, and translate the messages. (Read the Poedit help.)

  4. After saving the translated file, get Poedit to generate the MO file - Poedit can do this automatically for you if you select this in the preferences.

  5. Put the mo file in you langs folder so PivotX can use it (and you can see your translation in action).

  6. Finally, send the updated/completed translation to translations at pivotx.net.

Tips for Good Translations

PivotX Localization Repository

The PivotX Localization Repository is a Subversion repository where the official PivotX translations are maintained.

Currently, the PivotX maintainers commit updates and changes to the repository. Just send your contribution to translations at pivotx.net and we will handle it promptly.

Guidelines and requirements

All localizations should be UTF-8 - as the default POT file indicates.

PHP does not support Byte Order Markers (BOMs), so be sure the UTF-8 encoded files you contribute do not have them.

With a few exceptions, all translations should be written literally, rather than escaping accented and special characters with HTML character entities. Some characters must be escaped to avoid conflict with XHTML markup: angle brackets (< and >), and ampersands (&). In addition, there are a few other characters better used escaped, such as non-breaking spaces ( ), angle quotes (« and »), curly apostrophes (’) and curly quotes.

Translation Status

Visit the translation statistics page. (You can get the latest version of any translation by following the links on that page.) The stats are updated every night.

Disclaimer: This text is heavily based on the similar documentation for Wordpress.