Translating your product into multiple languages

Presenting your product to different audiences in different languages is very challenging. Over the years I've tried different approaches, but the one problem in common for all those approaches is the maintenance of the translations, is just impossible to keep track of all the changes over time.

In this post, I will explain the different attempts to solve this problem and will show you what has worked for me.

Loading JSON files on demand

The first and most popular approach when it comes to translations is to have every single text in your app in a JSON file, then in your code, you will reference the text using a key or an ID.

Each JSON file will contain the same keys but the texts will be translated to the language you want to support, English, Spanish, Japanese, and so on. The file might look something like this:

{
  "home.welcome": "¡Bienvenido!",
  "home.music.recommendations": "Recomendaciones"
}

Then in your code you will dinamically load the JSON based on the user preferences and use the keys like this:

<h1>{translate('home.welcome')}</h1>
<h3>{translate('home.music.recommendations')}</h3>

The translate function will take the key and will return the right text.

While this works well, the main problem is that you will have several gigantic files with all the translations in a single place, however, you have no idea if a key is being used in the code.

In addition to that, a key might be used in several places, therefore removing one of them will potentially remove it from unwanted places.

This approach is best used in SPAs, I wouldn't recommend it to be used in a blog or a landing page, but rather in a mobile or web app that doesn't require to be indexed by search engines.

Building different version

The idea with this approach is to build the app for each individual language you want to support. And then you will redirect the user to the right translation from your server.

You will still have your gigantic file with all the texts for each language, but at build time you are going to generate several JavaScript bundles, one for each translation, for example:

/i18n
  - en.json
  - es.json
  - jp.json
/src
/build
  - app.en.js
  - app.es.js
  - app.jp.js

Then your server will decide based on user preferences which bundle to load at runtime. This approach has a few variants, where you might also generate the HTML that loads the right bundle and then just redirects the user to the right index file.

This approach has the same problem as the previous one, it's impossible to know the keys that are being used and removing a key might also remove keys from places where you don't want to.

You can also generate translated HTML pages and deploy these pages to different subdomains, one for each language. Then you can redirect the user to a different subdomain depending on their preferences. This is ideal for SEO and for indexing your content by search engines.

Solving the maintenance problem

As you noticed, a common problem in both approaches is the gigantic files we will have for each language, it's impossible to know which keys are in use and which ones are not.

To solve this problem we should automate the process of looking at the source code and find those keys that are not in use, while we could build our own tool for the job I'd rather use something that works, luckly Tomáš Ehrlich has been working on an awesome project called LinguiJS!

I've been using this library for the last two years and I really won't go back to anything else. It comes with a command-line program where you can manage in an automated way several tasks such as adding new languages, extracting keys from the source code, deprecating unused keys and building your i18n files for you.

I will write more about this library in the coming posts, but you should start using this tool now! The documentation is awesome, with plenty of examples for different libraries, whether you are using React, VueJS, Angular or even pure JavaScript/Typescript projects.

That's all folks! If you enjoyed this post consider subscribing to the newsletter to get notified when a new post gets published!

Happy Coding!