Flex 3:Feature Introductions: Runtime Localization

Flex 3:Feature Introductions: Runtime Localization

From Adobe Labs (http://labs.adobe.com/wiki/index.php/Flex_3:Feature_Introductions:_Runtime_Localization)

Runtime Localization

Gordon Smith
September 25. 2007

Table of contents [hide]

1 Introduction 2 Sounds cool. Can I see a demo? 3 How about a simpler tutorial? 4 What are all those compilation options? 5 Huh? French framework resources? 6 Hello? Non... Bonjour! 7 OK, OK. How do I switch locales on the fly? 8 What’s this resourceManager thing? 9 Why do I need to write a binding expression instead of @Resource()? 10 What’s up with [ResourceBundle]? 11 Why is the localeChain an Array? 12 Can resource values only be Strings? 13 How do I compile a resource module? 14 How do I preload a resource module? 15 How do I load a resource module programmatically? 16 I’m tired! Anything else?

Introduction

In Flex 2, the localized resources for an application had to be linked into the application SWF. Also, the resources could only be for a single locale, so if you wanted to localize for multiple locales you had to build multiple application SWFs.

With Flex 3, localization support will become much more Flexible! Here’s how:

• You can put your resources into resource modules -- similar to style modules -- rather than into the application itself. You can preload the module for an appropriate locale when the application starts, and you can load modules for additional locales later.

• You can compile resources for multiple locales into a single application or module.

• You access all resources through a new ResourceManager, which can manage resources for multiple locales. You can change at runtime which locales get searched for resources.

• Binding expressions that reference resources via the new ResourceManager will automatically update if the locale changes. Components are notified when the locale changes so that they can update themselves appropriately.

• You can also use images, sounds, etc. as resources rather than just strings.

• You can programatically create your own resources at runtime and use them just like ones that were compiled from .properties files. So you can create resources at runtime from downloaded XML files, database results, etc.

Sounds cool. Can I see a demo?

To see what you’ll be able to do with runtime localization, take a look at the FlightReservation1 and FlightReservation2 demo applications. They accomplish the same thing, but they use two different localization strategies. Both versions have been localized for U.S. English (the en_US locale) and for Japanese (the ja_JP locale). They are provided as Flex Builder 3 projects which you can import into a Flex Builder workspace. Choose File > Import, select General > Existing Projects into Workspace, and browse for each project. Please read each project's README.txt file for more information. If you simply copy files into a new Flex Builder project rather than importing the projects, be sure to follow the instructions in these files or you may get compilation or runtime errors.

In FlightReservation1, both the en_US and the ja_JP resources are compiled into the application SWF. The first time that the application is launched, the en_US resources will be used by default. A Language combobox allows the user to select Japanese, at which point the application tells the ResourceManager to use the ja_JP resources instead of the en_US ones. As a result, the user interface switches — on the fly! — to Japanese. The application also saves the user’s locale choice in a local SharedObject. The next time the application starts, it reads this saved locale and uses its resources by default. So if you switch to Japanese and quit, this application will restart in Japanese.

In FlightReservation2, the application has no resources inside it. Instead they are compiled into two separate resource module SWFs, Resources_en_US.swf and Resources_ja_JP.swf. (Note: You cannot create resource modules in Flex Builder 3; you must use command-line tools to do so.) The HTML template (html-template/index.template.html) has been customized to preload the English resource module by specifying properties named resourceModuleURLs and localeChain in the FlashVars. Make sure that you use this template rather than Flex Builder’s default one. (In general, server-side logic could decide which locale to initially load, and generate the appropriate HTML wrapper.) When the user switches the locale at runtime, the application determines whether the new locale has already been loaded, and, if not, loads the appropriate resource module. So, the first time that the user chooses Japanese, the Japanese module will get loaded. But then the user can continue to switch back and forth between English and Japanese with no further module loading.

The on-the-fly locale switching in both versions is accomplished primarily by simple binding expressions which automatically update when the locale is changed. However, these applications use some other interesting localization techniques:

• The XML data — which simulates back-end data that in the real world would come from a database — is locale-independent. For example, the “from” and “to” locations for a route are expressed as airport codes. But the user interface localizes this info into locale-dependent city names using labelFunctions, and it sorts the lists based on the localized names.

• Dates are displayed with locale-dependent formatting.

• The flight distance is displayed in locale-dependent units — miles for U.S. English, kilometers for Japanese — with locale-dependent formatting.

• Prices are displayed in locale-dependent units — U.S. dollars for U.S. English, Yen for Japanese — with locale-dependent formatting (i.e., currency symbol and precision).

How about a simpler tutorial?

Sure. There is quite a bit going on in the FlightReservation demo, so I’ll let you dig into that by yourself when you’re ready. For now, lets go step-by-step through a really simple “Hello” app that we’ll localize for English and French. It will give you a good introduction to various aspects of localization in Flex 3.

Create a new Flex Project called RunLoc in Flex Builder. Enter the following code for RunLoc.mxml:

Just as in Flex 2, you can use the @Resource() MXML compiler directive to specify that the Label’s text property is to be set to a localized value from a resource bundle, rather than simply writing

with the hard-coded English word “Hello!”. The bundle and key attributes inside the @Resource() directive tell the compiler that we want to use the resource named GREETING inside a resource bundle named myResources.

The simplest way to create a resource bundle is to provide a .properties file defining the keys and values in the bundle. The MXML compiler will compile a .properties file into a subclass of the mx.resources.ResourceBundle class. So, create a folder named locale inside the project (as a sibling of the src folder) and, inside locale, create a folder named en_US for our U.S. English resources. Inside the en_US folder, create a file called myResources.properties. Open the Properties dialog for the myResources.properties file and set its "Text file encoding" to UTF-8. (If this causes a warning, ignore it.) The MXML compiler expects all .properties files to have UTF-8 encoding. Now edit the file and put one English resource in it:

GREETING=Hello!

Now open the project’s Properties dialog, select the Flex Compiler pane, and enter the following as “Additional compiler arguments”:

-locale=en_US -source-path=../locale/{locale}

If you now compile and run the application, you should see “Hello!” displayed.

What are all those compilation options?

I knew you’d ask.

From the @Resource() directive, the compiler knows that the application uses a resource bundle named myResources. The -source-path option tells the compiler where to look for additional source files such myResources.properties. The locale, en_US, specified by the -locale option is automatically subsituted for the special {locale} token in -source-path. When we change the locale, we won’t have to also change the source path. You need the .. in the source path because, in Flex Builder 3 Beta 2, a relative source path is resolved relative to the src directory, not relative to the project directory. This may change before we ship.

The -locale=en_US option also tells the compiler to use the en_US version of the framework resources. What are framework resources? Well, framework components such as Label use resources, just like your application and your custom components can use resources. Label and other framework classes have been precompiled into component libraries in the frameworks/libs folder of the Flex SDK. The resources required by these classes are located in separate resource bundle libraries in the frameworks/locale folder. For example, the English resources for the frameworks/libs/framework.swc library are in the resource bundle library frameworks/locale/en_US/framework_rb.swc.

Now we’d like to localize our RunLoc app for French — by providing resources for the fr_FR locale. But first we need to deal with the fact that the Flex SDK doesn't provide French framework resources.

Huh? French framework resources?

In the past, the MXML compiler was happy as long as you provided application resources for the locale you specified with the -locale option; it would fall back and use the en_US framework resources if it didn’t find those for the locale you specified. But the Flex 3 compiler is pickier: if you specify -locale=fr_FR then it will expect to find French framework resources.

Don’t worry, though... it’s not hard to make an fr_FR framework resource library. You can just use a command-line script which will compile the en_US .properties files for the fr_FR locale!

Set the current directory to the Flex SDK that your Flex Builder project is using. By default, this will be the directory sdks/3.0.0 inside your Flex Builder installation. Now execute

bin\copylocale.exe en_US fr_FR

on Windows or

bin/copylocale.sh en_US fr_FR

on Macintosh. Check to make sure that you now have a framework_rb.swc file inside frameworks\locale\fr_FR.

Now that we’ve made a French framework resource library, it’s really easy to localize our app for French.

Note that for some reason the data visualization src folder is missing from build 3.0.183654.
So if you try to run copylocale you will get this message:
C:\Program Files\Adobe\Flex Builder 3\sdks\3.0.0\bin>copylocale en_US fr_FR
Error: Directory "C:\Program Files\Adobe\Flex Builder 3\sdks\3.0.0\frameworks\projects\datavisualization\bundles\en_US\src" does not exist

I simply created an empty src folder at that location and then copylocale works.

C:\Program Files\Adobe\Flex Builder 3\sdks\3.0.0\bin>copylocale en_US fr_FR
In Flex SDK at C:\Program Files\Adobe\Flex Builder 3\sdks\3.0.0 ...

After doing all these steps I got an error "resource bundle charts not available". Then I copied the "charts_rbc.swc" from sdk 2.0.1 folder and placed inside the folder "C:\Program Files\Adobe\Flex Builder 3\sdks\3.32.0\frameworks\locale\fr_FR". Then I compiled the project again. Now it was working. Thanks to "http://www.herrodius.com/blog/123"

Hello? Non... Bonjour!

Inside the locale folder of the RunLoc project, create a folder called fr_FR. Inside the fr_FR folder, create a file called myResources.properties and sets its encoding to UTF-8. Enter the French version of the GREETING resource in it:

GREETING=Bonjour!

Open the project’s Properties dialog, select the Flex Compiler pane, and in the “Additional compiler arguments” simply change

-locale=en_US

to

-locale=fr_FR

Now run the application... you should see “Bonjour!” instead of “Hello!”.

OK, OK. How do I switch locales on the fly?

You’re right to be bored so far... up to this point we haven’t done anything that wasn’t possible in previous versions of Flex. But now we’re ready to talk about Flex 3’s improvements. To start, let's compile our RunLoc demo for both English and French, and add some code to switch between them.

Change RunLoc.mxml to look like this:

    
        [ResourceBundle("myResources")]
    

    
     
   
        [Bindable]
        private var locales:Array = [ "en_US" , "fr_FR" ];
 
   
        private function localeComboBox_initializeHandler(event:Event):void
        {
            localeComboBox.selectedIndex = locales.indexOf(resourceManager.localeChain[0]);
        }

        private function localeComboBox_changeHandler(event:Event):void
        {
            // Set the localeChain to either the one-element Array
            // [ "en_US" ] or the one-element Array [ "fr_FR" ].
            resourceManager.localeChain = [ localeComboBox.selectedItem ];
        }
 
   
    ]]>
    

    
 
   
                     initialize="localeComboBox_initializeHandler(event)"
                 change="localeComboBox_changeHandler(event)"/>

 
   
