Translating Your App

Internationalization, Localization, I18n, L12n, or translating your app to different languages. VoK provides basic support for localizing of your app. It provides the vt map which simply translates keys to strings. For example:

textField(vt["newuser.name"]) {
    bind(binder).bind(Person::name)
}
textField(vt["newuser.surname"]) {
    bind(binder).bind(Person::surname)
}

vt stands for Vok-Translate and was chosen because it’s much easier to type in on the keyboard than i18n.

In order to provide values for the localization keys, you need to create a so-called resource bundle (a map of keys to values) named VokMessages.properties in the src/main/resources/ folder of your app. An example of such file would be

newuser.name=Name:
newuser.surname=Surname:

To provide localized resources e.g. for your Japanese customers, just create another file named VokMessages_ja.properties (also in the src/main/resources/) folder, with the following contents:

newuser.name=名
newuser.surname=姓

Now your Japanese visitors will be welcomed by a familiar Japanese text.

Note: VoK localization support uses Java ResourceBundles underneath. Please consult About the ResourceBundles for information on how to name the VokMessages_*.properties bundles to provide a proper localization for particular country.

It is always good to keep the VokMessages.properties file. That’s a so-called fallback file - if a resource bundle for a particular language doesn’t exist, the fallback bundle will be loaded. You typically write youor fallback bundle in English, but you may also use other language, depending on the target audience of your app.

Note: if the key doesn’t exist in the bundle, it is wrapped in !{}! and returned. For example, vk["newform.nonexistent"] will return "!{newform.nonexistent}!"

How The Language Is Selected

The vt function retrieves the proper localization map based on the locale of the current UI: UI.getCurrent().locale.

Note: the function fails if there is no UI (the function is not called from Vaadin’s UI thread). You therefore can’t call it from e.g. a background thread.

To configure the current user locale, just compute a proper locale based on the steps below and then call UI.setLocale. With Vaadin 8 app, you can set the locale directly in the UI.init method; with Vaadin 10 you can set the locale also in UI.init method or in the constructor of your root layout class.

As a first step, you can check whether the user has configured his language in his settings. Just get the current user from the session, then do a database lookup for the user settings and retrieve the locale. If it’s not null, use it.
If user haven’t configured his locale or your app doesn’t support this kind of functionality, fall back and simply poll the browser for the WebBrowser.locale: Vaadin 8: Page.getCurrent().webBrowser.locale, Vaadin 10: VaadinSession.getCurrent().browser.locale.
If the browser provided null locale, fall back to Locale.ENGLISH.
Set the value computed by the steps above to the UI: UI.setLocale

Standard Bundle

In order to provide localization for filter components, Vaadin on Kotlin provides a standard bundle placed in the com.github.vok package. This bundle is internal and shouldn’t be overridden. It provides the following defaults:

filter.all=All
filter.clear=Clear
filter.ok=Ok
filter.set=Set
filter.atleast=at least
filter.atmost=at most

You can add these definitions into your own VokMessages.properties bundle - they will then be preferred over the default ones. This way, you can provide alternative translations (or additional translations) for the filter components.

Customized Solutions

The built-in VoK localization support may not be powerful enough for your needs. VoK doesn’t limit you in this regard: you are free to use a customized solution based on ResourceBundles (the typical solution for a JVM-based apps), or you can even roll your own completely custom solution for translating strings.