A rather long and rambling post about various things that are likely to cause headaches when dealing with the world outside your own country. More accurately, things that have caused me headaches in the past, so others can learn from my pain.

This is also a bit of a meta-post, because it covers a lot of other posts I've written about i18n and l10n. Most of those posts are based on my experience working on software that needed to consider all this stuff and the Java scribbles I've used to demonstrate some of the complexities.

Anyway, there's a lot of different stuff in here, all based on stuff I've learnt from doing far too much work on making multiple projects, webapps and websites work for various different languages and countries.

A lot of this is also covered in other websites and articles, the Wikipedia article is a good place to start.

So, might as well start with the most obvious stuff...

The second language is the hardest

Writing your app/website/whatever to support one language is easy (or at least, as easy as it gets). Enjoy it. Get all your business logic right, get the UI/UX working as well as you can, get people using it and act on their feedback.

Sadly, the first step you take into supporting another language is where you have to do the majority of the hard work. This isn't a case of getting more complex the more languages you support - a large chunk of the complexity hits you the moment you jump from one language to two. That's the point when you need to extract all your language strings to a dictionary (resource files, language DB, i18n template system, etc), convert all your number/date/currency formatting to use proper locale formatters, add a language picker, add support for recording language & country choice for the users, etc.

After the second language, there's likely to be more i18n complexity with each new language/country (right-to-left, font choices/sizes, colours, etc), but that first step takes a disproportionate amount of time & effort. So prepare for it and work with the business teams to plan the right time to introduce that second language.

Translating the words is the obvious bit

When thinking about i18n, the obvious bit is translating all the words into the new language. And yes, that's where the majority of the effort lies. You need to extract all the text, put it in a dictionary, send it to translators, answer all their questions, check and import the resulting translations, then check and fix the app with the new language support.

Not necessarily all text - you may have some cases where you deliberately don't translate some pieces of text. That could be things like: company names, specific legal wording, quotes/comments from other people, text about translations, etc.

But, because the words are the obvious bit, I won't talk about that much more - from now on I'll talk about all the bits which are less obvious, and have left their scars on my memory.

Unicode ALL the things!

To quote a colleague of mine, who says this whenever any translation issue occurs:

Where did you forget to use unicode?

More specifically - the rule of thumb is make sure everything is UTF-8 There may be outlying cases where you're either dealing with embedded systems, or older binary formats, or various comms protocols, but in those cases, build wrappers around them for any text going in or out.

Languages don't have flags, countries do

This gets a separate post all to itself, but to repeat the basic points:

• Most popular languages are spoken in many countries
• Countries often have more than one language
• Some flags cause real offence/annoyance to other countries
• Flags can be confusingly similar, or unrelated to their given language

Naming languages and countries

Languages and countries have names, this bit shouldn't come as a surprise. It also shouldn't be surprise that different languages have different names for other languages and countries. The most obvious example I see of getting this wrong is language pickers which show the list of supported languages in one specific language.

There's no point showing someone their own language using another language's name for it. If you want a Japanese visitor to your site to pick your carefully translated Japanese version - don't ask them to pick "Japanese", ask them to pick "日本語".

Similarly, bear in mind that country and language names are not always related (obvious example - Americans speak English, not American), countries have different names in different languages (e.g. Britain in French is "Royaume-Uni") and language names are different in other languages (e.g. "Arabic" - or as a native speaker might say -" العربية", or as the French say - "Arabe").

Naming people

There are many articles about how hard this is. One of my favorites is the infamous Falsehoods Programmers Believe About Names

The rough summary is - names are complex and it's best not to try to match that complexity in your code, because you'll fail. Instead, only store what you need. If you just need to know how someone wants to be addressed - ask them that, and store the answer, as the write it. By all means give them an id that your system can use, but display their name as they use it.

Partially translating addresses

Addresses - what are they for? Mainly, for finding places and more usually - people. One of the big reasons for addresses is so we can send bits of paper (and other stuff) to them. Most countries have organisations set up to do this, maybe with a nice friendly bloke called Pat, in a van, with a cat.

The trouble is that Pat in England and 皮皮鲁 in China don't speak each other's languages. So if I post a letter in the UK, for someone in China, what language do I use for the address? If I write it in English, Pat can get it on the plane to China but 皮皮鲁 won't know what to do with it. If I write the address in Chinese, Pat will be lost.

The answer is that addresses need to be partially translated if we expect them to be used internationally. The country name needs to be written in the language of the person posting the letter (e.g. "China"), so Pat can read it and the rest of the address needs to be written in the language of the person receiving the letter (e.g. "中国北京市东城区东单东长安街33号 邮政编码: 100006" - actually that also includes "China" in Chinese), so 皮皮鲁 can get in his van to deliver it.

Luckily, Pat and 皮皮鲁 and the posties of the world are usually very helpful, they'll try to figure out what the address means, however it's written. But that's not an excuse for making their life harder and risking your letters being misdelivered or stuck in the "dunno" box at the sorting office.

What time is it? What year is it?

Dates and times are hard. Once you start digging into how they actually work around the world, especially if you need to deal with dates a fair way into the past, you're starting down a very deep rabbit hole after Lewis Caroll's white rabbit.

There are many articles talking about how hard this topic gets, but just to get you started, here's another "falsehoods ... " article: https://infiniteundo.com/post/25326999628/falsehoods-programmers-believe-about-time