Change the -locale option to be 
 
   
-locale=en_US,fr_FR
 
   
Note from Jason: For Flex Builder 3.0.183654 I had to use space instead of column. i.e. "-locale=en_US fr_FR".
Also take away the 
 in the source code shown above. Great Tutorial. Thank you.
 
   
When you compile and run, the application will start in English (because en_US is specified as the first locale). But when you choose fr_FR in the combobox, the “Hello!” changes on the fly to “Bonjour!”. Next we’ll explain how this happens. 
 
   
 What’s this resourceManager thing? 
 
   
A new manager in the Flex framework — the ResourceManager — now handles access to all localized resources in an application. Any components that extend UIComponent, Formatter, or Validator now have a new resourceManager property, which lets you easily access the singleton instance of this manager. If you’re writing some other kind of class that needs to use the ResourceManager, you can call ResourceManager.getInstance() to get a reference to it. 
 
   
We compiled the RunLoc application in such a way that various resource bundles — our own myResources bundle, but also framework bundles such as core, controls, formatters, etc. — were linked into the application SWF. When the application started, instances of these resource bundles were automatically added to the ResourceManager. After they’ve been added, we can look up resources in them using ResourceManager methods such as getString().
 
   
Note that in the binding expression 
 
   
text="{resourceManager.getString('myResources', 'GREETING')}"
 
   
we specify a bundle name and a resource key, but not a particular locale. Instead, the locales that get searched for resources are determined by the localeChain property of the ResourceManager. The handler for the locale combobox’s "change" event sets resourceManager.localeChain. The setter for this property dispatches a "change" event from the ResourceManager, which is a signal that the application’s resources have changed in some way. This event causes two things to happen:
 
   
 
    
 
