Things you want to know before localizing your app

Original photo by Etienne Girardet

The task of translating texts on the screen to different languages may seem easy in comparison to product features development. Especially when the business estimates the effort. But the reality may be very different when you will start translating a big enough application that was not built with localization in mind from day one. 

This article sheds some light on several important aspects of localization that are not necessarily obvious for those who deal with this for the first time. But at the same time are very important to take into account from the very beginning of this process.

Parts of the system that are subject to translation

If your system has already grown big enough there is a risk of underestimating the effort needed to translate every single text that the user can see on the screen. And this is our goal, otherwise, localization will look incomplete. Texts to be translated can come from:

• HTML templates (most obvious)
• Libraries used on the client-side, both internal and 3rd party (e.g. internal components library, 3rd party date picker library)
• Server-side code (e.g. error and success messages, enums with string values)
• Database (e.g. category names, menu items)

And then you can have internal libraries built with different technologies that will require a completely different approach for localization. And the same is true for microservices on the server-side.

Choose translation management platform carefully

The translation management platform is the place where you will upload all the texts in the source language and where professional translators will be translating them. This is the very basic function of the platform, but to automate your processes, you will likely need many other features from the platform, like:

• integration with Git providers
• import/export settings
• translations QA
• tasks automation
• chat with translators
• other features specific to your project

Don't underestimate the importance of choosing a good translation management platform. This will be one of the most impactful things defining the overall success of the product localization effort and the continuous localization process in the future.

I have a favorite among all available options that my company has chosen after comparing different vendors. I prefer to not mention the name here though as the article is not supposed to promote any services. If you are interested in my opinion, feel free to PM me (you can find contacts in my profile).

Glossary before everything

Regardless of how much in rush you are, you want to have a glossary before translators will start their work. It is paramount to make sure that terms critical for your business domain will always be translated correctly and consistently.

Do not plan translation agency selection as the last thing to be done when everything else is in place. Agency selection should happen in parallel with technical work. As soon as you have both the translation management platform and agency (or whoever will be doing the translation work for you) you are good to start glossary translation. The list of glossary terms can be prepared even before that by someone from your team.

Be prepared for language differences

Imagine the following sentence you can easily have in your application:

{{ timeInSeconds }} seconds ago

The most straightforward way to approach localization here would be providing only the seconds ago part to translators as we don't need to translate the number. That makes sense. But unfortunately, word order is not the same in all languages. For example in Spanish phrase 5 seconds ago will look like this:

Hace X segundos

Do you see the problem here? In Spanish ago is written in a verb form and it goes at the beginning of the sentence. Expecting word order in all languages to be the same is similar to testing the happy path scenario only. It will be
an impossible mission for the Spanish translator to translate it correctly unless you will:

• choose a localization solution that supports placeholders (you likely will)
• make sure you and your colleagues follow the best practice to provide full sentences in localization keys: {{ timeInSeconds }} seconds ago
• make sure the translation management platform allows translators to move placeholders in translations

Provide translation context

If for whatever reason you can't provide the full sentence as suggested in the previous paragraph, make sure your localization solution supports providing additional context for translation keys. Assume we have the following pseudo-code snippet:

function getUploadProgressMessage(percents) {
  return __('You file is being uploaded: ') + percents + '%' + __('left');
}

Where __() is the function responsible for marking text as translatable. This function will look for the translation(say for the German version) in a JSON file that might look like this:

{
 "Your file is being uploaded": "Ihre Datei wird hochgeladen",
 "left": "?"
}

For you, as a developer, it's clear what is the meaning of the word left here. But a professional translator who will encounter this word as a separate translation key somewhere in the translation management platform will likely have no clue in which context left is used here. Is it a noun or a verb? Could be left for later, could be just a standalone left. 

In cases like this translator will ask for context first to translate the word correctly. If you don't have a way to provide the context in advance, you will doom developers or a localization manager (often both) to never-ending Q&A sessions with translators as new translatable content is being pushed all the time. To avoid this, your translation tools should support providing context, for code example above it could look like this:

__('left', 'Full sentence: Your file is being uploaded: 30% left');

And translation file for the German language could look like this:

[
 {
   source: "left",
   target: "",
   comment: "Full sentence: Your file is being uploaded: 30% left"
 }
]

Note this is just pseudo-code using JSON format for simplicity. Whatever format you choose, make sure your translation management platform will display these comments and they will be treated by translators as comments. Pay attention to standards like XLIFF that are supported by most translation management platforms and can be used if supported by your localization tooling.

Do not agree on routine work before you have explored all the options available to automate the process

When you have an existing application that has been developed for several years and should be now localized, expect a lot of routine work. Regardless of what technology stack is used in your project, there is a high chance that someone has already faced this challenge before and created tools to reduce the burden of routine work. It's mostly about your time that can be spent more efficiently but also about the chances of missing something out in the code. You might be interested in code analysis tools that can automate the following things:

• Finding all strings that look like translatable content
• Marking these texts for translation

For HTML content it is possible. Concrete implementation depends on the frameworks and libraries used. For other types of files, some patterns can point to the fact this string looks like translatable text, e.g. string is starting with a capital letter, no underscores used, etc.

Trust and verify

This is an important addition to the previous advice. You likely don't want to rely on automation completely. Applications are very different and there is no "silver bullet" type of tool that can take everything into account. Just to give you an example: in the world of SPA in your HTML templates, you likely have some attributes that should be translated e.g. placeholders and some custom attributes that have special meaning in the context of your project and should not be translated.

Let the automation tools find and mark texts for you and then verify the results and correct them where necessary before committing the changes.

Continuous localization

This is an existing term that makes a lot of sense. Just like with any other task that should run on every change (unit and e2e tests, code smell checks, etc.) you want to automate your localization processes.

Concrete tasks to be automated will depend on your localization workflow. But here are some examples of tasks you will likely want to automate:

• Pushing new translation keys to the translation management platform
• Pulling the latest translation files from the translation management platform

And if your chosen localization tools allow automating this as well:

• Extracting new translation keys from the application source code

Make sure your company on is the same page as you

Unlike other changes in software products, localization is not something you implement once and it just works from now on without any attention needed. New pages, tabs, and forms will be created in your Web application all the time, bringing new texts. Existing text wording will change as well. That means, when you are done marking existing texts for translation, you need to make sure the following will be true:

• Everyone in the company is aware of the fact that your product supports multiple languages from now on and marking new texts for localization is everyone's responsibility. 
• Translation keys extraction, upload, and download processes are automated as much as possible.

Here are some tips (quite obvious, but still) that can help you achieve this:

• Document all the processes. 
• Communicate it the right way. Probably you will need to do this multiple times. 
• Do your best to make it impossible to commit code that contains new texts that are not marked for localization. Linting tools can help to achieve this.

Conclusion

I hope this article will help you to estimate the effort needed to localize your application properly. Not necessarily all of the tips above apply to your project. But most of them are very generic and hopefully can save you and your colleagues some time.

If you have any questions feel free to ask here in the comments or reach out to me directly on the social platforms you will find in my profile.