Internationalization as a form of technical debt


The term technical debt is often used to label implementation choices that trade long-term goals for limited, short-term solutions. Technical debt has a negative connotation because it means that you have accrued a technical obligation that must be resolved before you can make future progress. Teams take on technical debt for many reasons: short schedules, insufficient knowledge, poor team collaboration, and a host of others. Generally, you want to avoid technical debt because it represents a technical hurdle that you have avoided or have resolved only partly. Technical debt limits the rate at which can innovate and progress in the future.

I’ve often thought about how many product and software teams approach software internationalization. The typical team will begin development with a single geographical market. The team knows that they want to succeed internationally, but they don’t worry about that concern at first. They have schedules, product features, and short-term needs that demand attention. They sacrifice long-term goals for short-term wins. They ignore best practices in software internationalization because of insufficient knowledge or perhaps even laziness. Over time, internationalization work becomes technical debt that must be paid to make further progress into desired markets. 

The disheartening fact is that unattended technical debt in internationalization will eventually require code refactoring, new implementations, and even updated designs. Interest increases rapidly. At some point, you may not be able to do everything yourself, and you might need external help.

Fortunately, internationalization does not have to become technical debt. Basic internationalization usually does not have huge upfront costs for either schedules or resources. Internationalization can be integrated into every sprint or delivery schedule. The very basic concepts are simple, and a little up-front and regular consideration will pay huge dividends.

So, what can you do now to avoid technical debt in internationalization? I suggest you tackle this in a few steps:

  1. Make everyone responsible for knowing the basic issues and concerns in internationalization.
  2. Resolve to implement best practices for each of the concerns that will affect your product.
  3. Make internationalization a part of your ongoing development and review process.

In an upcoming blog, I’ll provide you with some resources for each of these steps. 

All the best,
John O’Conner

Language Signals on the Web


Presenting a user interface in the customer’s language should be a high priority from your product management team. If not, they’re not doing their job in my opinion. Assuming you have the feature in your product roadmap, how do you choose the UI language of your customer on the web. After all, web applications have multiple, sometimes conflicting language signals.

A language signal is an indicator that gives your application a hint of your customer’s preferred language. In a web application, these signals are numerous. To help you in choosing from all these signals, I believe you should honor the preferences in the following priority. That is, check each signal for its existence in this order, and use the first signal that is available:

  1. query parameters, for example
  2. domain name or path parameters, i.e. or
  3. persistent application preferences
    • cookies
    • customer profile or settings
  4. browser accept-language headers
  5. geolocation hints
  6. default application language

Query Parameters

Query parameters are often used to override every other language or application signal. If parameters are used, your customer (QE engineers or even end users) are intentionally trying to coerce the application into ignoring all other language signals. Query parameters beat out any other language signal when they are provided in the same request.

Domain name or Path Parameters

Sometimes you will partition your localized sites by domain name or by language tag paths. A domain name partition means that you select different or even localized domain names for specific markets. For example, your French site could be You can also distinguish language preference on the path like this: or When query parameters don’t exist, this is the next choice in our prioritization.

Persistent Settings

Of course, if your application has allowed the user to select a language preference, the application should honor that preference. The preference may be stored in a cookie or even in a user profile attribute on the server.

Accept-Language Header

Most browsers provide a list of user language preferences in each request. These languages are provided in request headers as values of the accept-language attribute. This attribute can have 1 or more language codes, and they indicate the priority of the user when requesting content. In the absence of other signals, your application should respond to the accept-language header.

Geolocation Hints

The last signal that actually provides information about the user is the geographic location from which the user is accessing your content. Although imperfect and imprecise, geography can provide a hint to your customer’s language preference. It’s definitely not the best indicator because multiple languages can be spoken in any geographic location. In a pinch, though, you may be able to provide a language selection tool that provides a list of the most prominent languages spoken in a specific area of the world.

Default Application Language

Finally, when all else fails and there have been no other indicators, you can provide the UI in the default language of the application. If your company is in Germany, maybe the default is German. If it’s the U.S., your default language is most likely English…or maybe even Spanish. You have to display the application in some language, and the default at this point is your last option.

In Summary

