Kogito Tooling i18n

We’re happy to announce that Kogito Tooling is ready to be internationalized! This means that it will be possible to change the locale and access translations of the Kogito Tooling Channels.

To enable this new feature, we developed an i18n type-safe library with React usability in mind, which allows simple and easy integration with an already existing project. This article will explain our choices and go through all the minimal settings required to use it.

Integration

As mentioned, this is a library to be used on a React TypeScript project, so first of all, it’s necessary to create a dictionary type that is going to be used by our default locale. This is important, so our application doesn’t have any missing strings. The reference dictionary interface should extend the ReferenceDictionary<D> type.

Notice how we can only have string or functions receiving and returning strings. This makes the dictionaries implementations clean without any conversations to strings, or even worse, dangerous concatenations of non-string objects.

With our reference dictionary interface ready, we need to create our reference dictionary object which implements its interface.

The bold() function is a native JS feature, and will wrap the ‘name’ string in <b> HTML tags.

The application must have only one ReferenceDictionary object. All other dictionaries are going to be a translated version of the reference dictionary. With that in mind, the translated dictionaries should implement the TranslatedDictionary<D> type. The TranslatedDictionary<D> is a type with the same keys and types of the ReferenceDictionary<D>, but they’re all optional.

In this example, the ‘welcome’ key isn’t provided. When the user eventually selects the Portuguese dictionary, the ‘welcome’ key will fall back to the English dictionary because it is our reference dictionary.

Having optional keys is important for partial translations. It can be very difficult to translate an application to a whole other language. More than that, programmers won’t speak every language supported by the application, so upon creation of new keys, it’s important that the programmer is not required to translate them, leaving it for a translator to do later.

Now, it’s necessary to give the application access to these dictionaries. For that, we have the I18nDictionariesProvider React component, and it’s necessary to initialize it with a few props at the top level of our app.

The I18nDictionariesProvider component will add the dictionaries to the application context. When a dictionary is selected, it will be merged with the reference dictionary, creating a new dictionary object. In this process, all existing keys on the translated dictionary will override the reference keys, and this way, a new dictionary will be formed without any missing key. To illustrate this behavior, if the Portuguese dictionary is selected, the resultant dictionary object would be:

After the I18nDictionariesProvider component is ready, it’s possible to use the dictionaries on the children components with the useContext hook (useContext(myI18nCtx)) or the context provider (myI18nCtx.Provider), which gives access to the current locale, a function to change the locale (setLocale), and the object (i18n) with the current actual dictionary.

In this example we use an I18nHtml component. Remember the ‘welcome’ string with <b> tags that were added by the bold() function? We utilize this component because it can render a string with HTML tags using the dangerouslySetInnerHTML prop. It’s not recommended to use that with interpolated translation keys.

Wrapping up

This library solved the i18n problem for our needs at the moment, and if you think you have a similar use-case, you can use our i18n library too! All you have to do is install it using npm or yarn, and just follow the above steps to integrate it!

Installation:

npm install @kogito-tooling/i18n or yarn add @kogito-tooling/i18n

Stay tuned for more updates on Kogito Tooling! Don’t forget to try our VS Code and Chrome extensions. An online version of the editors is available at https://kiegroup.github.io/kogito-online/#/ . You can also download our Desktop app on our GitHub release page.