Writing full-stack statically-typed web apps on JVM at its simplest
This project is maintained by mvysny
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 thani18n
.
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 theVokMessages_*.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}!"
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.
WebBrowser.locale
: Vaadin 8: Page.getCurrent().webBrowser.locale
, Vaadin 10: VaadinSession.getCurrent().browser.locale
.null
locale, fall back to Locale.ENGLISH
.UI.setLocale
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.
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.