How to Prepare Your App for Localization

The time has come and your product manager has asked you to start preparing your old app for internationalization (i18n) support. The requirements are written with one line: “Add support for multiple locales”. You are starting to sweat and begin to have heart palpitations. How can we do that now, after years of working in this chaotic codebase?

No reason to panic! This guide will show you in short, simple steps, how to prepare your app for localization (l10n). In the end, you will not only find yourself in a better position to work but will also have satisfied the management’s instructions.


Laying the Groundwork for Localization

Preparing an application for localization is not typically a simple process, but we can make it easier if we follow certain best practices. If you have a large application that has not accommodated any sort of i18n support without any framework, then we have a road ahead of us. However, if we use a library such as React or frameworks like Angular, then we are in a slightly better position.

In either case, we should sit down and evaluate the changes required and how to best accomplish them without breaking stuff. We should first start with the current project and its status. Let’s see the different cases:

Project Is in Planning Status

If the project hasn’t started yet, then the design decisions are easier. Depending on the chosen framework or library you plan to use, you can find appropriate i18n libraries and start integrating them from the beginning. For example, we have the best libraries for React i18n or similarly, the best i18n libraries for Angular. Make sure you choose one and follow the instructions on how to set it up during the initial stages of development carefully.

Project Is Launched but Few Customers Are Using It

If the project is in production but still in the early stages, we may be also in a good position. As the codebase might be small, it would be easier to add an i18n library and translation strings in one go without a lot of changes.

Project is Launched With Customers Using it

If the project is in production but has a large codebase, and the customers have been using it for a long time, then things might get tricky. A change as invasive as adding i18n and l10n support to an app will not be trivial to handle. It is recommended to do gradual releases to the app – or regional updates – so that only a certain percentage of the users get affected in case of mishaps.

For example, you could first release the project with the instances of the translatable messages replaced to handle the default locale. For the users, they won’t see any difference but you would have done the first step. Then you can gradually add locales on each release so that you will have time to react. What’s important to have in mind is that ideally, you should have a way to add new translations without redeploying the application so that you can correct any mistakes without any disruptions.


Mapping Out the Preparation Steps

Now that we have established the general direction forward, we can describe the steps in detail.

Find Translators

Before you embark on the process of localizing your app, you need to invest in the most important asset: finding quality and affordable translation services. This is so you can fit the content with the website or application you want to deliver and make sure that the text displays correctly. You will also need to set up a good relationship with new translators – and finding ones that fit your purposes may take some time.

In our case, we have the guarantees of Gengo which offer quality translations within hours, backed up by a team of professional translators. They also offer specialized translation services for most of the commercial platforms such as Magento, WordPress or YouTube as well as a cool API for developer usage.

Get a Translation Management System (TMS)

The next most important step is to find a system that will manage the translated content and any sort of localized material. You may resent this thought believing you may not need it, but we recommend you to give it consideration. Localizing a commercial application is not simply writing some JSON files and letting the application use them. Those are datasets that need to be stored and tracked in a system so that they can be referenced in the future or kept under change control. After all, you need to be thinking of the future savings and benefits of having a managed system for translations.

If you are looking a solid, reliable and developer friendly TMS, consider giving Phrase a try. It offers all the good stuff that your project team will need for working with translations. For example, it has a really well-documented API and a CLI tool that works like Git. You can pull and push translation keys to the cloud and manage them via ITS Dashboard. It also supports tons of formats for any kind of framework. Working with it means that you never have to worry about missing keys or any impediments in your translation workflow.

Install a Library of Your Choice

It’s now time to choose a suitable i18n library. Generally, here we have to evaluate based on several criteria. For example, we can assess how easy it is to add the library to the existing code, how efficient it is to run, if there is community support or if it offers support for plurals and additional context.  We also need to change the user locale while maintaining a good SEO strategy, for example, building semantic links and ideally making the translations available at runtime for better flexibility. We suggest taking your time to try out all the libraries as proof of concepts to see how they fit into your workflow.


Finally, you need to push the button and start adding localized content. At this stage, it’s important to work with automation to remove any need for manual tasks. For example, using the Phrase Strings API with the provided library of choice might be the best option, as you won’t have to write error-prone bash scripts. You can add CI/CD pipeline steps to automatically synchronize any translations from the cloud without even touching the command line. This will give you greatest flexibility possible, and greatly simplify your everyday operations.

Wrapping It Up

Preparing an app for localization is not an intimidating process. It involves methodical and careful steps to ensure that we have all the necessary translation services, tools and automated tasks in place before we integrate them. After all, the improvement of each product is in our hands, and we have a responsibility to deliver the best relevant content for our customers.

Theo Despoudis

The author

Theo Despoudis

Theo Despoudis is a Senior Software Engineer, experienced mentor, and part of the Phrase Strings Content Team. Interested in open source architectures, cloud computing, best practices, and functional programming, he occasionally contributes to several publishing platforms and enjoys taking digital projects from inspiration to reality.

Stay informed

Subscribe to receive all the latest updates from Gengo in your inbox.

Translator Resources [EN]

Get the leads of users from translator resources page.

  • This field is for validation purposes and should be left unchanged.

Business Resources

Discover everything you need to know about going global.

Translator Resource Page

Discover everything you need to know about translating with Gengo.

Translator Forum