...
Language Files
Your app can include multiple language/locale-based string files. Each file should be included in your app.zip file and must be named in this way:
| No Format |
|---|
strings-[language]_[locale].js strings-es_mx.js |
Each file exports a 'keys' object of key-value pairs that are a language key and a language string. The values are mapped to arrays, which can (optionally) contain singular and pluralized versions of the string. For example:
| Code Block | ||
|---|---|---|
| ||
exports.keys = {
'TRANS_KEY_FOO' : ['Foo translation string.'],
'TRANS_KEY_BAR' : ['I have %s banana', 'I have %s bananas']
}; |
Using the Language APIs
In your application, when you want to display a string, do not put the language string in the app. Instead, pass the language key to the translator. The phone uses the correct file, finds the string, and displays it to the user.
The phone's chosen localization setting determines which language file the phone uses. However, if the app.zip does not include a language file for the chosen language, the phone uses the en_us language file or whichever you have indicated by the defaultLangLocale parameter you use when you initialize the app (app.init).
Using app.t is the preferred prefered way to utilize translation.
| Code Block | ||
|---|---|---|
| ||
/* For the purpose of this example, lets assume we have included a strings-en_us.js file in our package and it looks like this. This covers each combination of ways the translation library can be used. exports.keys = { "T_HELLO_WORLD" : ["Hello World"], "T_MY_NAME_IS" : ['My Name is %s"], "T_DOG" : ["Dog", "Dogs"], "T_PERSON_PPL" : ["I employ %s person", "I employ %s people."], "T_MY_ADDRESS" : ["My address is %s; %s, %s %s"] }; */
app.t("T_HELLO_WORLD"); // returns "Hello World"
app.t("T_MY_NAME_IS", ["Ryan"]); // returns "My Name is Ryan"
app.t("T_DOG", [], 1); // returns "Dog"
app.t("T_DOG", [], 2); // returns "Dogs"
app.t("T_PERSON_PPL", [1], 1); // returns "I employ 1 person."
app.t("T_PERSON_PPL", [3], 3); // returns "I employ 3 people."
app.t("T_MY_ADDRESS". ["12 Brown St.", "San Diego", "CA", "91211"]); // returns "My address is 12 Brown St.; San Diego, CA 91211" |
However, you can create your own Language object object and use its translate its translate method.
| Code Block | ||
|---|---|---|
| ||
/* Let's assume we have two string files for our app and they look like the following. [strings-en_us.js] exports.keys = { 'T_MY_APP' : 'My App', 'T_SETTINGS' : 'Settings' 'T_HAVE_DOGS' : ['I have %s dog', 'I have %s dogs'] }; [string-es_mx.js] exports.keys = { 'T_MY_APP' : 'Mi aplicación', 'T_HAVE_DOGS' : ['Tengo un perro', ' Tengo %s perros'] }; /* instantiate Language object set to es_mx (Spanish/Mexico) with a default of en_us (English/USA). If a key is missing from es_mx, the library will try to find it in the default language's strings file. */
var langObj = new Language({'langLocale' : 'es_mx', 'defaultLangLocale' : 'en_us'});
var str = langObj.translate({'key' : 'T_APP_TITLE'}); // returns "Mi aplicación"
var str2 = langObj.translate({'key' : 'T_SETTINGS'}); // returns "Settings" because the key does not exist in the es_mx file
var str3 = langObj.translate({'key' : 'T_HAVE_DOGS', 'count' : 4, 'vars' : ['4']}); //returns Tengo 4 perros |