2019-04-22 23:56 — By Erik van Eykelen

Use a Translation System


Let’s start by making a bold claim: the quality of our translation process is a yardstick for the quality of other product development processes such as planning, designing, coding, and testing. If you suck at translations, there’s a fair chance you can improve (less visible) processes (e.g. planning, or testing) behind the delivery of your product or service.

Translating software is hard. A couple of reasons why:

  • Good translations start by having an excellent source in the form of the product’s default language. This requires having a skilled text writer who works on this foundation semi full-time.
  • Good translations require razor-sharp clarity about the context of a word or sentence. This can only be achieved by providing your translators detailed screenshots highlighting sentences that must be translated.
  • Good translations need good translators. Preferably even two translators per language who check each other’s work.
  • Good translations are kept consistent by using a central “translation memory” which contains standard phrases and terms used by the product. This ensures long-term (counted in years) consistency.
  • Good translations need sufficient time to make them awesome. Having to scramble at the last minute to translate hundreds of words, in multiple languages, is not OK. Try to work on translations regularly to prevent the batch from growing to an unwieldy size.
  • Good translations require good software tools, starting with a web-based collaboration tool to work on translations with multiple translators, and (command-line) tools to push and pull translations between code and translation system.
  • Good translations require a single person who makes the final decision on wording, terms, phrases, jargon, active/passive form, grammar, and spelling. Stop questioning this person, accept the decisions, and show respect for the difficult task this person has to carry out. Making great software translations is a really difficult task.

Who does what

The translation process involves several roles:

  • Developers have to ensure every word (called strings in developer parlance) is placed in a resource file instead of embedding texts in code. This is a well-understood process by most developers. Every programming language and framework offers support for a number of different localization (abbreviated as “l10n”) systems. Examples are gettext and .NET resources files.
  • Developers, Tech Leads, or Product Owners must provide screenshots. It doesn’t matter who takes care of screenshots, as long as it happens.
  • Tech Leads & Product Owners must ensure that translations are part of the “Definition of Done” of each Pull Request. If translations are not ready then a feature, change, or bug fix is not ready for merging either.
  • The Translation Manager (TM) keeps an eye on Pull Requests which require translations and ensures missing strings are synced with the central translation system. Preferably developers perform this task on behalf of the TM at the same time they push the PR for review. The TM reviews the quality of the base language before engaging the translators. The TM keeps an eye on a quick turn-around for all the translations (less than 48 hours preferably). As soon as translations are ready the TM notifies the PR author that the translations can be pulled from the central translation system. Performing this pull updates the resource files in the codebase. The PR is subsequently updated for final review and merging.
  • Customers should have an easy way to submit translation issues by providing a simple link or button (e.g. in the footer of the app’s web pages). Clicking this link opens a small popup in which the error can be reported. The user’s feedback, along with additional data such as the page URL, is submitted to, for instance, Zendesk.


It’s important to split the total body of translation strings into separate modules because it enables developers and translators to work on a relatively small body of translations (per module) which is better than having to wade through thousands of translation keys lacking any context or meaning due to the sheer volume.

Translation modules should follow the modularization of the software product that is being translated. For example, if your app consists of an admin module, dashboard, profile page, and work spaces then the same modules (and naming) should be applied to the translation modules.

While it is tempting to create a set of general translations (such as “OK” and “Cancel”) I generally advise against such a shared module because a) it’s hard for developers to know exactly when they should (not) use a phrase from this general module, and b) the generalization of words should be managed by a translation memory and not by a surrogate in the form of such a shared module. Optimize for a great translation memory, not for small resource files.

Translation management system

The translation management system I like best at the moment is Lokalise (I have no affiliation with them).

Lokalise offers:

  • Support for gettext, .NET resources (resx), iOS/Android resources, and many other formats.
  • Support for singular/plural translations.
  • Versioning and branching.
  • A command line tool.
  • Support for screenshots (for context)
  • A translator “marketplace”
  • Integrations
  • Keyboard shortcuts
  • Fast user interface
  • Responsive support team
  • Rapid pace of innovation

I’ve also used https://phraseapp.com/ in the past, it’s also pretty good (but quite expensive).

Check out my product Operand, a collaborative tool for due diligences, audits, and assessments.