All Flex applications use resource bundles, whether you are aware of them or not. The Flex framework has a bunch of resource bundles for things such as containers, controls, effects, skins, and styles. These resource bundles are compiled into an application by default. You can also create your own custom resource bundles to use for things such as localization. You create a resource bundle by creating a new UTF-8 encoded text file and populating it with keys and values. Each key and value is delimited by an equals sign, and each key-value pair should be on its own line in the file. The following is an example of such a file:

instruction=Select a value
color=Color
send=Send

The keys in this example are instruction, color, and send. You probably noticed that all the values are strings. However, you can also embed objects and classes in a resource bundle using the Embed() and ClassReference() directives.

The following example not only uses string values, but also embeds an image:

instruction=Select a value
color=Color
send=Send
flag=Embed('../../usa.jpg')

You must save resource bundle files using the .properties extension. For example, you can save a resource bundle file as languageResources.properties. You will almost always want to save resource bundle files maintaining parity in naming, but placing them in subdirectories each named by locale. For example, if you want to support both French and Spanish, you might create two resource bundle files, both called languageResources.properties, but place them in different subdirectories called fr_FR and es_ES, respectively. Generally, you should place all the localization resource bundle files in subdirectories of one parent directory. For example, in the preceding scenario, the paths to the files might be locale/fr_FR/languageResources.properties and locale/es_ES/languageResources.properties. You could continue this pattern for as many locales as you need to support. For example, you could support English in the United States by adding a new file called locale/en_US/languageResources.properties. Usually, each file will contain the same set of keys, but with different, locale/language-specific values. For the examples that follow in the next few sections, we’ll use the resource bundle files shown in Example 5-2, Example 5-3, and Example 5-4. For each resource bundle we’ll assume that the files are saved in subdirectories of a locale directory that is a sibling of the src directory for the Flex project.

The code in Example 5-2 is saved in locale/en_US/languageResources.properties. This also assumes that there’s an assets directory in the project root, and that the .jpg files referenced in the following code examples are stored in that assets directory.

instruction=Select a value
color=Color
send=Send
flag=Embed('../../assets/usa.jpg')

The code in Example 5-3 is saved in locales/en_CA/languageResources.properties.

instruction=Select a value
color=Colour
send=Send
flag=Embed('../../assets/canada.jpg')

The code in Example 5-4 is saved in locales/es_ES/languageResources.properties.

instruction=Seleccione un valor
color=Color
send=Envíe
flag=Embed('../../assets/spain.jpg')

As we mentioned earlier, Flex includes a bunch of resource bundles that it uses when compiling most Flex applications. For example, there are bundles for controls, containers, styles, and effects. Some of these bundles are locale-specific, and the Flex SDK has only the bundles for the locale for which the SDK was intended. As an example, in the United States some of the Flex resource bundles are stored in the frameworks/locale/en_US directory of the SDK because they are specific to U.S. English. If you want to use resource bundles other than the locales already supported by the version of the SDK you have, you will need to create copies of the existing resource bundles, saving them to directories within frameworks/locale with the locale names you intend to use. For example, if you want to support Spanish (from Spain), you'll need to make sure you have a frameworks/locale/es_ES directory in your SDK containing all the necessary resource bundles (compiled and packaged as .swc files). The simplest way to accomplish this is to use the copylocale utility provided in the bin directory of the SDK. The copylocale utility will copy an existing locale’s resource bundles to a new locale. The syntax is as follows:

copylocale existingLocale newLocale

For example, if you already have the en_US locale and you want to support French, you could run copylocale as follows:

copylocale en_US fr_FR

For the examples that we’ll see in the following sections, we’ll assume that we’ve already run copylocale as necessary to ensure that we have the following locales in the SDK: en_US, en_CA, and es_ES.

One of the many manager classes that are included in the Flex framework is the ResourceManager class. As the name implies, this class is responsible for managing resources from resource bundles. In the next few sections, we’ll see ways in which you can tell a ResourceManager what resource bundle(s) to use. However, first we’ll look at how to access a ResourceManager as well as how to access the data from resource bundles via a ResourceManager.

The ResourceManager class uses the Singleton design pattern; therefore, there is just one instance per application. You can access that instance in one of two ways:

A ResourceManager object contains all the data for all the resource bundles that have been loaded into an application. You can retrieve that data in two ways:

The Resource() directive allows you to access data once, at application startup. That means you should use the Resource() directive only for compile-time localization. The directive requires that you pass it two attributes: bundle and key. The bundle is the name of the resource bundle file (minus the .properties extension) in which the key is defined. The key is the name of the key from the file for which you want the value. For example, the following uses the Resource() directive to retrieve the color value from the languageResources resource bundle:

<mx:Label text="@Resource(bundle='languageResources', key='color')" />

If you would like to retrieve a value from ResourceManager using ActionScript or in a data binding expression, you will need to use one of the following get methods of ResourceManager: getString(), getNumber(), getInt(), getUint(), getBoolean(), getObject(), getStringArray(), or getClass(). All of these methods require two parameters: the resource bundle name and the key name. For example, the following code retrieves the value for the color key from the languageResources resource bundle:

var color:uint = ResourceManager.getInstance().getInt("languageResources", "color");

