Before doing that, allow me to make a premise.

Back in the old days, we could copy our site structure as many times as the number of languages we had to work on, go deep into the pages and make necessary changes.

This worked well enough for static content, but had its downsides:

• There were problems updating content
• If you wanted to send the text to a translation service, you had to pull it from the pages yourself
• When the text came back from the translator, you had to work again to insert it into the pages
• There isn't a standard way to format the text and many translation services don't understand HTML, so you had to exchange Word documents and manually convert the text into HTML again to preserve code cleaniness
• There are problems with foreign character sets, you have to translate the HTML entities or convert between encodings
• The first page on your site was nothing more than a list of languages and flags, that meant the first and most important page of all the site has no content
• If you made a guess choosing your first page language, your other languages had to be manually selected by the user to make the switch.
• If you positioned certain elements into the text, you had to insert them manually again when you put the new content.
• There was no way for the translators to make the changes their selves without asking the webmaster, if they had not basic design skills.
• If they claimed such skills, you had to trust them enough to give them access the site source files and have faith in the fact they will not screw up anything.

The list can go on forever. Guess what? Dynamic websites are even worse! The problem is that most of the programmers build up websites pulling data from an archive (text files, a database connection, a service on the Intertubes) and put this materials into template pages. When preparing or upgrading a site to be multilanguage, you had to have a way to pull different data from database for each idiom. Then you have to figure out how to translate the text into the templates.

There are many ways to solve these problems.

You could manually change all the tables to hold the data for all idioms, and prepare a very big array that holds the strings you put into the template, put this big array in different files, one array for each language, and include the files as the user switches language.

This would be only the beginning, because then you should mantain all these arrays in sync. If you wanted to change this data from a control panel you have to put all the strings in a database. Manage language fallbacks (what if a string is not translated in a language?). What about caching? Then you had to write the procedures for querying, inserting and modifying such data.

Meet Translation2, the Pear module that does all of this for us, and much more. After installing it from the repository, we initialize it using this code:

require_once 'Translation2.php';

$tr =& Translation2::factory('mdb2',$db, array(
'langs_avail_table'        => 'translation_langs',
'lang_id_col'            => 'id',
'lang_name_col'            => 'name',
'lang_meta_col'            => 'meta',
'lang_errmsg_col'        => 'error_text',
'lang_encoding_col'        => 'encoding',
'strings_default_table'    => 'translation_strings', 
'string_id_col'            => 'ID', 
'string_page_id_col'    => 'page_id', 
'string_text_col'        => '%s', 
'autoCleanCache'        => true 
) );

Translation2 uses MDB2 as an archive foundation, so you have either to create a MDB2 connection, or reuse an existing one by passing the database object. As I presume you already use a database connection, I'll skip this part. Let's assume the database object is called $db.

Next we pass an array of parameters, specifying the gory details of the tables holding out our translation data. The example depicts two tables, translation_langs (that lists all languages) and translation_strings (that contains all the text).

The table that holds all the languages needs a column for the language id (like for example 'it' or 'en' or 'fr'), name (like 'English', or 'Espanol', 'Italiano',' 'Francais'), meta (extended name, like 'American English', usually matches the name), error text (when the string is not translated, for example 'not available','non disponibile','non traduit') and encoding ('iso-8859-1','utf-8' and so on). You can call these columns and tables as you want, you just need to pass the names into the parameters array.

The strings table instead has an ID column (I put there an MD5 hash of the strings I want to be translated, but any text will do), the page ID column (so you separate and query strings for different pages), the text column for each language ('%s' in the example means the columns are called after the language ID) and any other parameter you wish to use.

To set the language ID and page ID, simply issue these two commands:

$tr->setLang("it");
$tr->setPageID("LOGIN_PAGE");

You then start to initialize the so called 'decorators', additional features of the translation system. The most useful ones are the Cache decorator (that uses the Cache Lite Pear module) and the fallback decorator (to provide fallback strings in other languages).

An initialization sample of the Cache decorator follows:

require_once "Cache/Lite.php"; 
$tr =& $tr->getDecorator 'CacheLiteFunction'); 
$tr->setOption('cacheDir', '/cache/lang/'); 
$tr->setOption('lifeTime', 3600);

with getDecorator you call the decorator. As you see we had to require the cache module file. Then we set the options: the time the system has to cache strings and the directory to use for caching. There are other options, feel free to explore.

The fallback system is even easier:

$tr =& $tr->getDecorator('Lang');
$tr->setOption('fallbackLang', 'en');
$tr->setOption('fallbackLang', 'it');

that means "if you can't find the string in the chosen language, fall back to english. If there isn't an english string, fall back to italian". You can cascade languages as you wish. The function works on a string level, so you can have a complete translated website with only a pair of strings defaulted to another language.