To summarize, a web application can serve a global audience. In doing so, it may accommodate customers in a variety of languages. Your application’s user interface may be selected from numerous possibilities, numerous signals from the user. Those signals are important data points to consider when making the language choice to present to the user. Using the signals described in this article, you’ll be able to consider some of the more important language preference indicators. Follow the prioritization I’ve outlined here, and you’ll make the right language choice most of the time…until you don’t. And there will be times when you don’t make the right choice from all these signals. When that happens, and it will happen, you have to give your users some way to indicate that problem. Take a look at my previous blog entry about language selection widgets for help with that.



Even Apple Messes Up Sometimes

You have to respect Apple. They have excellent products that are known worldwide for their quality and ease-of-use. Part of that ease-of-use comes from their commitment to producing internationalized, world-ready products. However, even the best companies and employees make mistakes.

Recently I purchased a new iMac 27″ computer for my family. Of course, they don’t believe it is for them since I spend the most time using it. But I’m going to stick with my story…it’s the new family computer. Anyway, I immediately noticed that Apple is pushing their iCloud service. During setup and first run of things like iPhoto, I was prompted to choose whether I wanted to use iCloud for backups, etc.

Of course, I had to try out the iCloud service, so I entered all my personal details — name, account id, etc. The service works as expected, and I have nothing interesting to report on that.

To make iCloud clearly available and visible, Apple puts the iCloud service settings into the System Preferences application.

icloud settings

Clicking on the iCloud icon brings up the iCloud settings of course. Again, not much to say there. You have all the typical iCloud-able apps to choose from: Mail, Contacts, Calendars, Photo Stream, etc. However, I did quickly notice that iCloud had a little trouble with my name. Instead of showing my full name as John O’Conner, the iCloud app prominently displayed it as John O'Conner. Oops.

Icloud name

I admit that this is not the first time I have seen my name displayed in this way. Web forms sometimes mistakenly store my name using character entity references. Apparently the apostrophe sends bank and medical systems into fits of confused stupor. However, I’m surprised that it trips up Apple in this way.

It just goes to show you that even some of the best companies can make mistakes with how they handle and display text data. It’s common to normalize text when putting it into a database. However, I don’t think a character entity reference is the right thing to put into your db. If you do, you certainly should remember to decode it when you display it to your user.


Answers to Which Countries Have Multiple Time Zones

Yesterday I asked the question:

Which countries have multiple time zones?

And I promised an answer today. Congratulations to Paul Clapham, who made a great effort listing them!

The W3C document Working with Time Zones is the source of my information. That document lists the following countries as having more than one time zone:

  • Argentina
  • Australia
  • Brazil
  • Canada
  • Chile
  • Democratic Republic of the Congo
  • Ecuador
  • France
  • Greenland
  • Indonesia
  • Kazakhstan
  • Kiribati
  • Mexico
  • Micronesia
  • Mongolia
  • New Zealand
  • Portugal
  • Russia
  • Spain
  • The United States


Offensive Hand Gestures of the World

Recently I told some colleagues that I wanted to write a book about offensive hand gestures around the world. In my business, it’s common knowledge that icons of hand gestures just don’t localize well. We’re told to avoid using icons of hands and fingers because we might offend someone in a different culture. I’ve always known that anything can be offensive to someone somewhere, so of course I’ve accepted this as truth. Seems reasonable to avoid hand gestures when I can.

However, in all my years working in globalization and localization, I’ve never once been provided a comprehensive list of gestures that should be avoided. And not surprisingly, I’ve always wanted to see that list! In fact, I’ve wanted that list of offensive or rude gestures so much that I promised I’d write a book on the topic.

Oddly enough, it turns out that someone else has already beat me to the task. And I’ve discovered this not a moment too soon — I was already interviewing hand models. :) So, now that I know that someone has already beaten me to the job, I suppose I can now take that book off my todo list and just get a copy of it.

In my extensive research on the subject, I’ve found 3 books. THREE! On one of my late-night runs to Barnes and Noble, I saw the first one on my list — it was in the old discounted book pile. What a pity! Now pull out your credit card and take a look at these gems. I know I’ll order at least one of these:

  1. Rude Hand Gestures of the World
  2. Gestures: The Do’s and Taboos of Body Language Around the World
  3. 70 Japanese Gestures: No Language Communication

It’s really too bad too…I could really feel myself being pulled into this work. Maybe I can hope that the original authors do a 2nd edition and allow me to help? Man that would have been a fun book to research and write! But alas, I’m too late! But finally I’ve found the book I’ve wondered about for so long!