Componentising a site

The typical structure for localising markup is to split a page into multiple templates and components. Typically these reusable templates are derived from the structure of your website, but essentially, any repeating patterns of markup should have it’s own template (be it a component or a partial).

The idea is that we have one place that defines how a particular design element is rendered.

Inheritance structure

An important feature of an effectively internationalised site is the ability to override specific templates or components for localisation-specific requirements. This is either to customise the markup of a particular component, or not displaying that component, or displaying something not available to any other locale.

In it’s most basic form what you want is a templating system that, when a template is required, instead of looking for it in one specific place, it looks in a series of locations (based on the requested locale) until the most appropriate one is found, and then uses that. The most appropriate template is in the range of one specialised just for that locale right up to the generic default that applies to all locales.

Essentially in a well internationalised site there’s a generic set of components that are applicable to most locales most of the time. Then there is a locale specific overrides that either customise the component, stop it from rendering, or insert something not offered in the generic set. In this way each locale can override any template at any point.

Template inheritance gotchas

One very common mistake in inheritance is to use a site’s primary locale as the default level of localisation. Yahoo US made this mistake time and time again. Mainly because they built the US version of each media property first (because the US is Yahoo’s primary market). When they tried to create a Canadian version of Yahoo Finance (in English only: ca.finance.yahoo.com), for example, instead of refactoring the code to have a generic localisation level and both the US version and the Canadian version would specialise from that, they decided to keep the US version at the top of this tree, and the Canadian version became a descendent of that.

This created a serious maintenance headache. Since the size of the Canadian audience was miniscule in comparison to the US audience, there was no dedicated development team for it. Of course, with a proper internationalisation framework in place this isn’t a problem. But because Canada inherited the US codebase, every change to the US codebase became immediately available to Canada. Including features that could contractually only be offered in the US. That means for every change to the US codebase, some poor sap needed to undo that change for Canada by finding the previous version of the changed template, and localising it down to Canada, thus undoing the US change. This do/undo process wasted a large number of developer hours.

They realised the minefield of this approach, and instead of refactoring the Finance property to have a generic, rather than a US as a default localisation, they copied the templates for Canada into a separate codebase, and had a dedicated team in Canada to support their own offshoot.

Luckily, Yahoo in Europe had a tiny fraction of resources the US had access to, and in that scarcity they adopted a much better approach by building their own bespoke templating system, and having a generic localisation level at the top. That allowed Yahoo Europe to support 5 countries, and a dozen independent media sites, with one small team of developers maintaining the templates. (Which worked well for close on a decade; until Yahoo US decided that global properties / one codebase with everything inheriting from the US locale was the preferred solution.)

Specialisation on steroids: Yahoo Europe

At Yahoo! Europe we had a very powerful in-house template editing system (developed in the 20th century) that allowed us to build a generic Yahoo media site. Then we had the ability to specialise^[1] these templates to various dimensions:

• A site dimension: so a Sports site could customise a particular component just for Sport, without affecting the other media sites
• A country dimension^[2]: We could specialise to each of the five European countries we supported (independent or dependent on the site dimension)
• A site section dimension
• A content-type dimension
• A content data-provider dimension
• A page-specific dimension
• A template specific dimension

Although from the perspective of the page every template had a localisation path which looked like a list of paths to look for a specific template, starting from the most-specific (the template-specific level), and going up the list until it found an existing component.

The actual inheritance structure was a lot more complicated, and frankly ingenious. Proper localisation is a set of dimensions. And each dimension inter-relates independently of the others, which makes using a localisation tree impractical and limiting. Dimensions are the factors that can affect how a component displays. As I’ve mentioned, at Yahoo, the actual site itself is one major dimension (A Sports site, as opposed to a News site), then we have dimensions for the country, the data provider, the site section, the type of page, the type of data, and even the individual template itself. New dimensions could be added fairly simply: when we needed to co-brand a section of the site for a particular advertiser/partner we would introduce that as a new dimension and specialise any templates needing customisation to that level. Then when the advertising campaign was over we’d just remove the dimension from the specialism path.

Finding the right level of specialism

