Internationalizing Your Software Part One: The Process

When I first started at Lucid Software in 2017, I was on the internationalization team, commonly shortened to the numeronym “i18n” because there are 18 letters between the “i” and the “n.” As a software engineer with a Bachelor of Arts in Linguistics, this position was a great place for me to start at Lucid and experience internationalizing software. While our software was previously only available in English, now it is available in seven different languages: English, German, Dutch, Portuguese, Spanish, French, and Japanese. In this blog post, I reflect on some of the important things I’ve learned from my combined experiences working with languages and working at Lucid that may help you internationalize your own software.

Plan on i18n from the beginning

Even if you are initially only releasing your software in a single language, if there is any chance you’ll want it translated in the future, start thinking about i18n as soon as possible. Plan for the future by putting all user-facing phrases in a centralized location. That way, when you decide to translate them they are easy to find and work with. If you don’t start this way, it will be much harder later on to dig through your code searching for phrases, which may result in missing critical phrases that should be translated. Even if the process you begin with is not your final solution, it is a good idea to have some method for dealing with user-facing strings and referencing them in your files rather than hard-coding words everywhere. Your engineering teams will be grateful in the future, trust me.

Create a scalable system

An established system with centralized, easily accessible strings is vital to internationalization efforts. It should require minimal effort and negligible time to adhere to the process; after all, an engineering team’s primary goal is creating and improving quality features, and i18n shouldn’t be a barrier to that goal. The system you create for i18n should accomplish the following things:

• Make it easy for engineers to add strings
• Make it easy for the strings to be sent to professional translators
• Make it easy for engineers and quality assurance to test the software in different languages
• Be well documented and consistently used

Consider these questions as you architect your system and explore ways to make processes and standards a natural part of the engineering process:

• How and where will you store strings?
• Will you need to use different methods for your application’s frontend and backend?
• How will you organize strings (alphabetically, by feature, etc.)?
• How will you handle in-phrase variables such as names and numbers?
• How will you handle embedded HTML or similar UX requirements in your strings?
• What tools will you use for formatting numbers, dates, currency, etc?
• Who are your translators, and how will you send them new strings to translate?
• How will you ensure your translations are complete before the code is released?
• How will you make it easy to test the UI in different languages?

Of course, documenting the processes for your i18n system is critical to your team’s efforts to follow your i18n standards consistently. Consider how to share the guidelines you are setting up and who will need to know about them. Would an official training be worthwhile, or would an email suffice? How will new hires learn about your processes? Internationalization will only work if everyone is on board and aware of the requirements.

Translate entire phrases

Translating words individually will result in weird and awkward language. It’s better to always provide the translators with the entire phrase and let them rearrange the words and variables to match a given language’s structure. The following examples illustrate a few of the reasons why giving translators bits of phrases is problematic: Let’s say we have a translate function which takes in a string and returns its translation:

const translatedString = getTranslation(“translate me”);

Seems simple enough, right? But what if the string we want to translate contains a variable? The wrong thing to do would be this:

const agePhrase = bob + getTranslation(“ is ”) + age + getTranslation(“ years old”);

In fact, don’t do this either:

const nameLabel = getTranslation(“Name: ”) + name;

Or even:

const name = firstName + “ ” + lastName;

But, why? In Spanish, the normal way to translate agePhrase is:

bob + “ tiene ” + age + “ años.”
bob + “ has ” + age + “ years.”

In Russian, it would be translated:

bob + “ ” + age + “ год/года/лет.”
“To ” + bob + “ ” +  age + “ years.”

For context, in Russian, the name itself would be changed to the dative case to mean “To Bob.” Russian doesn’t use the verb “to be” in the present tense. And the word “years” would be different depending on if the number ended in 1, 2-4, or 3-0. When considering other languages (and the examples above), have you thought about what to do if you need to translate into a language that isn’t written from left to right? Or if a language doesn’t use punctuation or connect names the same way you do? Language structures are complex and can differ greatly from what you might expect. Just because a word and phrase combination makes sense in one language, doesn't mean it will make sense in another—in fact, it probably won't. A good engineering solution will take that into account. So, for the agePhrase example, a better approach would be to provide a whole string with placeholders for your translator to handle. Then you can find a graceful approach to substitute the placeholders:

const agePhrase = getTranslation(“User {name} is {age} years old”, {‘name’:bob, ‘age’:age});

An approach like this allows translators to properly translate the entire phrase so that the text of your product can read well in any language. In this three-part blog series, part two will cover more language differences and include suggestions for handling them.

Hire professional translators

Machine translations may seem attractive but are not a high-quality long term translation solution. While machine translation is definitely improving, it has a long way to go before it can understand and analyze language the same way a professional human translator can.

  Computers don’t actually understand the language that they receive, or the greater context. Human translators can account for complex linguistic situations that computers can’t, including the following cases:

• A word in language A has multiple equivalents in language B or has different meanings depending on context.
• Language A has different syntax (word order) than language B.
• More information is required in the target language than in the source language. For example, to translate the word “sister” into Chinese, I need to know if it is an older sister or a younger sister. To translate “I went” into Russian, I need to know if the person speaking is male or female, and if they went by foot, by car, by plane, or by boat, etc.
• Language A uses different idioms and metaphors than language B.
• A phrase that is perfectly normal in language A is culturally inappropriate and insulting in language B (or there are other sociolinguistic differences between the languages).

It may be tempting to look for a quick/cheap translator by asking around for a volunteer who speaks the target language. However, being a fluent speaker does not mean someone has the skills to be a good translator. If you want a high-quality product, you shouldn’t settle for subpar translations. A professional translator should have the skills to produce a translation that reads well and accurately maintains the meaning of the original message. There are many translation professionals and companies out there who can help, including the American Translators Association. Finally, keep in mind how quickly you need translations after requesting them. Some services have longer turnaround times, while others are extremely fast. Some services may also allow translations to sync automatically with your product. Whatever your priorities are, you should be able to find professional translation services to meet your needs, but it’s best to know your priorities and plan ahead to the best of your ability. Tune in soon for part two of this series, where I will go over more differences between languages and how to handle them in your code.