Adobe

Products

Acrobat

Creative Cloud

Creative Suite

Digital Marketing Suite

Digital Publishing Suite

Elements

Photoshop

Touch Apps

Student and Teacher Editions

More products

Solutions

Creative tools for business

Digital marketing

Digital media

Education

Financial services

Government

Web Experience Management

Building a multilingual HTML-based application

by Jeff Swartz

Modified

9 June 2010

Requirements

Prerequisite knowledge

General experience building HTML-based applications is suggested. For more details on getting started with this Quick Start, refer to Building the Quick Start sample applications with HTML.

Additional Requirements

Adobe AIR SDK

User level

Intermediate

Required products

Adobe AIR

Sample files

The HTML Localization example application demonstrates a number of features of working with the Adobe AIR HTML Localization Framework, including:

Setting up localization bundles to support multiple languages
Reordering the locale chain, based on user interaction, and updating the user interface with the selected locale
Saving and retrieving locale information in a preferences file
Supporting multiple languages in the AIR application installer

Figure 1 shows the HTML Localization example application.

Figure 1. The HTML Localization example application supports multiple languages.

Note: This is an example application provided, as is, for instructional purposes.

This sample application includes the following files:

index.html: The main application content
AIRAliases.js: The AIR JavaScript aliases file
AIRLocalizer.js: The AIR JavaScript aliases file for multilingual applications
application.xml: The AIR application descriptor file that you use to debug and build the application (using ADL and ADT)
style.css: A CSS style sheet used by the application.
locale: A directory containing localization bundle files
icons: A directory of sample AIR icon files

Note: Some of the text files in this application useUTF-8 encoding. Open them in a text editor that supports UTF-8 encoding.

Testing the application

Download and launch the application's installer (HTMLLocalizerSample.air) to install the application. The application is simple. Select the target language from the Choose Language pop-up list and the user interface updates accordingly.

Understanding the code

Note: For more information about using AIR classes, see the Adobe AIR API Reference for HTML Developers. For information on using the AIR HTML Localizer Framework, see the "Localizing AIR applications" chapter in Building Adobe AIR Applications.

Defining resources for different languages

Bundle files define different language versions of strings used by theapplication. These are included in the locale directory of the applicationdirectory. In this directory there are six subdirectories, one for each localesupported by the application: en_gb, en_us, es, fr, jp, ro. These directoriescorrespond to English (U.K.), English (U.S.), Spanish, French,Japanese, and Romanian. A locale can correspond to a language (such asFrench) or to a specific variant of a language (such as U.S. English).

Each directory contains a default.properties file. This file defines stringsfor the language. For example the default.properties file in the locale/en_usdirectory defines strings for U.S. English, and it contains the following:

        title=Sample Multi-language Application
lblCurrentSelectedLanguage=Current language
lblCurrentLanguage=English (U.S.)
lblChangeLanguage=Change language
lblLanguageSettings=Language settings
lblColors=Change colors
btnBlue=Blue
btnRed=Red
btnGreen=Green
btnAbout=About...
description=This is a simple example application that shows how to use the AIR HTML Localization framework.
    

The default.properties file for each locale defines key-value pairs for thatlocale.

Each line of the file assigns a string (to the right of the equal sign) to akey (to the left of the equal sign). For example the string "Change colors" is assigned tothe lblColors key (for U.S.English). The application then uses that string for the innerHTML value of an h1 element which has the local_innerHTML attribute set to "default.lblColors":

<h1 local_innerHTML="default.lblColors" class="optionGroup"></h1>

The application calls the update() method defined in the AIR HTMLLocalizer code. This method updates the h1element (and other elements of the HTML DOM) with the current locale strings. TheAIR HTML Localizer updates an element based on attribute settings defined bythe AIR HTML Localizer code:

An element that has alocal_innerHTML attribute defined as "default.lblColors" will haveits innerHTML value updated.The value for the lblColorskey in the default.propertiesfile defines the update value.
An element that has a local_value attribute defined as "default.btnGreen" will haveits valueattribute updated. The value for the btnGreen key in the default.properties file defines the updatevalue.

The AIR HTML Localizer arranges locales in an order known as the localechain. If the preferred locale does not define a key value, the AIR HTMLLocalizer checks subsequent locales for a matching definition.

For more information, see Changing the locale and updating the HTML DOM.

Initializing the Localizer object and setting thelocale chain

The JavaScript in the index.html file loads the AIRLocalizer.js file:

<script src="AIRLocalizer.js" type="text/javascript" charset="utf-8"></script>

When using the AIR HTML Localizer, be sure to include the AIRLocalizer.jsfile in your project directory (as it is with this sample application).

The main JavaScript sets a reference to the Localizer object, defined in theAIRLocalizer.js file:

var localizer = air.Localizer.localizer;

The locale chain defines the languages that the application can use, in thepreferred order. When you load the AIR HTML Localizer script, it automatically setsthe locale chain. The AIR HTML Localizer code bases the locale chain on twothings:

The languages supported by the application (defined in the localedirectory)
The user interface languages supported by the operating system(defined by the user in the operating system preferences settings)