Picking the right specialism level is not entirely straightforward, it needs to be considered. It’s far too easy to specialise a template right to the bottom so that you ensure that there’s no impact elsewhere on the site. This approach isn’t ideal and in the long-term it proves to be more costly, despite being the simplest and safest way to implement one change.

It takes knowledge of the available dimensions, what they are used for and where to accurately identify the appropriate level of specialism for a change. You need confidence in making the change at a higher level won’t break parts of the site you are not immediately looking at. That means understanding the implications of your change, and being in a good position to identify and test the affected areas of the site.

Focusing just on the primary locale of the site is only viable when developers are very confident of the scope and impact of their changes. Developers do need to consider the localisation implications of their changes. It’s not enough to get it working in your preferred locale and just assume everywhere else will be just fine. You need to know the impact, either before you make the change, or by confirming it as so by testing it thoroughly.

One of the weaknesses of templating systems of a dynamic and flexible nature is quickly identifying which pages are affected by changing a template. Sometimes a grep isn’t going to be enough, if the template inclusion is something other than a static reference. A developer needs good tools that know about the templating framework and help identify affected pages.

Open-source templating frameworks

Although my experience in internationalisation-supporting frameworks is based on an internal Yahoo templating framework called Jake, it isn’t entirely Yahoo specific. Jake is written in Perl. When Yahoo adopted PHP as it’s framework of choice a team quickly got involved in creating a very flexible dimension-supporting templating system called r3. This got released as open source a few years ago. It’s very powerful, but it really needs someone who understands r3 to write us a guide in how to use r3 and wield it properly.

In the meantime, start with a templating system that allows you to define a generic default localisation for your website, and a specialisation level for each locale where every template can be specialised to for locale-specific customisation. This is the bare minimum for localisation of website templates. Though, if you build it right and allow independent dimensions, you have a very powerful and flexible templating system that will do amazing things.

Footnotes

[1] At Yahoo we referred to the specialism path as the localisation path, although this path wasn’t strictly about localisation but also covered many mutually-exclusive dimensions. Within the European webdev team we understood when we were talking about localisation of templates, and when we were talking about localisation in an internationalisation context. But it was evident that using localisation for templates in this instance can be confusing, so instead calling this specific feature “specialism” and “specialising templates” would make the difference clearer. I’m adopting this nomenclature here.

[2] The choice of country as the primary specialism level of localisation is a classic mistake of internationalisation: a locale or culture doesn’t necessarily map to a country. Yahoo’s Spanish News site contains stories in multiple languages, including Spanish, Catalan, Basque etc. But there’s only one Spanish news site. Instead of a country locale, Yahoo should have established a locale level – Spain-Spanish, Spain-Catalan, Spain-Basque, so three separate locales, not one country with articles in three different languages. The specialism for language is definitely needed, plus another extra level in case there’s a geographic/natural/cultural boundary between groups of people in the same country and language, but still are independent of each other. Yahoo’s insistence on countries defining locales is what limits their ability to accommodate citizens who do not use what Yahoo defines as that country’s acceptable language.

Related resources:

• Easy localisation and templating with Yahoo r3
• Integrating Yahoo r3 with Phing

Mostly this requires developers and engineers of platforms to be aware of the internationalisation implications of their implementation choices. What may seem like an engineering best practice could very well be a massive barrier for localising sites to various countries.

Two major internationalisation steps

The common explanation of the work required is covered by two basic proclamations:

• Everything must be in UTF-8
• Static text strings must be replaced by translation references

Yes, UTF-8 is essential to working in many countries, especially in Asian markets and non-Western European countries. Even today, new systems freshly built are failing on this essential step.

Being able to specify translations for text strings is essential for any site that needs more than one language. But does this even cover 80% of the work required to internationalise a site?

Head-first internationalisation

In my 9 month stint making a “global-ready” Finance codebase barely functional in Europe I encountered a number of internationalisation issues that should have already been dealt with, but hadn’t.

From the outset, it seemed fairly straight-forward. Take the new quotes system code, which runs both the US Finance site and the Canadian Finance site, and launch it in Europe. So the UTF-8 work is already done, and I just needed to extract the text strings and replace them with translation lookups.

