Hero image for Localization

Localization is implemented in all projects regardless of the number of supported locales. This way, adding an extra locale (e.g. th_TH) will not cause any difficulty in the future.


Creating and maintaining translations can be a very tedious and manual process — think spreadsheets nightmares 😱. In addition, external stakeholders usually have the responsibility of translating the content from English to other languages. Therefore, prefer using third-party services like Phrase to manage localization strings.

The process usually involves the following steps:

  1. Developers push new localization keys or remove deprecated keys.
  2. External stakeholders - i.e. the client, translate the content.
  3. Developers pull the translated content into the project. This step often happens at build time (mobile application) or upon deployment (web application).

The process to push/pull localization keys is done via a CLI tool. It’s important to automate this process as much as possible.

An Example of Workflow

When using a translation tool such as Phrase, the following workflow is recommended. Like any solution, there are considerations and trade-offs that every developer must know.


An example of workflow to integrate Phrase

This workflow is available in the Lucid app.


The workflow above integrates the following considerations:

  • It removes the conflicts of newly added translations by only pushing translations from the shared branches — i.e. main or develop. Pushing from feature branches might create conflicts. For example, if feature A pushes its new translations, and later, feature B does the same: the translations from feature A might be removed from Phrase. If some translation work has started for feature A, it might also have been lost in this event.
  • Developers are not waiting for translations to work, so there is no bottleneck.
  • Pushing translations (i.e. new translation keys from developers) is automatic — this minimizes the risk of “forgotten push” and assures translators can do their work at the earliest, before the deployment into production.
  • Pulling translations is automatic and occurs just before building/deploying the app — this ensures the app is deployed with the latest translations.


This workflow includes trade-offs that developers need to know and carefully consider:

  • When a translation key should be changed, developers cannot simply change the key in the yml files. Instead, they need to add a new key, deploy the application, and ensure translators have moved all translations to the new key. Only then can the developers remove the deprecated key from the yml files.
  • When a translation key should be removed, developers first have to ensure the key is not being used in the application in any environment — i.e. production, staging, …
  • After a while, developers might have an outdated version of their local translations, for that, they can perform a manual pull from time to time, and persist it in the source code. This will not impact the deployed applications but it can ease the development and local testing activities.
  • Both the staging and production environments use the same translations. Pros: Translators do not have to manage two working spaces, there is no duplicated work and fewer opportunities for mistakes. Cons: Renaming or deleting a key requires the developers to apply a depreciation process. Such a manual process is a door for mistakes.