Building multilingual Flex applications on Adobe AIR

Adobe AIR 1.1 adds an important new capability to help us reach our goal of getting the AIR runtime on as many computers as possible: localization. This article describes the new localization functionality in AIR 1.1, discusses our localization framework support, and outlines the process I went through to localize Apprise, a simple but powerful feed aggregator written for AIR (see Figure 1).

Note: Apprise is an open source project; you can find the latest code at Google Code.

Understanding localization support in Adobe AIR 1.1

Adding localization to a platform is tricky because it's not just a single feature; it's actually a bunch of features that allow both the AIR runtime and AIR applications to be completely at home on non-English systems.

The list of components that make up the AIR 1.1 localization support include:

• Improved language rendering: The AIR 1.1 runtime should be able to render characters in just about any written language in both SWF and HTML content (including SWF in HTML).
• Runtime localization: Runtime dialog boxes (such as the runtime installer and application installer), application dialog boxes (such as the file browser, JavaScript alerts, and more), and default menus have been localized into Japanese, French, German, Chinese (traditional and simplified), Italian, Spanish, Korean, Portuguese, and Russian.
• IME (Input Method Editor) support: This allows users to input characters not present on their keyboards.
• New APIs: The AIR 1.1 runtime contains the new Capabilities.languages property which returns an array containing information about the user's preferred languages.
• Framework support: Flex 3 already contains runtime localization support, although there's an ActionScript library referenced below that makes dynamically localizing your Adobe AIR applications even easier. There's also an entire JavaScript localization framework included in the AIR SDK for localizing HTML applications.

The first three items above work automatically. In other words, as a developer, there's nothing you need to do in order to get non-English characters to render correctly in AIR applications. Additionally, runtime strings are automatically displayed to end users in the most appropriate language, and IMEs just work. Therefore, this article focuses on the code developers do have to worry about in order to localize their AIR applications.

Apprise was the first AIR application I localized, so I learned a lot during the process. I discovered that there are really three steps to the process:

1. Picking the most appropraite language.
2. Telling Flex which language to use.
3. Replacing strings and date masks.

Choosing the most appropriate language

Flex 3 provides runtime localization support, which works great in AIR. Runtime localization support means that you don't have to distribute a different .air file for each language you support. Rather, you can distribute a single .air file which contains resource bundles with strings translated into all the languages you support. The application can then dynamically tell Flex which language to use, and if the code was written correctly, the entire user interface will adapt itself automatically.

There are two ways to figure out which language your application should use:

• Let users pick the language themselves. Your application might provide a select box or a menu with all the supported languages, allowing the end user to pick the language he or she is most comfortable with.
• Query the operating system for the most appropriate language.

I chose to use the second approach in Apprise.

AIR 1.1 adds the new languages property to the flash.system.Capabilities class which returns an array of preferred languages as specified by the operating system. So now you know which languages the end user prefers, and of course you aleady know which languages your application supports, but you still have a problem: how do you put those two lists together to decide on the best language to use?

The problem is trickier than it initially seems, because the language information returned by the OS may or may not contain region information. Likewise, your own language packs also may or may not include region information. Eventually, the Flex framework will solve this problem for you (the changes are already checked into the public Flex source code repository, but they haven't yet made it into an official release); for now, we recommend using as3localelib. The as3locatelib project contains a class called LocaleUtil, which has a single static function called sortLanguagesByPreference. The sortLanguagesByPreference function takes an array of languages that you support, an array of languages representing the system preferences, and a "fallback" locale to be used in case there is no good option.

The code in Apprise looks like this:

For more information on as3localelib and to download the code for your project, check out the as3locale project page on Google Code.

Telling Flex which language to use

Now that you have a list of languages sorted by both what your application supports and the end user's preferences, all you have to do is tell the Flex framework which language the application should use (and therefore which resource bundles should be used). The localeChain property of the ResourceManager class tells Flex the order of the resource bundles to pull strings out of.

In Apprise, the code looks like this:

Replacing Strings and Date Masks

Since Apprise was originally written for AIR 1.0 (which did not include localization support), I had to go back and replace hardcoded strings with strings dynamically loaded from resource bundles. Resource bundles are files (or resources) that contain name/value pairs arranged in a conventional directory structure which Flex knows to look for. For example, in my Apprise src directory (shown in Figure 2), I created the directory "locale" inside of which I created a directory for each language Apprise supports. Inside of those directories, I created resource files with name/value pairs like this:

Of course, for the non-English resources, these name/value pairs are translated appropriately.

I'm not going to get into a lot of detail on how this works because there's already an excellent article called Localizing Flex Applications, which tells you everything you need to know about the Flex 3 runtime localization feature. But I'll show you a few examples.

Throughout my code, I changed labels that looked like this:

to this:

I also localized my date masks, so rather than this:

I used something like this:

That's about all that goes into localizing an AIR 1.1 application written in Flex. We also provide an excellent localization framework for HTML applications which you can read about in the Quick Start article, Building a multilingual HTML-based application.