It took 3 months to get one page live in one non-English country. We lost a number of features on the way, and the end result is sub-par in a number of respects, including regulatory requirements. Not a resounding success, and a tough learning curve of how internationalisation can hurt when it isn’t considered properly in building global-ready platforms.

Complex translations

Translating static text sentences and phrases is bog standard. However, sometimes we need this static text to contain variable information (for example the text string You are on page 1 of 5). It would be madness to force a translation of every single combination of page number and total number of pages, so we use token replacement to solve this tiny problem.

Be careful when using token replacement using more than one token. Don’t use the order of the tokens as a means of matching from one to the other. For instance, a simple example of sprintf: sprintf("Welcome, %s of %s", $title, $land); what happens when in one cultural locale the $land needs to appear before $title? Rather use name replacements. If your chosen programming language doesn’t allow named token replacements, then it would be wise to change your programming language to one that can.

Sometimes developers and engineers get too clever and create business logic that creates a sentence by adding one word at a time depending on a plethora of business logic. This becomes unlocalisable as grammar constructs vary across languages. I call this the dynamic sentence creation anti-pattern, and show a safer method of accomplishing this.

Other forms of token replacement

Formatting currencies is an interesting variant of token replacement. The location of the currency symbol is either before or after the currency amount. But some currencies have tokens in the middle, too.

Plural forms also catch people out. In some languages zero is singular, in others it is a plural. Even making words plural (plural form) isn’t a case of checking whether it’s just one or more than one. Polish for example has at least five different orders until it settles down to a regular pattern. Some frameworks get this right, symfony for example.

Then comes ordinality indicators (1st, 2nd, 3rd …); the English pattern is fairly regular, but in Czech it requires a bit of thought to algorithmically calculate the right indicator.

Formatting numbers

This is one of those obvious matters. Numbers should be formatted using the preferred cultural approaches, using the appropriate separators. Piece of cake. Run all numbers through a locale-aware formatter, and you’re done.

A translation string for the thousands separator, and one for the decimal point character. Except, if you are using a translation system that strips leading spaces out of text (because of sloppy XML imports), then you run into a nasty problem that the French thousands separator becomes an empty string. You need to be able to trust your translation system.

In Financial reporting there’s lots of data and lots of long numbers, so to squeeze as much information as possible onto the page we need to shortern long numbers, like Apple’s Market Cap of $209,380,000,000,000 is shorterned to $209.38B in the US. Which just about fits into the space available.

But, for France, this is a little more tricky for two reasons:

• There isn’t a short form of Billions in France. The closest is ‘Md’ which means thousand million.
• The French Finance industry prefer a space between the number and it’s suffix.

So to display Apple’s Market Cap in France we would print it as $209,38 Md. Again, if you’re translation system likes trimming off leading spaces, the French translation string for the shortened form of Billions is then incorrect.

Calculations

Numbers are numbers. Until they are formatted for your chosen locale. Then they are just strings. Adding up strings does one of three things:

• Addition is overloaded and the strings are concatenated together. So 1 + 1 equals 11.
• The strings, not being clean numbers are evaluated to the first character, and the rest of it is dropped. so 3,500 + 4,500 equals 7.
• The strings, not being clean numbers are evaluated to zero, so 3,500 + 4,500 equals 0.

None of these do what you expect. Why would anyone want to do this? One feature on a finance portfolio is to track the value of your own share portfolio. So as you add a new share to your portfolio and add in the number of shares you own; that is multiplied by the current share price and added to the other share evaluations to give you a portfolio value.

Then periodically, when the share prices tick up or down, your portfolio valuation changes accordingly. Unfortunately when you use the DOM as the source of your data, and those numbers are locale-formatted numbers, just doing arithmetic on it results in incorrect values, because the underlying assumptions are broken.

As soon as you use the DOM as a data source, you are at the mercy of localisation formatting of the data. Either you need to unlocalise the data and get back the raw numbers, or you need to store the raw data somewhere else. The third possibility is to drop the feature.

Regulations

