i18n Multitenancy: Customer-Specific Translations

AuthorMáximo Mussini
·3 min read

When providing services to different companies or customers with the same software, such as enterprise or white-label applications, it's not unusual that each customer uses different terminology for certain concepts within the application.

While they might be similar in terms of operations and transactions, different domains will often use different jargon, and as a result, prefer different names for a given feature or aspect of an application.

For example, a concept that in our application is "person", might be referred to as "user", "customer", or "employee", based on the language of their specific domain, or when using their in-house terminology.

Using the same terms than our users in their every day routine can help to make the software feel more natural and easier to grasp, lowering the adoption barrier and reducing the resistance to change in large organizations.

...fits right in with our usual flow.

Using i18n fallbacks 🌎

Fortunately, we can easily accomplish this by leveraging the existing i18n tools that are available in most platforms.

Just like we might allow a customer to switch between American or British variants of the English language (en-US and en-UK), we can create additional language-variants or locales for each customer or domain (en-LAW):

  customer: client

We can then use i18n fallbacks, so that any keys that are not defined in our domain-specific locale fall back to the usual definition in the language.

In the example above, any users that have the LAW translation preset assigned would see "client", but other users might see "customer".

This allows us to achieve a nice balance between configurability and productivity.

By managing these text overrides within the translation engine, it becomes almost effortless to dynamically customize the language used in the app.

Dictionaries for different domains or specific customers can be added with ease, and it becomes easier to test all the different combinations in the application.

A solution for Ruby apps 💎

I have wrapped a Ruby solution as the i18n_multitenant gem. Please check the readme for a more thorough explanation of how language variants are used, and a few examples on how to organize translations in order to effectively implement the approach.

What about translations in the browser?

For single-page applications or other apps where it's desirable to perform the translations in the browser, we can use a library such as i18n-js.

It's possible to configure it to use fallbacks, allowing us to reuse the same translation files in the JS world.


i18n fallbacks provide a simple way to adapt the terminology used in our software based on different domains and users needs, making it feel more familiar and easier to use without restricting the software's flexibility.