Internationalization

Internationalization, often abbreviated as i18n, is the process of designing and developing a product in a way that removes barriers to its use in different locales. It involves ensuring that the software can handle different languages, character sets, and cultural conventions (like date and time formats) without modification. Essentially, internationalization prepares the software for localization.

This guide briefs you on how to implement internationalization in Rocket.Chat.

When you're building for Rocket.Chat, you can add text to our files. Later, our community will translate this text into different languages.

• Tools used: In Rocket.Chat, internationalization is implemented using the TAP:i18n meteor package, and managing contributions from the translator's community is done using lingohub.

• Adding strings to the translation files: To translate a string in Rocket.Chat, you'll first need to create a key, which serves as the identifier for the string you wish to translate. For instance, the string This room is read-only should have the key room_is_read_only.

  • It's important to remember that keys should replace spaces with underscores (_) and be written in English, as this is the language used for Rocket.Chat's code. The key/value pair would then look like this: "room_is_read_only:"This room is read-only". You can also include placeholders in your strings, which allow for dynamic information changes when the i18n method is invoked.

  • A placeholder is enclosed by two double underscores (__ __). For example,"Conversation_closed": "Conversation closed: __comment__." where __comment__ can be substituted with any string provided in the parameters. Next, you'll need to add this key to the appropriate i18n.json file located in the i18n folder. Once your pull request is merged, our contributors at LingoHub will be alerted to the new string and will begin translating it.

• Using Translated Strings on the code: Having added your strings to the translation files, it's now time to utilize them in your code! When working with a .js file, you can employ the global method TAPi18n.__(). The parameters for this method can vary based on where it's being called from. If invoked from Rocket.Chat's back-end, you'll need to specify a language, typically derived from a user's object. The method would then appear as follows: TAPi18n.__('YOUR_KEY_HERE', {}, user.language).

  • You can also pass parameters in the second argument to substitute placeholders in the translated strings. However, if you're calling from the front-end, you can simply use TAPi18n.__('YOUR_KEY_HERE', {}), which will translate the selected string into the user's currently chosen language. If the selected key isn't found in the corresponding .i18n.json file, it defaults to English. If no key is found at all, the method displays the key inserted as a string.

  • When working with a .html file, you can simply enclose the string with {{ "{{_ " }}}} like so: {{ "{{_ YOUR_KEY_HERE" }}}}. This works similarly to the method mentioned above, with the added convenience of being able to add it directly to the .html file. In some instances, you may encounter methods that require an object with an i18nLabel or i18nDescription. In these cases, you only need to provide the key of the string, and the method will handle the rest.

Understanding and implementing internationalization in Rocket.Chat is essential for developers aiming to create a user-friendly and globally accessible application. By leveraging the TAPi18n.__() method, developers can ensure that their software communicates effectively with users in their preferred language, thereby enhancing the overall user experience.