If your site is focused on a particular industry, you need to be well aware of the regulations of that industry in the countries you chose to support. If a country specifies that all financial information is displayed to at least four decimal places, then it isn’t a great idea to base your entire system on the assumption that producting data to two decimal places will be sufficient.

Be aware of the implications of regulation in various countries, especially regulation aimed at how information is presented. This is still an important part of an internationalisable platform or site.

Assumptions of timezones

Time calculations are impossible if you do not know what timezone your timestamps are in. They are still fraught with difficulty when the timezones are known, and are different.

Mostly if you know the timezones, then you can easily offset the hours. Except when the times coincide with Daylight Savings Time adjustments. Not all countries move their clocks forward or back on the same day. That’s why we have dedicated libraries on the server to deal with these calculations, and why anything time and date related should be calculated there rather than left to the developer to do in the browser.

Conclusion

The last thing you want to do for an internationalised site is to turn off features that cannot be localised, or knowingly produce something that lands in a legal quagmire of regulation. Unfortunately many of the above problems are directly related to taking a code base built for one country and adapting it as is to an international market. Certain aspects became uninternationalisable because of compromises on the server-side, and in the architecture.

Internationalisation of a code base involves cleanly separating the default locale assumptions from the business logic. This step is paramount in enabling the localisation of the platform to other countries. Skip this step at your peril, because the next step of localising it will be a painful and frustrating experience.

Differences in grammar

Every human language has its own grammatical rules and style. The chances of a grammatical structure being the same across a range of natural languages is extremely low. So code written around a specific grammatical construct in one human language presents an impossible internationalisation barrier when needing to be translated into another language.

There’s only two approaches that could work here:

1. Write a custom replacement function per language
2. Throw away the code and try again

Drawbacks of language dependent code

Unfortunately option 1 – writing a custom replacement function per language – would require a developer to be involved every time a new language needs to be supported. And that developer needs to know this new language well enough to make the necessary changes or additions to get his function returning the grammatically correct output each time.

For every natural language that needs to be supported, the developer has to supply a new function. That function most likely already contains business logic. Adding a new language means duplicating, or reimplementing existing business logic to meet the grammatical structures of the new language.

So what happens when the business logic needs to be updated? Yep, the developer now has to update every single copy of the function. Each time checking the natural language syntax is correct. That means that the developer maintaining this piece of code has to be broadly familiar with every language his code supports. And that is totally unrealistic.

Developer zugzwang.

A real-world case

I ran into a piece of dynamic sentence generation code about two years ago when I was tasked with localising some “global-ready” JavaScript for use in Europe. I was assured all that needed to be done is to replace the static strings in the code with a reference to a JavaScript translations lookup.

Here is a simplified JavaScript pseudo-code version of the code I uncovered. (Simplified so we can focus on the internationalisation issues without getting bogged down in convoluted business logic.)

function getMarketStatus(market) {
	var message = market.name;
	var now     = new Date().getTime();

	if (market.open) {

		message += " open"

		if (market.open.early) {
			message += " early"

			if (market.reason) {
				message += " for " + market.reason;
			}

		} elseif (market.open.late) {
			message += " late "

			if (market.reason) {
				message += " for " + market.reason;
			}
		}

		if (now < market.open.time) {
			message += " in " +
				formatTimeLeft(now, market.open.time);
		}

	} elseif (market.close) {

		message += " close";

		if (market.close.early) {
			message += " early"

			if (market.reason) {
				message += " for " + market.reason;
			}

		} elseif (market.close.late) {
			message += " late "

			if (market.reason) {
				message += " for " + market.reason;
			}
		}

		if (now < market.close.time) {
			message += " in " +
				formatTimeLeft(now, market.close.time);
		}

	} else {
		message += " closed";
	}

 	return message;
}

This piece of code generates one sentence of text summarising the market status. Either the market is open or closed, opening soon or closing soon, maybe earlier or later than normal (perhaps for a specified reason).

Identifying the possibilities

The function returns one of the following patterns (variable data identified with curly braced place-holders):

