PEAR Manual
PrevNext

Introduction

Introduction -- Usage of Translation2

What is Translation2?

Translation2 is a class for multilingual applications management. It provides an easy way to retrieve all the strings for a multilingual site from a data source (i.e. db). The API is designed to be clean, simple to use, yet powerful and extensible. A Translation2_Admin class is provided to easily manage translations (add/remove a language, add/remove a string).

The following containers (data source drivers) are provided:

Some decorator classes will help in various tasks. They can be layered/stacked one on top of the other, in any number. This approach should suit everyone's needs. Currently, the following decorators are provided:

Usage example

This simple example will show how you can instanciate a Translation2 object and use it to retrieve your translated strings from a db, using the MDB2 driver: 
// set the parameters to connect to your db
$dbinfo = array(
    'hostspec' => 'host',
    'database' => 'dbname',
    'phptype'  => 'mysql',
    'username' => 'user',
    'password' => 'pwd'
);

define('TABLE_PREFIX', 'mytable_');

// tell Translation2 about your db-tables structure,
// if it's different from the default one.
// NB: the default db structure is:
//
// Table "langs" (available languages and meta info)
// +----+------+------+----------+------------+
// | ID | name | meta | encoding | error_text |
// +----+------+------+----------+------------+
//
// Table "strings" (translations)
// +----+---------+----+----+----+-----+
// | ID | page_id | en | de | it | ... |
// +----+---------+----+----+----+-----+
// You can have one table per translation, instead
// of one table for all the languages
//
$params = array(
    'langs_avail_table' => TABLE_PREFIX.'langs_avail',
    'lang_id_col'     => 'ID',
    'lang_name_col'   => 'name',
    'lang_meta_col'   => 'meta',
    'lang_errmsg_col' => 'error_text',
    'strings_tables'  => array(
                            'en' => TABLE_PREFIX.'i18n',
                            'it' => TABLE_PREFIX.'i18n',
                            'de' => TABLE_PREFIX.'i18n'
                         ),
    'string_id_col'      => 'ID',
    'string_page_id_col' => 'pageID',
    'string_text_col'    => '%s'  //'%s' will be replaced by the lang code
);

$driver = 'MDB2';

require_once 'Translation2.php';
$tr =& Translation2::factory($driver, $dbinfo, $params);

//always check for errors. In this examples, error checking is omitted
//to make the example concise.
if (PEAR::isError($tr)) {
    //deal with it
}

// set primary language
$tr->setLang('it');

// set the group of strings you want to fetch from
$tr->setPageID('defaultGroup');

// add a Lang decorator to provide a fallback language
$tr =& $tr->getDecorator('Lang');
$tr->setOption('fallbackLang', 'en');

// add another Lang decorator to provide another fallback language,
// in case some strings are not translated in Italian or English
$tr =& $tr->getDecorator('Lang');
$tr->setOption('fallbackLang', 'de');

// fetch the string with the 'test' stringID
echo $tr->get('test');

// fetch a string not translated into Italian (test fallback language)
echo $tr->get('only_english');

// fetch the whole group of strings, without resorting to the fallback lang
// and without any "decoration"
$rawPage = $tr->getRawPage();
print_r($rawPage);

// fetch the whole group of strings, but applying the decorators
$page = $tr->getPage();
print_r($page);

// you can force the lang and the group of the string you're requesting
echo $tr->get('month_01', 'calendar', 'it');

// the same is true for getRawPage() and getPage()
$page = $tr->getPage('calendar', 'de');
print_r($page);

As you can see, the main methods are get(), getPage() and getRawPage(). The full syntax is 
get($stringID, $pageID, $langID);
but if you set the pageID and the langID beforehand, you won't need to specify them at each get() invocation.

NB: you have to check for errors at least on the first invocation of one of these methods, since the db connection is only estabilished at this point, so the chances of failures are higher here.

Extracting language info

Now let's see how we can extract some meta info from the db: 
$tr->getLang();     // no langID => get current lang
$tr->getLang('it'); // same as above, if the current lang is Italian

// the first parameter is the lang code,
// with the second parameter you can filter the info you need
$tr->getLang('it', 'error_text');
$tr->getLang('en', 'name');
$tr->getLang('de', 'meta');
$tr->getLang('de', 'encoding');

Using decorators

Translation2 uses decorators to filter/change the retrieved strings. You can have a chain of decorators (filters), and you can also add yours. 
$tr =& Translation2::factory($driver, $dbinfo, $params);
$tr->setLang('en');
$tr->setPageID('calendar');

// add a memory-based cache decorator, to do some basic prefetching and
// reduce the load on the db
$tr = & $tr->getDecorator('CacheMemory');

// add a file-based cache decorator, to cache the query results through pages
$tr =& $tr->getDecorator('CacheLiteFunction');
$tr->setOption('cacheDir', 'cache/');
$tr->setOption('lifeTime', 3600*24);

// add a fallback lang decorator
$tr = & $tr->getDecorator('Lang');
$tr->setOption('fallbackLang', 'it');

// add a special chars decorator to replace special characters with the html entity
$tr = & $tr->getDecorator('SpecialChars');
// control the charset to use
$tr->setOption('charset', 'ISO-8859-2');

// add a UTF-8 decorator to automatically decode UTF-8 strings
$tr = & $tr->getDecorator('UTF8');

// add a default text decorator to deal with empty strings
$tr = & $tr->getDecorator('DefaultText');
// replace the empty string with its stringID
echo $tr->get('emptyString');
// use a custom fallback text
echo $tr->get('emptyString', 'stringGroup', 'en', 'show this default text');

Getting the stringID from a string

The getStringID() method is the reverse of get(). If you want to translate a string to another language, but you don't know the associated stringID, you can retrieve it with this method: 
$tr->setLang('it');

// translate the Italian string "gennaio" into the English "january"
$stringID = $tr->getStringID('gennaio', 'calendar');
echo $translatedString = $tr->get($stringID, 'calendar', 'en');

Parameter substitution

Translation2 can handle parametric strings, and replace them with parameters passed at runtime (they can be numeric or associative arrays). 
// "hello_user" = "hello &&user&&, today is &&weekday&&, &&day&&th &&month&& &&year&&"

$tr->setParams(array(
    0         => '',
    'user'    => 'Joe',
    'day'     => '15',
    'month'   => $tr->get('month_01', 'calendar', 'en'),
    'year'    => '2004',
    'weekday' => $tr->get('day_5', 'calendar', 'en')
));

echo $tr->get('hello_user');
// the above line will print "hello Joe, today is Friday, 15th January 2004"

PrevHomeNext
Class Summary Translation2UpAdmin Introduction