Deitte.com

A resource bundle is a simple file, commonly called a properties file, where keys and values are stored. The file format for resource bundles is similar to Java properties files, with a "key=value" on each line. The main difference from the Java properties format is that files with non-ASCII characters in them should be stored as UTF-8.

Properties files are put in directories where they can be searched for by the compiler in the same way that other source files are found. The properties files should be arranged in directories in a specific way that's explained in the example below.

The values in the resource bundles can be accessed in Flex through @Resource in MXML or through ResourceBundle metadata and the ResourceBundle class in ActionScript. There's two pieces of information that are needed to access resource bundles in MXML or ActionScript- a bundle name and a key. The bundle name is the same name as the properties file. So if you create HelloWorldBundle.properties, the bundle name is HelloWorldBundle. The keys are found in the properties file, to the left of the values.

We'll start off the example by creating a new Flex project in Flex Builder. When creating the project, select Basic for data access and name the project whatever you'd like. Click on "Next" to enter more information.

Before entering anything else in Flex Builder, we need to create directories for the properties files. The files should go in their own directories that are outside of any current source path. I've created the main directory for the properties file in the default directory for projects:

	   C:\Documents and Settings\bdeitte\My Documents\Flex Builder 2\locale

We also need to add subdirectories for each language we plan to have resource bundles in. The subdirectory names should match the locale names we plan to use We'll be using en_US for our English strings and sp for Spanish strings. So now I have:

	  C:\Documents and Settings\bdeitte\My Documents\Flex Builder 2\locale\en_US
	  C:\Documents and Settings\bdeitte\My Documents\Flex Builder 2\locale\sp

We'll get back to putting files in these directories later. Now we want to finish setting up our Flex Builder project. To have the project find the resource bundles, we need to add the directories we've just created to the source path. We don't add a source path for both en_US and sp, but rather we use the special "{locale}" signifier. So I add this folder as a source path in Flex Builder:

	  C:\Documents and Settings\bdeitte\My Documents\Flex Builder 2\locale\{locale}

The Main application file name should be changed to HelloWorld.mxml. Then click Finish.

You should now have a HelloWorld.mxml file in front of you in Flex Builder. In Source mode, change HelloWorld.mxml to the following:<.p>

	<?xml version="1.0" encoding="utf-8"?>
	<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">
		<mx:Label text="@Resource(key='hello', bundle='HelloWorldBundle')"/>
	</mx:Application>

This is all of the MXML for the Hello World application that we are building. Note the use of @Resource for the Label's text and the key and bundle information. At this point you can try to compile HelloWorld.mxml, but you'll get the following error:

   Unable to resolve a class for ResourceBundle: HelloWorldBundle.	

A class is mentioned here because the Flex compiler thinks of the properties files as classes, and it can't find a properties files.

Create the file HelloWorldBundle.properties in the en_US directory created earlier. Add the following to the file:

	   hello=Hello World

Create HelloWorldBundle.properties in the sp directory, and add the following to the file:

	   hello=Hola Mundo

The names of the properties files correspond to the bundle value we specified in @Resource, and the key value corresponds to the left side. We could add more key values as needed, like this:

	hello=Hola Mundo
	one=uno
	bye=Adios

We can then go back to Flex Builder and run HelloWorld. When you run the project, you should see on the screen the most exciting of Flex applications, "Hello World".

To run the project in Spanish, right-click on the project name and bring up the properties for the project. In the additional compiler arguments, change the locale from "en_US" to "sp". The "sp" matches the folder name where we put the second HelloWorldBundle.properties. When you run the project after this, you will see "Hola Mundo".

If you were building these Flex applications for later use, you would have to copy the directory of output files from the English version before building the Spanish version. Alternatively, you could build these files with the command-line compiler when creating the final SWFs. You would also need to build a page in HTML or Flash for choosing between the different languages.

We only explored using @Resource within MXML and did not use the ResourceBundle metadata in ActionScript. This is an essential part of using resource bundles. Check the "Localizing Flex Applications" section of "Flex 2 Developer's Guide" in the Flex documentation to learn more about this.

We didn't discuss a few of the more advanced features of resource bundles in this article:

• Resource bundles can be used inside of SWCs if you create resource bundle SWCs.
• Complete classes and media such as images can be internationalized by using custom resource bundles.
• All of the framework uses properties files, and by using the framework source you can localize the framework.

More information about these features can also be found in the "Localizing Flex Applications" documentation.

The ResourceBundle API documentation can be used to learn more about resource bundles, but try to ignore the main summary on the page. Significant pieces of the description are currently incorrect.

There's a few issues with resource bundles which will be fixed in the next update to Flex. Most notably, Flex Builder can show an error after updating a properties file. You'll know you are encountering this problem if you see an "Unable to resolve a class for ResourceBundle" error where the class mentioned ends with "_properties". Clean the project in order to remove the error.

We haven't decided on this change, but Flex Builder could remove the need to copy directories. This could be done through a publish dialogue that allows multiple locales to be chosen.

Flex could allow resources to be dynamically retrieved at runtime. For now, Flex only supports the compiling of resource bundles into the SWF.

In the far future, Flex may allow different translation formats than properties files, such as the XML Localization Interchange File Format. We also plan to allow media and classes to be added to properties files. This will mean that custom resource bundles won't be needed for complex resource bundles.

Update: As noted in the comments, this article was published.

Update2: This article has been translated to Chinese on zhuoqun.net.