Localization workflow: best practices

In the localization of any software including websites and web apps, mobile apps, games, IoT and standalone software, there is no continuous, logical document similar to articles and books. Instead, there are hundreds or thousands of words/phrases which by default do not carry implicit context. In addition, they are quite often are simply impossible to translate without knowing some background information. For example, take English words like go, pool, mine, draft — depending on the situation, they have a completely different meaning. This is one of the many reasons why a modern product team should consider using a professional translation management system (TMS) instead of translating localization files straightaway or even worse sending Microsoft Excel/Google Docs sheets to translators.

Other, but not all the benefits coming with a good TMS:

  • developers are totally freed from participating in the process of localization, especially from copying & pasting the translations into the code
  • the process is fully automated and transparent
  • localization files are always consistent — translators cannot break the markup
  • the context of a translation shown to a translator includes screenshots, descriptions, or comments to keys
  • translators can immediately discuss the translation with localization and product managers and other translators in a provided project chat
  • QA specialists may see the live preview on mobile device screen or a browser

There are various approaches to a localization workflow. Still, four important steps remain common:

  1. Uploading or importing the source
  2. Translation
  3. Reviewing (may be omitted in small scale projects)
  4. Delivery of the translated content to end users

A localization process usually involves 4 groups of collaborators:

  • Software developers
  • Localization managers, product owners, product managers, project managers, team leads
  • Translators, copywriters, marketing specialists
  • Reviewers, quality assurance (QA) specialists

Developers come first in most of the cases, as they start by adding string identifiers (called keys or key identifiers or key names) to the code while programming the screens shown to users. It is applicable to any software, be it a mobile app, website, game, smart home or standalone software. Whenever there is a need to display some text to a user, a string identifier is employed.

Localization files contain the mapping between keys and actual translations or translation values. For example, a key identifier on the login button for a website may very well be button.login, while translation values — “Login” for English and “Iniciar sesión” for Spanish.

There are many localization file formats: AppleStrings or XLIFF for iOS, XML for Android, JSON/YAML/PO for Web, etc. These are not plain-text files, and it is hard to understand their structure for a non-technical person.


Localization workflow

1. Supplying the source

Everything starts with the source supplied to a team of translators, be that the initial translation to a new language or a set of new strings that have to be translated.

Initial project set up

In most cases, there are some localization files already (in just the base language or in multiple languages that may be partially or fully translated). It’s a good idea to do the initial project set up using Lokalise web UI (you will be able to automate the upload process later).

Once you create a project, simply drag and drop all the existing localization files at the Uploads page. The system extracts keys and translations from all languages, creates key items in the database and maps relevant language translations to these keys.


Lokalise is a multiplatform system – that means you can store iOS, Android, Web or any other strings together, even if they originally exist in different files and formats. Once you upload it all, the system does the automatic merging for the keys with similar names. There are just several steps to merge all other possible keys using translation matching (see docs). As you merge the keys, they only need to be translated once – the strings get exported to appropriate files with appropriate names depending on the platform.

It is important to understand how keys are tied to platforms and filenames in Lokalise:

  • A key can be assigned to one or multiple platforms.
  • Assigning a key to a platform means including the key in the export routine for the file formats associated with the platform (e.g. if a key is assigned to iOS and Android platforms it would get exported to both .strings and .xml files, but would not go to the .json export).
  • A key can be assigned to one unique filename per each platform.
  • A path may be an integral part of the filename (e.g. locale/en.json and main/en.json are considered two different filenames). It is recommended to omit the path in filename and add it dynamically when generating the bundle.

Change management

Once the project is set up, it’s a good idea to add a little bit of automation and leave the process to translators, reviewers and QA.

Whether these are new features/app screens/web pages that are being added to your app, new keys along with base language translations (or translation prototypes at least) are added by a coder in the process of development.

Option 1 – Uploading the files using CLI tool
As teams start using Lokalise, this is the most popular approach for change management. The CLI tool is a simple wrapper for the API (and it’s open source too). Uploading your files is done by a single command line, here is the example:

lokalise --token <api token> import <project id> --lang_iso en --file strings.xml

By default, Lokalise only adds new keys along with translations found in the files you are uploading. In case you want to overwrite translations that were modified in a local file you are uploading add --replace 1 as a parameter.

Option 2 – Use GitHub/GitLab/Bitbucket integration
Most teams use version control systems like GitHub. Instead of pushing the file changes to both GitHub and Lokalise, you may set up an integration in Lokalise that would automatically fetch the files as soon as developers push the changes to the repository.

Hint – you only need to link base language files when setting up the Github integration. Lokalise will automatically create a pull request with all language file versions as you perform the export.

Make sure to configure the Auto-pull option in GitHub when setting up the integration.

Option 3 – Add new keys in Lokalise directly
Instead of adding keys to your local files and then uploading them to Lokalise it’s a good idea to start adding keys in Lokalise directly. Make sure that “Allow key editing” option is enabled in project settings. Key editor provides several handy options, including the ability to define the key pre-fill field mask – if you are adding multiple keys, like index.welcome, index.button, index.title just set a pre-fill mask to index. so it is automatically added as you hit “Save” and need to add another key.

Option 4 – Use API to create new keys
Yet another option to add new keys to Lokalise as they are added in your backend is using the API. See /string/set method for more information.


The easiest and quickest way to provide translators with a context is using screenshots. Lokalise offers multiple ways of uploading screenshots, including automatic snapping (see In-context editing below), however, the most popular one is the bulk uploading of the image files.