• {market} open
• {market} open in {timePeriod}
• {market} open early
• {market} open early in {timePeriod}
• {market} open early for {reason}
• {market} open early for {reason} in {timePeriod}
• {market} open late
• {market} open late in {timePeriod}
• {market} open late for {reason}
• {market} open late for {reason} in {timePeriod}
• {market} close
• {market} close in {timePeriod}
• {market} close early
• {market} close early in {timePeriod}
• {market} close early for {reason}
• {market} close early for {reason} in {timePeriod}
• {market} close late
• {market} close late in {timePeriod}
• {market} close late for {reason}
• {market} close late for {reason} in {timePeriod}
• {market} closed

Where:

• {market} is the name of the market under scrutiny, e.g. UK markets
• {timePeriod} is the number of minutes and hours before the market opens or closes
• {reason} is the stated reason why a marked opened or closed early or late.

The simple difficulty

That’s 21 different text strings. The likelihood of the word order remaining the same across different languages is close zero.

The simple case is that the order of atomic elements works in English, but unlikely to consistently work in other languages. And for this piece of logic to be fit for internationalisation, this order cannot be assumed to work. A translator needs to be able to use the most appropriate and correct order of the targeted language and culture.

Moreover, the difficulties don’t end there.

The disguised change of meaning

Perhaps the most insidious feature of the above code is that adding in an extra word significantly changes the meaning of previous words. Take for example these two generated sentences:

1. UK markets open
2. UK markets open in 20 minutes

The first sentence is a declaration that the market is currently open. The second, however, does not; it states that the market will open after a defined period of time. So the sentence has changed from a present tense declarative, to a future tense expectation.

The English grammar barely holds together in this change of tense, and it’s unlikely that more regular and refined languages could pull off this form of grammatical gymnastics.

Factor out the natural language

So how do we fix this? Rather simply, by avoiding constructing sentences fragments at a time. Figure out which pieces of information are needed, and then look up the most appropriate translatable sentence that matches the information.

We refactor the code above in a two step process:

1. Replace the sentence appending logic with something that keeps track of which bits of information needs to be conveyed, and pick the most appropriate sentence.
2. Add the dynamic data into the sentence by means of token or place-holder replacement

Step 1 requires a rethink of the business logic implementation. We have to keep track of what pieces of information we need to display, and from that pick the most appropriate sentence. An obvious way of doing this is to keep a translations hash with all the possible combinations, and keying those in a calculatable way.

I’ve done this the same way as the original code builds up a sentence, except I’m building up a lookup key. And the lookup key then maps to a full sentence. This level of abstraction divorces the actual sentence grammar from the business logic rather neatly. (This approach is analogous to bitwise logic; something familiar to most C developers)

After that, it’s a simple case of retrieving the correct sentence, and replacing any data place-holders with the actual information.

After these refactoring steps the code looks like this:

function getMarketStatus(market) {
	var status;
	var now     = new Date().getTime();

	// Collect the pertinent pieces of information
	// So we can pick the right translation string
	var message = {
		market:   market.name,
		sentence: ""
	};

	if (market.open) {
		status = market.open;
		message.sentence = "O";

	} elseif (market.close) {
		status = market.close;
		message.sentence = "C";

	} else {
		message.sentence = "X";

	}

	if (status) {

		// Make a note of early/late status
		if (status.early) {
			message.sentence += "E";

		} elseif (status.late) {
			message.sentence += "L";

		}

		// Make a note of any reason
		if (market.reason) {
			message.reason    = market.reason;
			message.sentence += "R";

		}

		// Make a note of any time period
		if (status.time) {
			message.timePeriod =
				formatTimeLeft(now, market.open.time);
			message.sentence += "T";

		}
	}

	// Pick the right sentence to display
	var sentence = TRANSLATIONS[message.sentence];

	// Replace dynamic data
	return YAHOO.lang.substitute(
		sentence, message
	);
}

