Internationalization

Rico Suter edited this page Dec 5, 2015 · 15 revisions

To translate an HTML element, simply use the vs-translate (or data-translate) attribute on the element. The framework will automatically look up the specified key in the language file of the view's package and the current language and set the innerHTML of the element.

A part of the view myPackage/views/MySampleView.html:

<span vs-translate="myText"></span>

This is the same as writing:

{{translate('myText')}}

To pass a translated string into a view, use the getString() method:

<vs-my-view my-text="{translate('myText')}" />

The content of the file myPackage/languages/en.json:

{
	"myText": "Sample text in English", 
}

Methods for implementing multilingual applications:

  • visto.setLanguage(language, availableLanguages = null, updateBindings = true)
    • Sets the available languages and the current language to a specific value
  • visto.setUserLanguage(availableLanguages = null, updateBindings = true)
    • Sets the available languages and selects the best language using the browser settings
  • visto.getString
    • Get translated string of the current language
  • getString (in ViewBase or ViewModel):
    • Get translated string of the current language from the view or view model's package (recommended over visto.getString())

The getString() method

There are two getString() method locations: On the view or view model class and the visto object. It is recommended to use the getString() method of the view or view models class, because it loads a string from the same package and thus package renamings do not cause problems. However if you need translated strings in other locations (e.g. a domain class) you have to use the visto object's getString() method.

The getString() method directly returns the translated string if it is already loaded. All language strings for the same package as the view or view models are already loaded and you don't have to use the callback.

On the view or view model class

To load a translated string in your view or view model class, simply use the getString() method of the super class:

// Code in methods of view or view model classes: 
var str = this.getString("myStringKey"); 
// The key myStringKey is looked up in the correct language file 
// of the view or view model's package

If you manually use translated strings you may have to listen to language changes to update the GUI manually with the language strings for another language. Use the "language" observable of the visto module to listen to language changes.

On the visto object

import visto = module("libs/visto");
import package = module("module");

visto.getString("myStringKey", package, (myString) => { 
	/* TODO: use loaded string */ 
}); 

The second parameter package is required to inform the method from which package the string has to be loaded. Unfortunately it is not possible to retrieve this information automatically in the getString() method. It is recommended to use the imported package object instead of a hard-coded package name - this way it is possible to rename the package without complications (the correct package is automatically identified by the getString() method).

Translate KnockoutJS bindings

Sometimes you need to translate values of a binding which is defined in HTML. One example is the "optionsCaption" property for the "options" binding, which shows a combobox caption. The following HTML code shows how to translate the property:

<select vs-options="{items}" vs-options-caption="{ $root.getString('labelSelection') }" />

Note: $root is the current view model and getString() returns a string from the same package as the view model. The above tag can also be written as:

<select data-bind="options: items, optionsCaption: $root.getString('labelSelection')" />

Notification if user changes the language

Use the following code to get notified when the language changed:

import visto = require("libs/visto");

...

initialize() {
	this.subscribe(visto.language, () => {
		// TODO: Implement your language-has-changed logic
	}
}

Replace string loading method

TODO

visto.getLanguageStrings = function (packageName, language, completed) {
	...
	completed({ "key1": "value1", "key2": "value2" });
}