As you’ve already seen, most data is stored in a .properties file as strings. The exceptions to that are embedded assets (using the Embed() directive) and classes (using the ClassReference() directive). Since there is no formal way to distinguish values as string, number, integer, Boolean, and so on, when storing the values in a .properties file, the responsibility of differentiating is left to the ResourceManager and you, the developer. You can use the get methods to specify how you’d like the ResourceManager to coerce the value for a key. For example, getBoolean() will attempt to coerce the value to a Boolean value whereas getInt() will attempt to coerce the value to an integer. You should use the getClass() method to retrieve all values stored using the Embed() or ClassReference() directive.

When you want to implement compile-time localization, you need to do two things:

The following code illustrates how an MXML document might look when using compile-time localization:

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="vertical">
    <mx:Form>
         <mx:FormHeading label="@Resource(key='instruction', bundle=
'languageResources')" />
         <mx:FormItem label="@Resource(bundle='languageResources', key='color')">
              <mx:ColorPicker id="color" />
         </mx:FormItem>
         <mx:FormItem>
              <mx:Button label="@Resource(bundle='languageResources', key='send')" />
         </mx:FormItem>
    </mx:Form>
    <mx:Image source="@Resource(bundle='languageResources', key='flag')" />
</mx:Application>

When compiling the application, you must tell it what resource bundles to use by adding a locale attribute to the compiler options. You also need to tell the compiler where it can find custom resource bundle .properties files by adding the directory for the resource bundle files to the source path. The following code tells the compiler to compile an application using the en_CA resource bundle, and it tells the compiler where it can find custom resource bundle files:

mxmlc -locale en_CA -source-path=../locale/{locale} Example.mxml

If you are using Flex Builder, you should do the following:

Runtime localization occurs in one of two ways:

We’ll look at each option in the following sections.

-locale en_US en_CA es_ES -source-path=../locales/{locale}

resourceManager.localeChain = ["en_US"];

<mx:Metadata>
    [ResourceBundle("languageResources")]
</mx:Metadata>

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="vertical">
    <mx:Metadata>
         [ResourceBundle("languageResources")]
    </mx:Metadata>
    <mx:Script>
         <![CDATA[

              private function selectLanguage():void {
                   resourceManager.localeChain = [language.value];
              }

         ]]>
    </mx:Script>
    <mx:ComboBox id="language" change="selectLanguage();">
         <mx:dataProvider>
              <mx:ArrayCollection>
                   <mx:Object label="English (US)" data="en_US" />
                   <mx:Object label="English (Canada)" data="en_CA" />
                   <mx:Object label="Espanol (Espana)" data="es_ES" />
              </mx:ArrayCollection>
         </mx:dataProvider>
    </mx:ComboBox>
    <mx:Form>
         <mx:FormHeading
label="{resourceManager.getString('languageResources', 'instruction')}" />
         <mx:FormItem
label="{resourceManager.getString('languageResources', 'color')}">
              <mx:ColorPicker id="color" />
         </mx:FormItem>
         <mx:FormItem>
              <mx:Button
label="{resourceManager.getString('languageResources', 'send')}" />
         </mx:FormItem>
    </mx:Form>
    <mx:Image
source="{resourceManager.getClass('languageResources', 'flag')}" />
</mx:Application>

mxmlc -locale= -resource-bundle-list=listOfResourceBundles.txt Example.mxml

bundles = collections containers controls core effects languageResources skins styles

mxmlc -locale=locale -source-path=locale/{locale} -include-resource-
bundles=commaDelimitedListOfResourceBundles -output resourceModuleName.swf

mxmlc -locale=en_US -source-path=locale/{locale}
-include-resource-bundles=languageResources,collections,containers,
controls,core,effects,skins,styles -output en_US_ResourceModule.swf

localeChain=en_US&resourceModuleURLs=en_US_ResourceModule.swf

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="vertical">
    <mx:Metadata>
         [ResourceBundle("languageResources")]
    </mx:Metadata>
    <mx:Script>
         <![CDATA[

              import mx.events.ResourceEvent;

              private var _selectedResourceName:String;

              private function changeResourceHandler(resourceName:String):void {
                   _selectedResourceName = resourceName;
                   var eventDispatcher:IEventDispatcher = resourceManager.
loadResourceModule(resourceName + "_ResourceModule.swf");
                   eventDispatcher.addEventListener(ResourceEvent.COMPLETE,
languageModuleLoadedHandler);
              }

              private function languageModuleLoadedHandler(event:Event):void {
                   resourceManager.localeChain = [_selectedResourceName];
              }

              private function selectLanguage():void {
                   changeResourceHandler(language.value as String);
              }

         ]]>
    </mx:Script>
    <mx:ComboBox id="language" change="selectLanguage();">
         <mx:dataProvider>
              <mx:ArrayCollection>
                   <mx:Object label="English (US)" data="en_US" />
                   <mx:Object label="English (Canada)" data="en_CA" />
                   <mx:Object label="Espanol (Espana)" data="es_ES" />
              </mx:ArrayCollection>
         </mx:dataProvider>
    </mx:ComboBox>
    <mx:Form>
         <mx:FormHeading
label="{resourceManager.getString('languageResources', 'instruction')}" />
         <mx:FormItem label="{resourceManager.getString('resources', 'color')}">
              <mx:ColorPicker id="color" />
         </mx:FormItem>
         <mx:FormItem>
              <mx:Button
label="{resourceManager.getString('languageResources', 'send')}" />
         </mx:FormItem>
    </mx:Form>
    <mx:Image
source="{resourceManager.getClass('languageResources', 'flag')}"
width="60" height="40" />
</mx:Application>