Why you need to think about internationalization before you start developing software

Starting a new project is exciting. There’s so much to think about — like how to make it scalable, reliable, maintainable, and secure. With so many moving parts to juggle, internationalization — or the process of designing software so it can be translated into many languages — is often not your first priority. 

Today, Mattermost is shipped in 21 languages. The entire Mattermost project contains more than 64,000 words in 9,500 sentences. That is about the size of a 140-page novel. 

So, when it comes to internationalization, we have some experience, and we’d love to share it with you. 

If you’re interested in internationalizing your software, it’s best to make that decision at the start of the project. With that in mind, here are some best practices to consider when it comes to internationalizing your next software product.

Use variables

Our first golden tip: Use variables for things that never should be translated. 

Mattermost contains a lot of links that lead the user to more in-depth documentation. Recently, we replaced each link with a variable. As we decided to reorganize our documentation site to make it even better for Mattermost users, all the links had to be modified. This meant that every translator had to retranslate strings containing a link and copy-paste the correct link into it. 

At this point, we decided to change all the URLs to variables. That way, if we ever needed to change our documentation or correct a link to an external site, it would only require a code change — not time and effort from our translators. 

Mattermost has three products: Channels, Boards, and Playbooks. Since these are product names, they shouldn’t be translated. But when we are referring to channels, boards, and playbooks more generally, we need to translate these words. 

It’s not always clear to translators when to translate or not. The plan is to put our product names in a variable, too, so that translators don’t need to worry anymore if it should be translated or not. That way, if we ever changed our product names, the localization process would be much easier.

Provide context

Our second golden tip to ease your internationalization is to provide as much context as you can to your translators. Sometimes sentences are very clear. But sometimes you only have a single word to translate, like Count. This can be a noun (with two totally different meanings) or a verb, which is translated differently in many languages. 

When you give each string a unique key that tells something where and how the string is used, you’re providing context to your translators. In our example, the key is Calculations.Options.count.displayName. So, we can guess it’s a verb. 

At the moment, we’re researching how to provide the screenshots that the QA department is using for their tests to our translators. This would be the perfect solution for giving context to our translators.

Here’s another small tip that can have a large impact: Don’t split a sentence into multiple strings. From the developer’s standpoint, splitting a sentence into three strings seems to make sense. You have the good layout you want without much hassle. 

But there are three things that can go wrong here:

1. You can’t be sure that your three strings will be presented to your translator in the same order. As such, the translator can be given the middle of a sentence without any additional context.
2. Every language has its own grammar and syntax — which means the order of the words can be quite different in different languages. As a result, concatenating three strings into one sentence may end up sounding like Yoda from Star Wars talking to your users.
3. Some languages, like Portuguese and French, are more verbose than English. So your layout can break in a more verbose language. The same idea holds true for languages that are more compact than English, like Japanese and Chinese.

Embrace cultural differences

There are differences in verbosity between languages. But there are differences beyond that, too. 

At Mattermost, we use a friendly, less formal tone in the product, and we want our translations to have that same tone. But some languages have to keep using the more formal form — like French, Hungarian, and Japanese. In these languages, using a more informal form would sound disrespectful or childish to the end user. But even a formal form can still be friendly and personal.

We even have dialects in our Mattermost translations, including Brazilian-Portuguese and Australian-English. We also have our first right-to-left language, Persian, in beta at this moment.

Through the internationalization process, your product becomes more inclusive, and more folks are able to use it in their native language — which makes the effort of translating your product worthwhile.

Do you want to contribute to the translations of Mattermost?

Are you interested in helping translate Mattermost into new languages? Getting involved is easy: Just create an account at our translation server and start translating. For more information on the translation process, check out the Mattermost handbook. While you’re at it, join our localization channel at our community server and say hello!