The AIR HTML Localizer scans the locale directory. It then arranges the localechain to best match the user interface languages supported by the operatingsystem.

Populating the pop-up list of supported languages

The supportedLanguagesarray, defined at the beginning of the application’s main script, lists thelocale codes the application supports:

var supportedLanguages = localizer.getLocaleChain().sort();

The init() method firstcalls the loadLanguagesSelectBox()function. This function uses these arrays to dynamically add content to a select element in the HTML DOM:

        var control = document.getElementById('changeLanguageControl');
for (i = 0;  i < supportedLanguages.length; i++)
{
    var localeCode = supportedLanguages[i];
    var languageName = localizer.getString('default', 'lblCurrentLanguage', null, localeCode);
    control.add(new Option(languageName, localeCode));
}
    

The call to the getString()method retrieves the language name for a locale. The language name is stored inthe lblCurrentLanguageproperty of the default.properties file.

The resulting selectelement looks like Figure 2.

Figure 2. The changeLanguageControl element

Initializing the application to use the preferred locale

The init() function callsthe loadLanguagePrefs() function.This function checks if the application has saved a language setting. Each timethe application runs or the user changes language preferences, the applicationstores a preferred language code in a preferences file. This preferences file isthe prefs/language.txt file in the application storage directory. If that fileexists, the loadLanguagePrefs()function returns the language code (such as "fr")stored in the file.

        var prefsFile = air.File.applicationStorageDirectory;
prefsFile = prefsFile.resolvePath("prefs/language.txt");
if (prefsFile.exists)
{
    stream = new air.FileStream();
    stream.open(prefsFile, air.FileMode.READ);
    var language = stream.readUTFBytes(stream.bytesAvailable);
    stream.close();
    return language;
}
    

If the code cannot find the preferences file, the application is runfor the first time. In that case, the loadLanguagePrefs()function returns the value of localizer.getLocaleChain()[0].This value is the first language defined in the locale chain:

return localizer.getLocaleChain()[0];

The init() function usesthe value returned by the loadLanguagePrefs()function to update the selected language in the changeLanguageControl select element. It also calls the changeLanguage() function, passing thelanguage code as a parameter:

        var language = loadLanguagePrefs(); document.getElementById('changeLanguageControl').value = language;
changeLanguage(language);
    

The next section describes the changeLanguage()function.

Changing the locale and updating the HTML DOM

The changeLanguage() functionupdates the HTML DOM to use the locale selected in the changeLanguageControl select element.The user can change the value selected in this element (see Figure 3).

Figure 3. The changeLanguageControl element

Also, the init() functionupdates this element to reflect the preferred locale (see the previous section),and calls the changeLanguage() function.

The changeLanguage()function changes the order of the locale chain, based on the selection of the changeLanguageControl element. The getLocaleChain() method of the Localizerobject returns an array of locale codes defining the locale chain:

        var selectedLocale = document.getElementById('changeLanguageControl').value;
    var chain = air.Localizer.sortLanguagesByPreference(supportedLanguages, [selectedLocale]);
    

The function then updates the AIR HTML Localizer to use the new localechain:

localizer.setLocaleChain(chain);

The next line of code updates the HTML DOM with strings defined in thelocale chain:

localizer.update();

The next line of code calls the saveLanguagePref()function:

saveLanguagePref(selectedLocale);

The saveLanguagePref()function saves the selected locale to a preferences file, as described in thenext section.

Saving the language preference to a file

The saveLanguagePref()function saves the selected language code to the prefs/language.txt file in theapplication storage directory:

        var prefsFile = air.File.applicationStorageDirectory;
prefsFile = prefsFile.resolvePath("prefs/language.txt");
stream = new air.FileStream();
stream.open(prefsFile, air.FileMode.WRITE);
stream.writeUTFBytes(language);
stream.close();
    

The application reads this preferences file the next time it initializes.See Initializing the Localizer object and setting the locale chain.

Supporting multiple languages in the AIR application installer

With AIR 1.1, the AIR application installersupports multiple languages. These include Traditional Chinese, SimplifiedChinese, English, French, German, Italian, Japanese, Korean, BrazilianPortuguese, Russian, and Spanish. In the application descriptor file, you candefine name and description elements for each of theselanguages. The HTML localization sample application defines name and description elements in English, French, Romanian, andSpanish:

        <name>
    <text xml:lang="en">Sample Multi-Language Application</text>
    <text xml:lang="es">Muestra del applicacion multilingue</text>
    <text xml:lang="fr">Example d'application multilingue</text>
    <text xml:lang="ro">Aplicatie Demo Pentru Suportul Multi Limba</text>
</name>
<description>
    <text xml:lang="en">
        This is a simple example application that shows how to use the AIR HTML 
        Localization framework.
    </text>
    <text xml:lang="es">
        Este es un applicacion simple que demuestra como usar el AIR HTML 
        estructura de localizacion.
    </text>
    <text xml:lang="fr">
        Cette simple application est un exemple qui illustre l'utilisation du 
        AIR HTML Localization framework.
    </text>
    <text xml:lang="ro">
        Aceasta este o aplicatie simpla ce demonstreaza folosirea framework-ului 
        AIR HTML Localization.
    </text>
</description>
    