To do queries you use commands like:

$tr->get('PLEASE_LOGIN');

to ask for a translated string,

$tr->getRaw('PLEASE_LOGIN','LOGIN_PAGE');

to ask all translations for a string specifying the Page ID,

$tr->getLangs();

to enumerate all languages, and so on.

You can at this point insert data into the tables yourself, or use the handy administration API that the translation system exposes. Simply initialize it (the parameters array is the same):

$tr_admin = &Translation2_Admin::factory([...continue the same way as the Translation2 constructor...]);

Then you can issue commands like:

$tr_admin ->cleanCache();

to clean the cache

$tr_admin->add("PLEASE_LOGIN', 'LOGIN_PAGE', array("en"=>"Please insert your user name and password in the fields","it"=>"Prego inserire il tuo nome utente e password"));

to insert a new string into the database.

The API enables to easily add, modify and remove languages and strings.

If you want, Translation2 can use as a data source even an XML file or Gettext GNU .po / .mo compiled files. The decorators can also be used to convert between encodings.

That's all, folks!

I hope you liked the article, stay tuned for the next episode of Web localization in PHP: language detection by subscribing to the RSS feed.

I would also be happy to answer to any questions you could have on the Translation2 module. In particular, I've tightly integrated it into a Markdown parser (a PHPBB code like language) and some plugins to provide realtime translations into Smarty templates.

On Windows, instead, there is a layer called Open Database Connectivity (ODBC) that translates the calls from the software to the database, providing a common interface and emulating missing features. Each vendor provides a specific driver, that plugs into the architecture. Via ODBC even a text file or an Excel spreadsheet can be connected and queried like it was a database.

It has been natural to me to start searching the net for a PHP equivalent of that layer. Shortly after starting I found the de facto standard for database abstraction in PHP, called MDB2. Even if it has not the flexibility of a real ODBC layer, it's lack of complexity made it very popular among fellow web programmers at first, just to find out it's ability to grow via extensions and performing in a relatively easy way a set of very powerful and demanding operations.

MDB2 is a Pear library, so you need to follow a procedure to install it. Refer to the Pear website for details.

Just after including the MDB2 scripts into your PHP file

<?

require_once ("MDB2.php");

?>

you need to  create an instance of the database class, like this

<?

$dsn = "your database type://your user name:your password@your server/your database name";

$db = MDB2::factory($dsn);

?>

so you have a connection string that explains how to connect to the database, and an object with multiple methods to perform database operations. You don't need to know other details about the database apart from the ones you put in the Data Source Name (DSN), everything else is handled by the MDB2 object.

After that, you perform vendor agnostic queries like this

$result = $db->queryAll ($sql);

But, as said, the real power behind MDB2 is it's extensions system, for example

$db->loadModule('Extended');

$tablename = "customers";

$data = array("name"=>"Bob","surname"=>"Michael");

$result= $db->extended->autoExecute($tablename,$data, MDB2_AUTOQUERY_INSERT);

I've effectively inserted a new customer into my table without writing a single word of SQL, and without worrying of the actual table structure.

The same applies to interrogation queries, like this

$tablename = "customers";

$where = "`NAME` = 'BOB' AND `SURNAME` = 'MICHAEL'";

$result= $db->extended->autoExecute($tablename,null,
MDB2_AUTOQUERY_SELECT,
$where,null,true,true);

the only SQL here is the where clause, everything else is managed by the library.

You can even store an XML backup of your entire database with a few commands

$db_schema_options = array(
'use_transactions' => true,
'log_line_break' => '<br>',
'idxname_format' => '%s',
'debug' => true,
'quote_identifier' => true,
'force_defaults' => true,
'portability' => true
);

$schema = MDB2_Schema::factory($dsn, $db_schema_options);

$definition = $schema->getDefinitionFromDatabase();

$schema_dump = $schema->dumpDatabase($definition, array(
'output_mode' => 'file',
'output' => $dumpfile
), MDB2_SCHEMA_DUMP_ALL);

where $dumpfile is the file name you want your backup to go to.

The notion of schemas enables your application to seamless update the database across updates. The MDB2 can made automatic modifications of your table definitions to match the ones into the schema.

The library enables to use complex database functions, like transactions, to make your web applications secure and overcome stability problems when delicate procedures are performed, like the cart checkout on a e-commerce website, a money transfer, or any other situation where a power outage or a software interruption can lead to an partial update. Transactions group the operations so that any error will lead to a rollback, preserving the state your data was prior to updating.

If later in the process you want to change your database, for example from MySQL to Microsoft SQL server? Simply change your DSN from mysql to mssql and you are ready!

Did you like this article? Subscribe to my transactional feeds and leave a comment!