Once the localization files are in place and key/translation pairs are set up, it’s time to upload the images at the Screenshots page. The system automatically performs the OCR (optical character recognition) to identify any textual information and matches that against translations in the base language to make a link between image and keys. In case the OCR could not identify the text (i.e. low contrast images or too small or exotic font is used) it’s a very quick process to make the mappings manually. The connection is many-to-many – each screenshot can be linked to multiple keys and each key can be linked to multiple screenshots.

Screenshots may be organized into logical groups using tags which gives translators even more contextual information while using the Screenshot Filter in the editor.


We are actively working on adding project branching feature (coming Q4 2018) to enable transparent version and branch support for Lokalise. Currently, the options are using tags with version/branch description or even creating a project copy in case of major version update.

2. Translation and reviewing

As the initial set up is done and change management process is clear, it’s time to understand how the actual translation and reviewing process works.

You can invite a team of in-house translators, invite a third party translation agency or use any of the translation partners we have built-in for your convenience (see Using translation providers below).

Besides offering an ultimate toolset for localization process automation, Lokalise comes with a beautiful collaborative editor, comparable to modern professional CAT tools. The editor has two views – a classic bilingual view (where the source is on the left and target is on the right) and a multi-lingual view that shows all language translations simultaneously. The latter is very handy for product/localization managers to see the overall progress of the project. The full feature list of the editor is available in documentation page, we will focus on the main ones.

Lokalise comes with integrated machine translation options (DeepL, Google Translate, Yandex Translate and Microsoft Translator) and a translation memory, that are essential for efficient translation.

You may pre-translate the project using machine translation (use Orders menu on top) or by applying 100% translation memory matches. An alternative approach to pre-translating would be using inline suggestions while translating, thus ensuring better quality and minimizing the number of possible mistakes comparing to bulk pre-translation.


Assuming you’ve set up a team of translators and reviewers (see docs page) and there are new strings uploaded, it’s time to set up a Task.

Tasks may be set up manually by project admins using the web UI or you may use the API to create tasks programmatically (coming with API 2.0 in August 2018).

You need to define task scope (keys that have to be included), languages and assignees. Each assignee gets a notification over e-mail as well as in personal Incoming tasks widget.

Administrators can see task completion progress by language.

As the task is completed (or a language in the task is marked as completed), use project integrations to perform certain actions. You may inform administrators over e-mail, send notification in Slack, create tickets in Trello, create tasks in Jira or send a webhook to your endpoint so it performs the export/starts the delivery process).

Multiple reviewal cycles

In case you need a separate reviewal cycle (or even multiple reviewal cycles by different people), create a chained task for review-only and only include contributors with the Reviewer access as assignees.


There are some projects with hundreds and even thousands of translators. Consider using translation upvoting mechanism in such cases. Translation version with most upvotes (or the one that is reviewed) becomes the “main” one and goes to export.


QA filters

There is an indicator for QA issues in every project. It includes links to filters that show placeholder and HTML mismatches (differences between base language and target languages), spelling and grammar issues (automatic check available in 20+ languages) and a filter to show leading/trailing spaces that may be occasionally left by translators.

In-context editing

We provide a unique option for translators and QA specialists – the in-context editors for web (comes as JavaScript plugin) and mobile (currently available for iOS only). Instead of delivering the localization files back to code, releasing a version with new files in-context editors allow pixel-perfect visual translation experience – proper font, proper place, the good old WYSIWYG.


Besides the actual contextual information like descriptions and screenshots that project admins may provide, Lokalise has a built-in project/key chat with @mentions so translators can discuss the nuances of particular translation approaches in place.

Using translation providers

Missing the in-house translator team? Not a problem – we have three human-powered translation partners at your service, prices starting at $0.07/word. Each of the providers is able to translate about 2000 words/day for each language pair.

Gengo is the most affordable one and as soon as your project is well-prepared in terms of providing screenshots, glossary terms, comments and project brief it is a good choice. The translation jobs are sent to Gengo over API, however, they still include all of the contextual information. Unlike two other providers, Gengo translators would not install your app or deeply read a website, though. It is possible to request corrections from Gengo for 4 days after the translations are completed.

The other providers are Language Inspired and Alconost. Both companies would do the translation work inside the Lokalise environment and dive deeper than Gengo by learning your product by reading a web or downloading an app (if applicable).

3. Delivery of translated content

Once the translation tasks are complete you need to export the content and deliver it to end users. Besides simply downloading the files using the web UI there are several automation options to choose from.

Mobile SDK

Distributing translated strings to your mobile app users has never been easier than with Lokalise mobile SDKs (supported for iOS and Android). Embed the very lightweight SDK by adding just a few lines of code to get the ability to distribute translations to end users over-the-air bypassing AppStore or Google Play release cycle and reviewing. Instantly fix typos, finish translations or play with wording. You can even add new languages on the fly on Android.

CLI tool

The most popular option is to export your localization files using the command line tool. Usually the export is performed at the build process (for production) or prior to build process in case it’s the development environment. Just as with import, that is just one line of code, here is the example:

lokalise --token <api token> export <project id> --type json --unzip_to /var/www/locale

You can fine tune the export, directory structure and set various parameters for filtering of data (see the CLI tool docs).

GitHub/GitLab/Bitbucket integration

In case you have set up a repository integration, Lokalise can create pull requests in order to put translated localization files back into GitHub. Keep in mind that even if you have only linked source files, we can still create commits with all files, so the only thing you will have to do is to merge pull requests. Pull request creation may be triggered using the web interface or the CLI tool.

Amazon S3/Google Cloud Storage

Most modern web frameworks suggest serving the static content like images, css and language files from a CDN. We have created one-click integrations that upload exported files to an Amazon/GCS bucket of your choice.

Related posts

Sign up to our newsletter

Get the latest articles on all things localization and translation management delivered straight to your inbox.

Read also
Localization made easy. Why wait?
The preferred localization tool of 1500+ leading global companies