// Mapping each combination into a sentence
TRANSLATIONS = {
	O:    "{market} open",
	OT:   "{market} open in {timePeriod}",
	OE:   "{market} open early",
	OET:  "{market} open early in {timePeriod}",
	OER:  "{market} open early for {reason}",
	OERT: "{market} open early for {reason} in {timePeriod}",
	OL:   "{market} open late",
	OLT:  "{market} open late in {timePeriod}",
	OLR:  "{market} open late for {reason}",
	OLRT: "{market} open late for {reason} in {timePeriod}",
	C:    "{market} close",
	CT:   "{market} close in {timePeriod}",
	CE:   "{market} close early",
	CET:  "{market} close early in {timePeriod}",
	CER:  "{market} close early for {reason}",
	CERT: "{market} close early for {reason} in {timePeriod}",
	CL:   "{market} close late",
	CLT:  "{market} close late in {timePeriod}",
	CLR:  "{market} close late for {reason}",
	CLRT: "{market} close late for {reason} in {timePeriod}",
	X:    "{market} closed"
};

Once we move the TRANSLATIONS object to a language-specific file we can then allow translators to translate the sentences to the targeted language.

This technique is flexible enough even to tackle the irregular grammar when the market.close object exists but with no useful data, thus {market} close could easily be corrected to {market} will close soon.

Also the flexibility will make handling the {reason} wildcard a little easier, if not perfectly.

So we avoid the need to create dynamic sentences on the fly, and instead focus on what pieces of information we need to share. And then offer the translator sufficient flexibility, through the use of replaceable tokens, to set the most appropriate translation for the targeted language.

Back in the real world…

My refactored solution didn’t go live. Instead, the feature it powered was descoped in Europe. That was the cost of using this particular anti-pattern.

In the last post we looked at simple static text replacement where the text doesn’t change from request to request. But as soon as we use conditionals to build up a text string this simple lookup method is no longer sufficient.

Simple data inclusion

The simplest of dynamic text examples we have is a message telling us which page we are on.

<?php
$pageNo = 6;
echo "You are currently on page ", $pageNo;
?>

The first pitfall to avoid is to resist creating a translation string for the static-looking text You are currently on page. Yes, this is a static piece of text, but it requires additional context for the message to make sense. This is done in the code by tacking on the page number at the end of the string. The resulting string is You are currently on page 16 which makes sense without further context.

This works in English, but in other languages it may not be appropriate, or grammatically correct for the page number to be at the end. We need to ensure that the placement of the page number is as flexible as possible.

The most straightforward solution is to use a token to represent the $pageNo variable in the text string. And at request time replace these tokens with their variable amounts. This is a three step process:

• Refactor the static looking text to use a text replacement
• Process the refactored string at request time
• Add the refactored string to the translation table

The commonly accepted practice for tokens is to use a single word wrapped in curly brackets. I’d recommend this approach because translation strings are independent of any language limitations, it’s easy to do replacement in PHP. And if you need to use these translations in JavaScript then YUI’s YAHOO.lang.substitute() handles curly bracket replacement right out of the box. (The alternative is sprintf‘s %s syntax, but be careful if there are multiple tokens that could be in a different order to what you’d expect)

<?php
// Step 1: Refactor string
$pageNo = 6;
$pageMsg = "You are currently on page {page}";
echo $pageMsg;
?>

With this refactoring we are basically just echoing out a static string that’s sitting in a new variable. Between defining the variable and writing it out we need to add in some extra code to replace {page} with the actual page number:

<?php
// Step 2: Replace tokens
$pageMsg = "You are currently on page {page}";
$pageMsg = preg_replace('/{page}/', $pageNo, $pageMsg);
echo $pageMsg;
?>

The preg_replace looks for an occurrence of {page} and replaces it with the contents of the variable $pageNo.

Now we can treat the starting string as a static text string and add it to our translations array:

<?php
$translations = array(
	"pageMessage" => "You are currently on page {page}";
);
?>

And update our main code to reference this translation

<?php
// Step 3: Add to the translations dictionary
$pageMsg = $translations['pageMessage'];
$pageMsg = preg_replace('/{page}/', $pageNo, $pageMsg);
echo $pageMsg;
?>

The benefit of this approach is that the token can be anywhere in the string and now requires no code modifications if in one language the token needs to be somewhere other than at the end. We’ve removed the locale dependencies.

