PEAR::Translation2 Tutorials

One recurring topic on many PHP forums is how to deal with the internationalization (i18n) of a website. In particular, an hot question is where to store the translations. Some people like to have them in the database, as it's more convenient to access, others prefer the speed of gettext but are not too enthusiastic about the editing tools, many simply store them in INI files or as PHP arrays. Other people wonder what is the most efficient solution and if they're able to implement it.

PEAR::Translation2 tries to address all these concerns. Now that a stable release is out, let's have a first overview of the package and its features; some tutorials on its usage will follow. If you want to try this package, all you have to do is:

$ pear install Translation2

Translation2 was written with three goals in mind:

  1. ease of use
  2. flexibility
  3. performance

1) Ease of use

The Translation2 API is essential, yet powerful. There are two main methods to retrieve the translated strings:

  • get($stringID, $pageID, $languageID) to get a single translation for a given language;
  • getPage($pageID, $languageID) to get all the translations of a group in a language. NB: a "page" is not necessarily a "web page", it's just a group of strings that are related or belong to the same "section", so it may make sense to group them into a single unit.

You can set a default language with setLang() and a a default page (i.e. the default group of translated strings) with setPageID() so you don't have to pass it as a parameter to each get() or getPage() call.

Along with the base class, there is also an Admin module to manage all the translations in an easy way. Again, the methods are kept to a minimum and are very intuitive:

2) Flexibility

By design, Translation2 has a layered structure: upon the base layer, you can stack one or many decorators to add extra functionality: a fallback language to deal with strings not yet translated in the chosen language, a caching layer (memory-based or file-based), a charset converter, etc...
Adding a decorator is as simple as this:

// $tr is a Translation2 object
// english is the main language
$tr->setLang('en');
 
// add a fallback language layer
$tr =& $tr->getDecorator('Lang');
$tr->setOption('fallbackLang', 'it')
 
// add a memory-based cache layer:
$tr =& $tr->getDecorator('CacheMemory');

Another key feature of Translation2 is having a container abstraction interface, so you can plug different storage containers and access the data in the same way for them all. The official package already provides some database containers (for PEAR DB, MDB and MDB2), one for GetText (using the native extension or a PHP parser), and one XML-based. The API is consistent among all the containers, so the choice is not driven by "how hard it is to set up gettext", but can be made depending on the tools that you might already use, or the confidence you have in a given storage solution.

3) Performance

The last goal of Translation2 is performance. The lightweight and layered design allows a fine-grained choice of what the specific application needs, so if you don't need a feature, you don't have to load it. This holds true for the decorators (you can have none or many of them) and the Admin module. Many translation classes make the mistake to include the administrative tasks in the same unit as the retrieving routines, even if the former are used once every XXX times (where XXX is usually a BIG number) the page is accessed.

Recap

I hope this brief page can shed some light on some of the design decisions behind Translation2, and that it can spark some curiosity in those of you who haven't tried it yet. Next time, we'll see some actual usage examples to get it working.
Bookmark this page, I'll link the tutorials from here.
Stay tuned!




4 responses to "PEAR::Translation2 Tutorials"

There is nothing left to say but a big THANK YOU! Translation2 offers the right solution to find the golden mean of performance and simplicity. It is definitely a good choice if you find gettext too hard to handle and look for a good alternative.
I stored my translations in a database as it is easy to access, however, what I really miss in the other containers is a graphical front end, that allows to modify and manage your translations.

Hello,
I\'m trying to use PEAR Translate2.
I installed everything using the command line, translate2\' folder is in pear and pear is under php,(C:php\\pear\\pear\\translate2)
I entered the path in php.ini.
The projects are under htdocs of apache2.
But unfortunately every time I try to call translate2, I get
Warning: require_once (Traslation2 \\ Translation2.php) [function.require-once]: failed to open stream: No such file or directory in C: \\ Program Files \\ Apache Software Foundation \\ apache2.2 \\ htdocs \\ try.phpon line 3
Fatal error: require_once () [function.require]: Failed opening required \'Traslation2 \\ Translation2.php\' (include_path = \'.; C: \\ php \\ PEAR;; PHP\'s default setting is for include_path.\') In C: \\ Program files \\ Apache Software Foundation \\ apache2.2 \\ htdocs \\ try.php on line 3
in row 3 of try.php trere is \"require_once \'Traslation2 \\ Translation2.php\';\"
suggestions?
thanks in advance

Thanks for the article. What would be really useful is an outline of the default MYSQL tables. I can\'t see this anywhere in the documentation.

Hi,
you can find the db structure in the official documentation:
http://pear.php.net/manual/en/package.internationalization.translation2.intro.php
or have a look at this test case:
http://svn.php.net/viewvc/pear/packages/Translation2/trunk/tests/tests.sql?view=markup
If you use the Translation2_Admin functions, the tables will be created automatically.

Lorenzo Alberton

Lorenzo Alberton Lorenzo PHP5 ZCE - Zend Certified Engineer has been working with large enterprise UK companies for the past years and is now CTO at DataSift. He's an international conference speaker and a long-time contributor to many open source projects. Lorenzo Alberton's profile on LinkedIN View Lorenzo Alberton's Twitter stream

Lorenzo Alberton - Sun Certified MySQL 5 Developer

Tags

AJAX, Apache, Book Review, Charset, Cheat Sheet, Data structures, Database, Firebird SQL, Hadoop, Imagick, INFORMATION_SCHEMA, JavaScript, Kafka, Linux, Message Queues, mod_rewrite, Monitoring, MySQL, NoSQL, Oracle, PDO, PEAR, Performance, PHP, PostgreSQL, Profiling, Scalability, Security, SPL, SQL Server, SQLite, Testing, Tutorial, TYPO3, Windows, Zend Framework

Buy me a book - Joel On Software