Binding expressions involving resource-access methods of ResourceManager such as getString() are updated. This is why “Hello!” changed to “Bonjour!”.
 
 
    
 
Components that extend UIComponent, Formatter, or Validator execute their resourcesChanged() method. This is how components such as CurrencyFormatter can update their default value for resource-backed properties such as currencySymbol. If you are writing another kind of class that needs to respond to resource changes, you can simply listen for "change" events from the ResourceManager.
 
 
   
 
   
 Why do I need to write a binding expression instead of @Resource()? 
 
   
We could have made the @Resource() directive generate a binding expression that would update when the localeChain changes, but we decided not to. Binding expressions have some overhead associated with them and we don’t want to penalize developers who need localization but not on-the-fly locale changes. 
 
   
Although switching locales on the fly is cool, it’s not something that every localized application will need. For many or even most apps, it will be good enough to start up in an appropriate locale, and perhaps allow the user to select a different locale for the next time that the application starts. In that case, @Resource() will work just fine.
 
   
Our thinking is that developers who want to support on-the-fly locale changes should “opt in” to that by writing explicit binding expressions. 
 
   
 What’s up with [ResourceBundle]? 
 
   
I was wondering when you were going to ask why I put the tag 
 
   

    [ResourceBundle("myResources")]
 
 
   