Grammatical differences

One of the difficult problems of creating text on the fly is grammatical differences between languages. We have to be careful where our code is implementing grammar rules. For example, here’s a PHP snippet that prints out the number of unread email items:

<?php
$unread = 2;
echo $unread, " unread email", ($unread==1)?'':'s';
?>

This just about works in English. But translating for a different locale we can’t assume the same grammar rules apply. Obviously pluralising a word isn’t as straightforward as adding the letter ‘s’ to the end.

This particular piece of code needs to be refactored to remove the grammar logic, and then it is in a state to be localised. The obvious first step, along with our text replacement token, is to remove the conditional logic and create two separate text strings:

<?php
$unread = 2;

// Select the right message
$unreadMsg = "{total} unread emails";
if ($unread==1) {
	$unreadMsg = "{total} unread email";
}

// Replace the token
$unreadMsg = preg_replace('/{total}/', $unread, $unreadMsg);

echo $unreadMsg;
?>

And we are back into the normal lines of replacing static text with a reference to a translation. (Although Polish pluralisation is more complicated, so would need more logic or perhaps a different approach – hat tip Brad).

String translation libraries

It becomes a little tedious to create a regex rule for every token that needs to be replaced. And there are classes or libraries to do this for just about any web-facing programming language. A very elegant solution is Ed Eliot’s PHP 5 text translation library.

Ed’s class gets the basics right:

• Translations are in a separate file, one per language
• Specifying the language code and it grabs the right translations file
• the Get method takes an array of token replacements, and applies them to the translations for you

The typical approach to translating this text is to replace every piece of static text with a variable reference that points to a translation dictionary. For example the simple code:

echo "Hello world";

The static text “Hello World” should be replaced with a variable reference. In this example, let’s create a simple lookup array in PHP (in its own external file, and include it in):

<?php
$translations = array(
    'hello_world' => 'Hello World'
    // Other translation strings
);
?>

We can now replace our original text with the reference $translations['hello_world'], like so:

echo $translations['hello_world'];

With the $translations array being in an external PHP file we can have one of these files per locale or language and include the right one at request time.

This is the first step at separating the locale specific information from our code. Adding a new locale means creating a new translations file for that locale and more importantly, no code changes.

A large chunk of internationalising code for localisation involves just replacing existing text with translated versions. It is an important step, and the first one to get right. The next step will involve dealing with strings that are dynamically altered at request time.

Using images for buttons is nothing new. Accessibility wise, all you really need is some way of specifying a text-equivalent to the image, and you are essentially done.

The two main techniques of using imaged buttons are using the input type of image, or a button element styled with image replacement.

Typically the size of the image button comes directly from the design specification, which means that the text on the button has actually been a design decision, and the page design has taken that into consideration.

The result is a button that cannot be internationalised, for the following reasons:

• translating the button text means creating a new image for each translation
• the size of each image now has to change to accommodate the translated text.

There are two sane approaches to dealing with this situation, and it depends on the willingness of your designers to compromise in favour of international-friendly designs. But both solutions involve reimplementing the button markup, and if there are JavaScript event-handlers registered, there’s a strong possibility that these would need to be updated to take into account the changed markup.

The first solution is to get rid of the button image entirely, and use a proper submit input button. Then use CSS to style the button away from the default set into something closer to the original design, compromising the exacting details of text-shadows, rounded corners.

Designs that require a particular font, with specific kerning and other font metrics are unfit for internationalising websites, unless you can get your designer to guarantee that they will create and supply all the button images you need for every localisation from now on.

The second solution is to get the design team to create a tile-able button background big enough to cater for any reasonable width of text. Then using a sliding doors technique, a button element (or a cleverly marked-up submit button) can be styled to produce an elastic button background. All that’s left is to style the font of the real text as closely as reasonably possible to the original design specification.

By making the actual text back into real text your existing ways of translating text can be used, and localising forms becomes a matter of translations and other unique locale-specific requirements, not laboriously dealing with image manipulation.

Text inside images cause headaches in localising sites. It is far better to spend more time upfront coming up with a reasonable compromise that is based on text being real text, not an image.