WEB Advent 2008 / On Internationalization

Two weeks ago, I was in Buenos Aires for CakeFest. It was an excellent opportunity to connect with the community and discover some of the creative things that people are doing with CakePHP.

I was most impressed by the translators. Because this was a bilingual (English and Spanish) conference, we had a group of translators who provided headsets to those who only spoke one of the two languages. While the speakers were presenting, the translators would simultaneously listen in one language and speak in another. The level of focus required is nothing short of astounding. Additionally, all badges, signage, and handouts were designed and printed in both languages. This was a truly international conference, and everyone benefitted.

Getting Started

Internationalization, whether for an event or a web application, takes effort. But, with a little planning, it's not so bad. Before diving in, let's cover some terminology:

• Internationalization is a property of your application's architecture. Internationalizing an application is the process of stripping out everything that ties that application to a specific language or region of the world, and making those things generic, so they can be translated.
• Localization is the process of translating text and adding region-specific information to an application, so it's usable by people living in the region.
• A locale file is a file that maps keywords or phrases within your application to those of a particular language or regional dialect.
• A locale code is a short sequence of two sets of two letters used for locale mapping. The first two are for the language; the second two are for the locale. For example, en-us for English as spoken in the US, or it-ch for Italian as spoken in Switzerland.

Here are a few of the things to take into consideration when internationalizing a web app:

Text Replacement

At a minimum, all text should be localizable. This means text should be represented as locale strings which can either be shortened strings like no_items or full native text like There are no items on this page. In either case, the text needs to be wrapped in some sort of translation function and needs to correspond to keys in your locale file.

Pluralization

Each language has its own rules for pluralization, and these must be considered when dealing with any text that can be affected by plurality.

Dates, Times, & Currency

In the US, we write $1,000.50 to mean one thousand dollars and fifty cents. In Montréal, this is expressed as $1 000,50 USD.

Character Encoding

In most cases, UTF-8 is sufficient for representing a wide range of languages and locales. However, keep in mind that some languages (Korean and Chinese) use other character encodings by default. A basic understanding of Unicode is recommended.

Keep in mind that it can be difficult to break out of your own cultural and lingustic preconceptions, and don't forget that there is quite literally a world of assistance available. If possible, involve someone with another cultural background, and be sure to consult some in-depth resources.

Doin' the Stuff

In CakePHP, there are several useful tools for localizing your site. One is the __() function. This function can be used to wrap all text. For example, consider a simple header:

<h1>My awesome title</h1>

Using __(), this becomes:

<h1><?php __('My awesome title'); ?></h1>

Alternatively, you might prefer:

<h1><?php __('TITLE'); ?></h1>

If a block of text is partly dynamic, use __n(), which you can combine with sprintf() to translate singular and plural words:

<?php echo sprintf(__n('I have %d MacBook', 'I have %d MacBooks', 2, TRUE), 2); ?>

This generates the following:

I have 2 MacBooks

Once you've wrapped your text appropriately, CakePHP has a console command for generating a translation file. Assuming you have your console configured appropriately, simply type cake i18n extract from the command line, and follow the prompts. You will then have a gettext-compatible translation file, which can be given to your friendly neighborhood translation service or the helpful open source community.

CakePHP also supports translations of database content. For more information, please read our top-to-bottom internationalization tutorial.

That's about all I have to say. So, Fröhliche Weihnachten, Feliz Navidad, and Merry Christmas.