Internationalization

Translate HTML elements

To translate a HTML element simply use the 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 to the translated text.

A part of the view "myPackage/views/SampleView.html":

<li><a data-bind="click: openLink" data-translate="linkSample" href="#"></a></li>

The file "myPackage/languages/en.json":

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

Methods

  • 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 on view or view model: 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 are not a problem. 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 (if accessing multiple strings, it returns the first value). 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

// 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.

Signature:

getString(key: string): string;

On the visto object

define(["exports", "libs/visto", "module"], function (exports, visto, mod) {
	...
	visto.getString("myStringKey", mod, function(myString) { 
		/* TODO: use loaded string */ 
	}); 
	
	visto.getString(["myStringKey1", "myStringKey2"], mod, function(myString1?, myStr2?) { 
		/* TODO: use loaded strings */ 
	}); 
	...
});

TypeScript:

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

visto.getString(["myStringKey1", "myStringKey2"], mod, (myString1, myString2) => { 
	/* TODO: use loaded strings */ 
}); 

The second parameter (module) 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 module 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).

Signatures:

getString(key: string, path?: Module, completed?: (value: string) => void ): string;
getString(key: string, path?: string, completed?: (value: string) => void ): string;
getString(key: string[], path?: Module, completed?: (...value: string[]) => void ): string;
getString(key: string[], path?: string, completed?: (...value: string[]) => void ): string;

Translate KnockoutJS bindings

Sometimes you need to translate bindings which are 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 data-bind="options: items, optionsCaption: $root.getString('labelSelection')" />

Note: $root is the current view model and getString() returns a string from the same package as the view model.

Notification if user changes the language

Use the following JavaScript code:

MyViewModel.prototype.initialize = function() {
	this.subscribe(this.viewManager.language, function () {
		// implement your language-has-changed logic
	}
}

Last edited Dec 14, 2013 at 6:34 PM by rsuter, version 35

Comments

No comments yet.