For the impatient:
-
Get the latest version of the (compiled) translation for your language on the translation download page.
-
Check the status for all translations on the translation statistics page.
-
Submit your improved translation to translations at pivotx.net.
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.
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.
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:
-
POT (Portable Object Template) files
The first step in the localization process is that a program is used to search through the PivotX source code and pick out every message passed into a __() or _e() function. This list of English-language messages is put into a specially formatted template file (POT file) that forms the basis of all translations. Generally, you can download a POT file for PivotX so you shouldn't have to generate your own. -
PO (Portable Object) files
The second step in the localization process is that the translator translates all the messages from the POT file into the target language, and saves both English and translated messages in a PO file. -
MO (Machine Object) files
The final step in the localization process is that the PO file is run through a program that turns it into an optimized machine-readable binary file (MO file). Compiling the translations to machine code makes the localized program much faster in retrieving the translations while it is running.
There are various tools available to aid in translating. You may use whichever you prefer.
-
Virtaal, Poedit
Open source programs for Windows, Mac OS X and UNIX/Linux which provides an easy-to-use GUI for editing PO files and generate MO files. -
KBabel, gtranslator
Other open source PO editing programs for the different window managers on Linux. -
GNU Gettext
The official Gettext tools package contains command-line tools for creating POTs, manipulating POs, and generating MOs. For those comfortable with a command shell. -
Launchpad
The Ubuntu Linux project has a web site that allows you to translate messages without even looking at a PO or POT file, and export directly to a MO.
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.
-
Download and install the tool (Poedit).
-
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.
-
Open the file in Poedit, and translate the messages. (Read the Poedit help.)
-
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.
-
Put the mo file in you langs folder so PivotX can use it (and you can see your translation in action).
-
Finally, send the updated/completed translation to translations at pivotx.net.
-
Don't translate literally, translate organically
Being bi- or multi-lingual, you undoubtedly know that the languages you speak have different structures, rhythms, tones, and inflections. Translated messages don't need to be structured the same way as the English ones: take the ideas that are presented and come up with a message that expresses the same thing in a natural way for the target language. It's the difference between creating an equal message and an equivalent message: don't replicate, replace. Even with more structural items in messages, you have creative license to adapt and change if you feel it will be more logical for, or better adapted to, your target audience. -
Try to keep the same level of formality (or informality)
Each message has a different level of formality or informality. Exactly what level of formality or informality to use for each message in your target language is something you'll have to figure out on your own (or with your team), but PiovtX messages (informational messages in particular) tend to have a politely informal tone in English. Try to accomplish the equivalent in the target language, within your cultural context. -
Don't use slang or audience-specific terms
Some amount of terminology is to be expected in a blog, but refrain from using colloquialisms that only the 'in' crowd will get. If the uninitiated blogger were to install PivotX in your language, would they know what the term means? Words like pingback, trackback, and feed are exceptions to this rule; they're terminology that are typically difficult to translate and that many translators choose to leave in English. -
Read other software's localizations in your language
If you get stuck or need direction, try reading through the translations of other popular software tools to get a feel for what terms are commonly used, how formality is addressed, etc. Of course, PivotX has its own tone and feel, so keep that in mind when you're reading other localizations, but feel free to dig up UI terms and the like to maintain consistency with other software in your language.
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.
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.
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.