Table of Contents

  1. Quick Links
  2. Introduction
  3. Sahana Collaborative Translation using Pootle
  4. Other Methods for Creating a Sahana Translation
    1. Creating a PO File With Sahana
    2. Submitting a Local PO File to Pootle
    3. Submitting a Local Non-PO File
  5. Sahana Language Pack
    1. Download
    2. Installation
    3. Hints

SAHANA Translation Guide

Introduction

The original language of the Sahana user interface is English, however, usually it will be necessary to have a localized user interface with all text messages and markings shown in a local language and script. To solve this problem, Sahana uses the  GNU gettext utilities for localization of the user interface.

GNU gettext refers to message catalogues to lookup the actual translation for each message string. So, to have the user interface in a local language and script, you just have to apply the appropriate language version of the message catalogues.

A gettext message catalogue is a binary file (Machine Object, MO file, *.mo), which is generated by msgfmt from a human-readable/editable text file (Portable Object, PO file, *.po). The PO file simply consists of pairs of strings, with each the original (marked by msgid) and the actual translated form (marked by msgstr) of a UI message string.

All message strings of the Sahana user interface are located in one large message catalogue (sahana.po/sahana.mo). The Sahana PO/MO files reside in the res/locale/[ll_CC]/LC_MESSAGES subdirectories of the Sahana installation (with ll_CC representing the ISO codes of the particular language and country, e.g. de_DE for German/Germany).

Sahana Collaborative Translation using Pootle

Since 2008, the Sahana community provides an online facility for web-based collaborative translation of the Sahana user interface into various languages at:

This website is based on Pootle (Portable Object based Online Translation/Localization Engine), a server engine for working on .po-files over the web. The Pootle server manages PO files (=file-based), and it provides an interface for online editing.

To help translating Sahana into your language:

  • Familiarize yourself a little with Sahana e.g., take a look at the  Sahana Website and/or try out the  Sahana Demo
  • Register yourself an account at the  Sahana Pootle Server
  • Join the  Sahana Localization GoogleGroup (you may need to register a Google account first):
    • search the  GoogleGroup for mention of your language
    • read the mails to familiarize yourself with what has been going on in your language
    • post a message briefly introducing yourself (e.g., what experience as translator you have, how familiar you are with Sahana and PO-based localization) and telling that you want to help translate Sahana into your language
  • Ask on the mailing list wether your language already has a maintainer. The language maintainer is basically the chief translator who reviews all suggestions and can give guidance and advice to other translators as necessary.
  • Start translating, follow the PootleGuide (even if you want to work offline)

Other Methods for Creating a Sahana Translation

While the Pootle system is particularly good for collaborative translation, there are other approaches, particular for a customized local translation. Any tool that creates PO files will work. Furthermore, almost any computer-readable list of pairs of "Original String" <-> "Translated String" can be accommodated.

Creating a PO File With Sahana

Even your local Sahana installation itself can create a PO file - just do as follows:

  • Give write permission to your web server to the whole 'res' subdirectory.
  • Make sure the gettext utilities are installed properly.
  • Start Sahana, go to the Admin menu -> Language/Locale -> Interactive Translation.
  • Follow the instructions shown for this function.
  • Extract the PO file in the "Translation" menu.

There are also shell scripts available to extract any desired portion of the Sahana UI strings from the sources and create PO templates (and other list formats) of it - so you can have translation templates for any modified/customized Sahana version (as long as it uses GNU/gettext for localization).

Submitting a Local PO File to Pootle

To submit a PO file to the Pootle site (regardless of how you have translated it), just send it to webmas...@… and comment about its origin. It will then be merged into the Pootle server files, so that you or other translation maintainers can do further review/correction of the translation.

The existing translation at the Pootle site always has a higher priority than translations submitted from elsewhere (reverse merging). So if you wish to correct an existing translation, please use the Pootle site and make your suggestion/overwrite existing translations. If this seems too tricky, contact webmas...@… to have it done for you.

Submitting a Local Non-PO File

Besides normal PO files, submissions of other formats can be handled. Requirements are:

  • the particular translator is registered at the Sahana Localization Group.
  • the translation is provided in computer-readable pairs of "Original String" <-> "Translated String".
  • a Linux desktop system can read the file somehow.

Example formats are any portion/aggregation of PO files, CSV lists, Excel sheets, XML files, and so on.

Sahana Language Pack

The Sahana Language Pack is a collection of precompiled translations (PO/MO files) for Sahana - to be added directly to a running instance.

Download

The language pack is available for download at one of the following locations:

Installation

To install/update the language pack, simply copy and unpack it directly into the res/locale subdirectory of your Sahana installation, e.g.:

Extract the locales list from the package: 

tar xzvf sahana-0.6.2-stable-langpack.tar.gz locales.txt

Install/update all locales from the package: 

tar xzvf sahana-0.6.2-stable-langpack.tar.gz

Install/update only a particular locale: 

tar xzvf sahana-0.6.2-stable-langpack.tar.gz ru_RU

After installation of the files, set up the locales you need using the Sahana Admin interface.

Hints

  • the language pack of the latest stable release of Sahana (actually, 0.6.2-stable) will be updated on a monthly base, so you can try to update to the most recent version if you see gaps or errors in the translation you use
  • it is recommendable to make a backup copy of the res/locale directory before installing new files
  • ensure, that the webserver has writing permissions on the res/locale/locale file
  • ensure, that your server is set up to accept this locale
  • if you experience coding problems with special characters (e.g. ñ), try to append .UTF-8 to the locale directory name (e.g. de_DE.UTF-8 instead of de_DE) and update the file res/locale/locale accordingly
  • it could be necessary to restart Apache once after changing locale settings or files