Localization

Appcelerator provides a simple Localization framework that makes it easy to externalize client-side text like field labels, user messages, and button text. The following sections describe the key concepts behind our Localization framework.

Setting the Locale

By default, the user’s machine’s locale will automatically be set to the appropriate language. Localized applications can also programmatically set the specific locale to use by setting the following Javascript variable:

<script>
	Appcelerator.Localization.currentLanguage = "en";
</script>

This variable tells Appcelerator which localization bundle to use. You can also use a specific ISO language identifier such as “en-US” or “en-UK”.

Creating Localized Bundles

First, you need to create your key/value pair mappings. We use a Javascript variable to store each key/value pair. Here’s an example:

var en_lang_bundle = 
{
	"username.label": "Enter username:",
	"password.label": "Enter password",

	"fruit.dropdown":
	[
		{id:"",value:"select a fruit"},
		{id:"1",value:"orange"},
		{id:"2",value:"apple"},
		{id:"3",value:"banana"}
	]
}

The example above shows how to do simple key/value pair definitions, and the “fruit.dropdown” definition shows how you can localize SELECT values that are not stored in the database.

Note: it's important that the last defined key/value pair does not have a comma at the end. It will break in IE if it does. The same is true for the last value in an array definition like "fruit.dropdown", the last key/value cannot have a comma at the end

Registering Localized Bundles

Once you have a language bundle defined, you need to register it with Appcelerator. We provide a Javascript function that makes this task easy. Here’s an example:

<script>
Appcelerator.Localization.addLanguageBundle("en",English",$H(en_lang_bundle));
</script>

The function above takes three arguments: the locale, a display name, and a hash of your language bundle variable defined in the “Creating Language Bundles” section above. You need to register each of your locale-specific language bundles with Appcelerator using the above function.

Referencing “Key/Value” Pairs in your Application

Once you have completed the above, you are ready to localize your application. Appcelerator provides a few techniques for doing this.

First, you can use the langid attribute on an element to set the localized value. Here’s an example:

<div id="username_label" class="label" langid="username.label"></div>

In the example above, the DIVs value will be set to “Enter username:” (based on the bundle defined above). The langid attribute should be mapped to the “key” in your bundle.

You can also programmatically set localized values using our Localization Javascript API. Here’s an example:

<app:script>
	$("username_label").innerHTML = 
		Appcelerator.Localization.get("username.label","username","en");
</app:script>

In the example above, we set our “username_label” DIV to the value of the key “username.label”. We also specified a default value in case the key is not found. Finally, we specified the locale. This could also be specified using the “Appcelerator.Localization.currentLanguage” variable if you set it previously in your application.