in the RunLoc app. The answer is that when you use an expression like resourceManager.getString(bundleName, key) instead of the directive @Resource(bundle='myResources', key='GREETING') to access resources, the compiler isn’t clever enough to figure out what resource bundles your application (or component, or AS class) needs. You might be determining bundleName in some very convoluted way. So when you don’t use @Resource(), you have to tell the compiler in another, very explicit, way which bundles you’re accessing.
 
   
The way to do that now is to put [ResourceBundle()] metadata with the name of the bundle into your application’s (or component’s)  tag. If you’re writing an ActionScript class instead, put this metadata on the class declaration, like this:
 
   
[ResourceBundle("myResources")]
public class MyComponent extends UIComponent
{
   ...
}
 
   
If you’ve localized Flex applications in the past, you may have used [ResourceBundle()] metadata on static or instance variables:
 
   
[ResourceBundle("myResources")]
 static var rb:ResourceBundle;
 
   
This would initialize rb to be a reference to the myResources ResourceBundle instance, and you could then write expressions such as rb.getString("GREETING"). Although this should still work if you compile for one and only one locale, it is very strongly discouraged. 
 
   
The new localization scheme relies on all resource bundles being owned by the ResourceManager, and all resource access going through the ResourceManager. You should revise any old code which access resources directly from resource bundles.
 
   
 Why is the localeChain an Array? 
 
   