On the back of some work I did figuring out how to handle DST in different countries, I wrote a separate blog post about TimeZones in Java

And just in case you thought that although time might be hard, it can't be hard to decide what year it is, I also did some poking into Java Chronologies.

One final comment on time - Leap Seconds. These have been happening for years, but every time a new one is added operating systems and NTP servers everywhere have a flurry of new problems to address, including knowing which "timezones" don't acknowledge them (i.e. TAI). Here's a detailed article written about the last one, in 2016 Preparing for the 2016 Leap Second

Formatting - nothing is ever easy

Once you've extracted all the text, sorted out all the date and time differences, figured out how to address people and locations there's still the problem of how to stick all that information back onto the page/screen in a format the user finds familiar and useful. I've mentioned some of these elsewhere in this article, but some of the things that will need their formatting to be locale aware are:

• dates and times - everyone has their own way of writing these, sometimes 3 or 4 ways!
• numbers in general - decimal separators, thousands (or otherwise) separators, negative
• monetary amounts - often different to general numbers, with fewer decimals, extra symbols (or not)
• measurements - especially those including fractions (e.g. 4 yards, 3 feet, 2 inches, 320 thou)
• Ordinal numbers - the 2^nd floor, or the 2º floor in Italy
• Honourifics and titles - do you call Fred Bloggs with a PhD "Doctor Bloggs", "Fred Bloggs PhD" or "Dr. Fred Bloggs". What about in French?
• Place addresses - largest to smallest area (e.g. China), or smallest to largest (e.g. UK), post/zip codes before or after city/region, etc.

Edge cases and gotchas hide everywhere

I'll just throw out a few examples that have bitten me in the past...

Chinese "long form" dates aren't that long

A quick bit of Java 10 JShell

var df = DateFormat.getDateInstance(DateFormat.SHORT, Locale.CHINA);
df.format(new Date());
$29 ==> "2018/6/16"

var df = DateFormat.getDateInstance(DateFormat.MEDIUM, Locale.CHINA);
df.format(new Date());
$23 ==> "2018年6月16日"

var df = DateFormat.getDateInstance(DateFormat.LONG, Locale.CHINA);
df.format(new Date());
$25 ==> "2018年6月16日"

Yup, the medium and long forms are identical, and both have one more character than the short form.

Nepal's flag isn't a rectangle

You weren't counting on all country flags being rectangles for some nice HTML styling were you?

Some currencies aren't currencies

I wrote a separate article about localising currencies in Java.

One of the points I made there is that not all the "currencies" used around the world are actually currencies used to actually buy & sell things. Hence they don't all have exchange rates, which can cause problems, especially if you're dealing with complex test cases.

Different Spanish, different format

Another quick bit of Java 10 JShell, showing the same number formatted in Ecuadorian Spanish and Guatamalan Spanish.

var nf = NumberFormat.getInstance(Locale.forLanguageTag("es-ec"));
nf.format(1234567.89);
$40 ==> "1.234.567,89"

var nf = NumberFormat.getInstance(Locale.forLanguageTag("es-gt"));
nf.format(1234567.89);
$46 ==> "1,234,567.89"

That's two different Spanish variants, from countries fairly close to each other, one uses dots for thousands and commas for decimals and the other does it properly (ahem ).

Date arithmetic isn't commutative

"plus one year, minus one day" is not the same as "minus one day, plus one year". Start from the 1st March 2012. Add a year, go back one day, you're on 28th Feb 2013. Now start from the same day, go back one day and add a year, you're on the 29th Feb 2013 - which doesn't exist, exception throwing time!

And that's just dealing with the ISO calendar - so not strictly i18n related. However, there are different calendars in use around the world and throughout history (as I mentioned above). If you need to do any date translation between calendars, or even worse, date calculations across calendars, be afraid - and write a big pile of test cases.

The only constant is Change

Eventually you start to get the rules straight, settle on some traslations, use the right formatting tools, you've validated everything everywhere and generally started to get that backlog of i18n issues down to a reasonable level.

Then in sneaks real life. Countries change their name, Libya changes their flag, Tonga irregularly changes their TimeZone, Netherlands Antilles stops existing, a number of currencies disappear overnight when the Euro appears, New Zealand might add a new official language, and on and on.

Yes, really, all of those and more.

And that's just the easy stuff

All the stuff above is actually fairly straightforward - because on the whole there are fairly well defined rules to follow. They may be complex rules with lots of edge cases and unexpected interactions, but at least they are specified.

The real complexity appears as we get to more subtle, cultural things like colour choices, familiar print/screen layouts, semantics and grammar, forms of address. With this stuff there's no single right answer, although there are an awful lot of wrong answers - any of which can start an argument.

If you're being serious about i18n/l10n, then on top of all the issues to do with just being understood and not confusing people, you're going to need to consider some complex political and historical issues. This is a massive topic, but to give a few quick examples of the kind of stuff you'll be getting hit with...

• Is "Palestine" a country? (Depends who you ask and who you want to write hit pieces about you on social media)
• Do the Taiwanese speak "Chinese"? (and which variant, in which country)
• Does the Isle of Man count as European, or British? (depends if you're buying duty free, setting up a financial deal, or going on a day trip)
• Is Costa Rica in the USA? (depends whether they've just had a disaster and the US is trying to avoid helping)
• Can someone give themselves the username "Jehovah"? Or "Goebbels"? (Depends on your religion, country, legal system, and your parents)

Previous Post Next Post