vok

Writing full-stack statically-typed web apps on JVM can't get any simpler

This project is maintained by mvysny

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)
}

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.

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.