Ah, you noticed that too! For example, if you want to search only the French resources you have to write 
 
   
resourceManager.localeChain = [ "fr_FR" ];
 
   
not
 
   
resourceManager.localeChain = "fr_FR";
 
   
The reason that the localeChain is an Array is so that the ResourceManager can support incomplete locales.
 
   
Suppose that you’re localizing an application for English as spoken in India (i.e., the en_IN locale). Most — but not all — of the resources will be the same as for U.S. English, so there’s no reason to duplicate them all in the en_IN resources — this just bloats your application’s size. The en_IN .properties files need only to have the resources that differ between en_US and en_IN. Then, if the ResourceManager has bundles for both en_US and en_IN and you set
 
   
resourceManager.localeChain = [ "en_IN", "en_US" ];
 
   
the ResourceManager will search for a resource first in the en_IN bundle and, if it isn’t found there, then in the en_US bundle. You can “fall back” from one locale to another until you find a resource. If getString() doesn’t find the resource you specify in any locale, it returns null. 
 
   
 Can resource values only be Strings? 
 
   
The short answer to this is No, but it’s a little complicated so I’ll give a fuller explanation.
 
   
When you compile a .properties file with resources such as 
 
   
COUNTRY=United States
PRICE=19.99
AGE=21
SENIOR=true 
 
   
the MXML compiler autogenerates a subclass of ResourceBundle with a content Object containing the key/value pairs for those resources. The generated code is equivalent to 
 
   
content["COUNTRY"] = "United States";
content["PRICE"] = "19.99";
content["AGE"] = "21";
content["SENIOR"] = "true"
 
   
Note that all of these resource values are Strings. The compiler doesn’t look at SENIOR=true and decide that the value should be the Boolean true rather than the String "true". So if you call resourceManager.getString("myBundle", "SENIOR") you’ll get the String "true".
 
   
However, the ResourceManager has other resource-access methods besides getString(). For example:
 
   
resourceManager.getNumber("myResources", "PRICE"); // returns the Number 19.99, not the String "19.99"
resourceManager.getInt("myResources", "AGE"); // returns the int 21, not the String "21"
resourceManager.getBoolean("myResources", "SENIOR") // returns the Boolean true, not the String "true"
 
   
These methods, like getString(), are actually all wrappers around the fundamental resource-access method getObject(), which returns the resource value with no conversion.
 
   
Beginning with Flex 3, you can now use Embed() and ClassReference() directives in .properties files, as in
 
   
LOGO=Embed("logo.png")
SORTER=ClassReference("sorters.Urdu")
 
   
These directives work just the same as in CSS files or  tags. When you use these directives, the resource value is of type Class. This is obvious for ClassReference(); for Embed(), it’s because the MXML compiler autogenerates a class to represent embedded data such as a PNG graphics file. You can use the ResourceManager’s getClass() method to access these resource values..
 
   
If you create your own resource bundles at runtime rather than having the MXML compiler compile them from .properties files, you can put any key/value pairs you want into their content Object. You’re not limited to Strings. This is discussed in a later section. 
 
   
Determining the initial locale
 
   
When an application is compiled for multiple locales, such as with the compilation option
 
   
-locale=en_US,fr_FR
 
   
the ResourceManager's localeChain property is initialized to this sequence of locales. For example, in this case it would find the English resources because en_US is listed first. However, you can override this default initial value by specifying the localeChain as an application parameter in the FlashVars in the HTML template.
 
   
In the html-template folder of the RunLoc project, open the index.template.html file and insert the line
 
   
"FlashVars", "localeChain=fr_FR",
 
   
after the line 
 
   
"src", "${swf}",
 
   
in the second call to the JavaScript function AC_FL_RunContent().
 
   
Save the file. Now clean the project (with Project > Clean in the menubar) to force the RunLoc.html file in the bin folder (which is simply a renamed copy of the index.template.html file) to be regenerated. It should automatically update when the index.template.html file is saved, but due to a bug in Beta 3 this doesn't happen. 
 
   
When you run, the application should start up in French. If you change fr_FR to en_US and regenerate RunLoc.html, the app should start up in English.
 
   
You can specify multiple locales in the FlashVars, as in
 
   
"FlashVars", "localeChain=en_IN,en_US",
 
   
which would initialize the localeChain property to [ "en_IN", "en_US" ].
 
   
To support browsers that have JavaScript disabled, you need to also specify the FlashVars in two other places (in the