TimeTrex Message Internationalization(i18n) README

by Open Source Consulting, S.A.


= OVERVIEW =

TimeTrex contains english strings embedded throughout the PHP code and
smarty templates.  The GNU Gettext suite of tools has been chosen to aid 
with the tasks of:

 - marking and extracting english strings from the source files
 - translating english strings into other languages
 - displaying the foreign language translations of the strings
 - merging in new english strings from the source files
 - merging in new translations from the translators
 

It is a very good idea for anyone working in this area to read up more 
about gettext here:

http://www.gnu.org/software/gettext/

Below, we will explain more about how gettext is integrated with TimeTrex, 
how to properly code strings for translation, and how the translation 
maintenance tools work.
 

= TTi18n Class =

TimeTrex now includes a class for handling all i18n related matters.
Methods related to message translation include:

  - chooseBestLocale()  -- determines which locale to use for messages.
  
  - gettext() -- returns a translated version of given input string.
  

This class works basically like the standard setlocale(), 
bindtextdomain(), gettext() combination but it allows us to abstract the 
implementation a bit.  For example, we may use PEAR's Translation2 class 
to parse the gettext files, instead of using PHP's native gettext() 
function.

For this reason, it is important that all translation calls in the system 
go through TTi18n::gettext() instead of calling gettext() directly.
  

= Smarty Template Files =

We are using a slightly modified version of the gettext plugin for smarty.  
This plugin allows us to mark strings for translation with the following 
syntax:

 {t}Here is some text that needs to be translated.{/t}
 
The only modification to this plugin is that we call TTi18n::gettext() 
(when defined) instead of gettext().


= PHP Source Code Files =

Any strings within the source code that...
  
  a) contain words and 
  b) are intended for an end-user to see 
  
  ...must be embedded within a call to TTi18n::gettext( "my string" ).


There are two reasons for this:

  1) gettext() must be called in order to perform the translation at 
     runtime.  This should be obvious.
     
  2) The string extractor looks for "gettext( ... )" to know which strings 
     to extract.  Therefore, the following code is to be avoided:
     
        $myvar = 'Please enter a value below';
        $myvar = TTi18n::gettext( $myvar );
        
     While the above would do the right thing at runtime, the extractor 
     would not know that this string represents english, so the above 
     string would probably never get translated. Instead, this should be 
     coded as:
     
        $myvar = TTi18n::gettext('Please enter a value below');
        
Be careful to ensure that gettext() is only called once on a given string.
Calling multiple times will probably not cause display problems, but each 
call adds some performance overhead.


= The locale directories and messages.po files =

The locale directory exists at

 timetrex/interface/locale
 
This directory contains:
 - the messages.pot master string dictionary with all english strings.
 - a sub-directory for each locale, eg es_ES for spanish/Spain.
 - the locale_stats.txt file which contains statistics about translations. 

Each locale sub-directory contains another sub-directory LC_MESSAGES which 
in turn contains messages.po and (possibly) messages.mo.  messages.po will 
contain the translations for that particular locale.  messages.mo is a 
compiled form of the .po file that is necessary for GNU gettext to 
function -- however, it is not always required when using the Translation2 
library.

*** IMPORTANT ***

In the interest of avoiding possible encoding headaches, we are 
standardizing on the use UTF-8 encoded messages.po files.  That is, all 
messages.po should be saved as UTF-8 before they are placed/updated into 
the tree.

Why? It has been observed that the Translation2 library does not properly 
convert encodings. While it may be possible to work around this, UTF-8 makes 
things simple all around.


= The Translation helper tools =

These files live in tools/i18n.  ( Though they could be anywhere. )

Each of these should be run from the directory in which it is saved.

mklocales.php
 This script creates and initializes the locale directories beneath the 
 interface/locale directory.  Edit the script and re-run to add a new 
 locale directory and associated messages.po file.

gen_master_pot.sh
 This file generates a master messages.pot file in the interface/locale 
 directory.  This file is then used as the source when merging to 
 individual locales.
 
mergelocale.sh
 This script merges new strings from messages.pot master file into a 
 messages.po file for a single locale.  It also generates the binary
 messages.mo file. Typically, this script is only called by mergelocales.sh
 
mergelocales.php
 This script merges new strings from message.pot master file into the 
 messages.po files for all existings locale directories, creates the 
 binary messages.mo files, and updates the translation stats.

calc_l10n_stats.php 
 This script calculates the percentage of the application that has been 
 translated for each available locale.  It writes out a csv file that can
 be read by a PHP script to display the stats on a web page.

notify_translator.php
 This file notifies the translator by e-mail when new source 
 strings are available for TimeTrex.  Be careful not to run this by 
 accident, as you may end up spamming people unnecessarily.

tsmarty2c.php
 This script is part of the smarty gettext plugin, and is used to extract 
 the strings that can be translated from the smarty templates.  This 
 script is called by the gen_master_pot.sh script.

updatetranslation.sh
 This script is used to merge a single messages.po file 
 provided by a translator with the corresponding messages.po files within 
 TimeTrex.


= Using the translation helper tools on a daily basis =

These are the typical events that happen during application development:

  1) New strings get added into the PHP source or smarty templates.
  
  2) A translator sent in new translations.
  
  3) We need to add a new locale (language) for translation.
  

Let's look at them individually:

1) New strings get added into the PHP source or smarty templates.

In this case, we need to a) update the master .pot file, b) merge 
those changes into the indvidual messages.po files, c) generate the binary 
messages.mo files and d) update the locale stats. It is as simple as:

   $ ./gen_master_pot.sh
   $ ./mergelocales.php

   
2) A translator sent in new translations.

Here, we just need to merge the translator's changes into a single 
messages.po file for a single locale.  Then we want to update the binary 
message.mo file and the locale stats.  Let's suppose we have just received 
spanish translations ( es_ES ) and have saved them in /tmp/messages.po.

   $ ./update_translation.sh es_ES /tmp/messages.po
   $ ./calc_l10n_stats.php


3) We need to add a new locale (language) for translation.

Let's suppose we have found an Italian translator, and now we want to add 
an it_IT locale.  All we do is:

   $ vi mklocales.php           # Now uncomment the line with // 'it_IT'.
   $ ./mklocales.php
   
We could also make all the known locales by uncommenting all the locale 
lines in this script, and then re-running it.