First of all, why do we have this blog post? What is the question that we're trying to answer here? The topic was raised by my colleague in the UK, she asked me specifically about the localisation, toolings, and insights into big 'NOs' or 'YESes' in the Asia-Pacific region.

So I am trying to answer the question and talk about frontend localisation, since my company have expanded to many places now in APAC, Singapore, Philippines, Vietnam etc.

Most likely, you will encounter the weird word "i18n" when you work in front end development. If you wonder what the 18 stands for? It's not 18 different languages. Instead, it is just the number of letters between first i and last n of the word internationalization.

Before we start, just a quick introduction about myself. I was working in a bank as a technical lead, and I am writing about my past life in banking, which is full of acronyms. You would realise everything in banking is an acronym, so it sounds more professional and no one knows what you are talking about.

The company I worked in is called HSBC, which stands for How Simple Becomes Complicated. If you think that changing a character on a website is easy, then you are wrong. You have no idea how complicated the process is, which include the business team for requirements gathering, the development team using git-flow and code review, the QA team for testing, the release team to deploy… which usually takes 2 weeks to change 1 word in a production webpage.

I was in a team called ASD-ASP, which means Accelerated Scaled Delivery in the Asia Pacific, so my job was to build regional features on the web and mobile, such as FPX in Malaysia and PayMe for business in Hong Kong. All the examples I gave in this blog post are real-life experiences.

Take this page for example. You would be surprised what could go wrong on this page. Can you guess what's wrong?

The problem is the timer. Imagine you are blind, and you use an accessibility tool to navigate the page. You would have no idea there are only 10 minutes left for you to complete the transaction. And if you navigate the page, find the time and read it out loud, you will get crazy, it just says "10 minutes left, 9 minutes 59 seconds, 9 minutes 58 seconds…" and it just read aloud every second and you have no time to complete your transaction.

And to build the page you just saw, the tooling we used was AEM, which stands for Adobe Experience Manager. There are only a few companies in Hong Kong using AEM. It's a legacy content management system that could only generate static pages. So to make things worse, we need to use Angular/React in TypeScript to generate dynamic single-page applications on top of it.

And for mobile, we were using the internal tools written in python script. The copy team would put the copy in different languages on a confluence page, then the script would read the confluence page to generate a localised JSON file in key-value pairs. Then the developer put the generated file in the app. It creates more problems than it solves, which I will explain later on. 

With AEM, the idea is that the copy team with no technical knowledge can still update the page. But in reality, usually, the frontend engineer would make the change of text, while the dialogue itself was also built by a frontend engineer using XML, so it creates an extra layer of unnecessary work.

With an internal tool on the confluence page, the copy team would try to label the frontend design. What could go wrong here? The design screenshot would most likely be outdated. Then different frontend engineers would put a different copy key representing the same thing. There is no standard and if people reuse the same key on different pages, it would create surprising side effects once you update the values.

Next, make a guess what could go wrong with the screen below? Actually, there are many issues here if you try to localise it. There are at least 5 items, let me show you.

The first big NO is to use the word country. This is a real production issue that I encountered. If you scroll down this country list page, you will see Taiwan and Hong Kong. Who thinks Hong Kong is a country? You are in trouble and violate the national security law. You can get into jail by putting Taiwan as a country.

The second big NO in this screen is you forget to localise the search bar. You would need to index it in different languages. But when you translate the country list, for example, the alphabetical order no longer works. You would need a list of different sort order for example.

And the fuzzy search is going to be different behaviour for different countries. For example, in China, people are using pinyin to search. The English word "hello" as an example, the Chinese word is translated as "你好" and pinyin is "Nǐ hǎo". People would only use the initial to search by typing in "nh". I wrote an open-source library 5 years ago to do this. The link is: https://www.npmjs.com/package/hanyu-pinyin

The third big NO is you may forget to translate the error message. The error message could be front end validation, using regular expressions. But then the regular expression would not work for other languages.

And If you use a server-side error message to generate the message, then do not localise the message at the backend, unless you are using the server-side generation of the page for performance reasons like Gatsby. It's common problem I see when frontend engineer is lazy, they just translate the whole message at the front end. The problem is when you add a full stop in the example below, then you are screwed. So use the error code to do the mapping instead.

i.e. Don't do:

Backend error: {
"Msg": "Something went wrong"
}
Front end mapping: {
"Something went wrong": "出了些問題"
}

Instead, do this:

Backend error: {
"Msg": "Something went wrong",
"Code": "ERR01"
}

Front end mapping: {
"ERR01": "出了些問題"
}

The fourth big NO is no versioning on your translation. Like the screenshot below, this v1 is "log in", the v2 is "sign in", then v3 is "Logon" and v4 is "Log On" with a space. The business team always changes their mind and it becomes a big problem. Every time after a code cut, we need to do a patch, just to update the copy to please the business team.

The fifth big NO is to ignore the translation of accessibility for blind people. Blind people cannot see the cross icon on the screen, they can only see the alternate text, and it's very frustrating for a Chinese person who doesn't understand English and hit the alt text as "clear". But QA will miss this kind of issue.

Besides, don't use Google translate. And I had a real example from our marketing team on the press release. For those who can read different languages, it's self-explanatory how ridiculous it is. For those who can't understand other languages, the English phrase like "bank agnostic" is very hard to translate, it would just mean "unhook" and looks ridiculous.

For the big YESes, yes, size matters. "Do consider different screen sizes as different languages have different lengths." "請考慮不同的屏幕尺寸，因為不同的語言有不同的長度", see the Chinese length is shorter. I mean the sentence, not something else.

Yes, do consider languages that write from left to right instead of right to left. e.g. Arabic

Yes, do use a template language, such as a handlebar, to allow inserting variables in a string. e.g. html

<html>

  <p>Hi, my name is {{name}} and I live is {{city}}.</p>

</html>

Yes, do involve the legal team to check the terms and conditions.

Yes, do display in local currency instead of the British pound (1 GBP = 1.85 SGD). I had made a production incident before due to decimal places in different currencies. For example, JPY has no decimal places, and Russia was not following ISO4217. If you bought a flight to Russia as a customer, you may charge 100 times more expensive due to the bug in currency decimal places conversion.

And yes, do display dates in a localised format.

Besides, there are some technical issues to consider:

  • String may not escape probably, e.g. 'Something's wrong' vs 'Something//'s wrong'.
  • Snapshot testing would be failed with a new copy, update snapshot if necessary, or synthetic monitoring may hit an error when key change.
  • Hard to translate technical terms, e.g. Agile, Scrum Master = ?
  • Hyperlink in the text needs to redirect to the localised page. We always get this bug in production, wherein a Chinese page with a href to another English page instead of a Chinese page.
  • WeChat Pay / Ali Pay had Chinese documentation only at the beginning when I was doing the integration. The software engineer who can read English only was like what the fuck.
  • Mobile app get system language instead of app selected languages.

Traditional Chinese in Hong Kong and Taiwan, Simplified Chinese in mainland China and Singapore, Vietnamese in Vietnam, are the three common languages that I worked on. Notice even in English, it got a couple of variants, such as Malaysia Amanah, due to shariah compliance, you would need to rephrase "interest" to "Urijah". And it has a different product name.

If you are working with Gatsby, these are the i18n libraries that may work for you:

Overall, there are many things that could go wrong in localisation. The best solution is to work with the locals, and they would easily spot the obvious problem.

Any questions about localisation? Feel free to let me know 🙂

 This post is ad-supported
​