« Finally Updated: Embedding HTML in a Flex application using an IFrame | Main | Heading to Brightcove »

Using Resource Bundles in Flex

An important note: if you're planning to use this information for Flex 3 development, please see the documentation instead. There's a number of significant differences in using resource bundles in Flex 3. This information is only applicable to Flex 2.

This 1100-word article was supposed to be published, but I haven't heard anything about it in a long time. So I'm sharing it here:

There comes a day when we all need an application in multiple languages. In Flex, the solution to this problem is resource bundles. In this article, I'll describe the basic use of resource bundles and create a small example in Flex Builder. I'll also suggest some resources for further exploration and ponder some potential future directions of this feature.

The Basics of Resource Bundles

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.

Setting Up the Flex Builder Project

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.

Creating HelloWorld.mxml

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')"/>

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.

Adding the 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
Building and Running the SWFs

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.

Further Exploration

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.

Future Directions

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.

Comments (11)


Well this is amusing. This was published and I didn't know it:


This version is the same as the published one.


Thanks for the article ! I've being wanting to see how I can use the resource bundle in Flex but I was too lazy to chekc the Flex Dev Guide :-)
I have a question regarding the resource. Will this be a good way to store some configurations settings for my app ? Stuff like URLs and I don't know what else one might need and should not be in the source code.
I think resource should be used only for localizing the app since they are bound to a local string.
Thanks for any comments on this.

Thanks for this article! I have not known that

Crisp, I would store configuration settings in an XML file and load it with HTTPService.

Tariq, yes now I see I was mistaken! I did search for the article on the DDJ site but couldn't find it. I emailed SYS-CON right after I posted this and found out that it was simply a miscommunication. But I'll keep this post up here so that more people come across the information.


When I tried in my flex builder 3 beta, it occurs following errors. Any one could help on this? Thanks in advance.
Error: Unable to resolve a class for ResourceBundle: core

Error: Unable to resolve a class for ResourceBundle: styles

Error: Unable to resolve a class for ResourceBundle: effects

Error: Unable to resolve a class for ResourceBundle: skins

Error: Unable to resolve a class for ResourceBundle: containers

chaos, there were a lot of ResourceBundle changes in Flex 3. See the following article for details: http://labs.adobe.com/wiki/index.php/Flex_3:Feature_Introductions:_Runtime_Localization . I'm guessing that something changed on purpose here, but I haven't had the chance to look at the changes myself. If you figure this out or hear from someone at Adobe on this, can you post a comment here to help others? Thanks.



I have few problem regarding to ResourceBundle in Flex especially in Flex 3.

If you allow me to mail you I would like to show you my code , its a simple and small snippet, but that is giving me a trivial error.

Can you help me... ?


I am Automating a Flex Application
so I am adding the .swc files in Flex compiler
but when i am executing it ,it gives me the error
::(Unable to resolve resource bundle "rft_flexautomation" for locale "en_US").

Can Anyone Help me Plzz...?

vishanth pawar:

I am trying to implement the localization but it is giving compile time error saying "unable to resolve resouce bundle 'myResource'".
I set the Flex_compiler additional arguments to the
-locale=fr_FR,en_US -source-path=D:/workspaces/NewHWF/HWF/flex_src/locale/{locale} -allow-source-path-overlap=true -include-resource-bundles=flexpoc,SharedResources,collections,containers,controls,core,datamanagement,effects,formatters,logging,messaging,rpc,skins,styles

I am unable to resolve this error.

Please help me in this to resolve

vishanth, not sure what's going on from that info. I would ask on flexcoders mailing list. Also, note that the info above is just for Flex 2.