Wednesday, September 27, 2006

Creating & Using localized flex libraries with Flexbuilder

Part One - Create SWC Library

1. Create a stand alone folder called Resources in your flexbuilder projects folder. Subsequently create subfolders in Resources for each locale (i.e. en_US, fr_FR). Here you will store your resource files: en_US\, fr_FR\, etc.
2. Start Flexbuilder. Create a flex library project called testlib. Add a source path (Project>>> Properties >>> Flex Library Build Path >>> Source Path >>> Add Folder) ${DOCUMENTS}\Resources\{locale}
3. Add a new folder to project called locale and link it (File >> New >>> Folder. At bottom click Advanced >> check "Link to Folder in the file System") to ${DOCUMENTS}\Resources
4. Create a class (code below) and then make sure it's checked in Project>>> Properties >>> Flex Library Build Path >>> Classes.
5. Create two folders under the bin folder called en_US and fr_FR
6. Change the compile arguments (Project >>> Properties >>> Flex Library Compiler >>> Additional Compiler Arguments.) to -locale fr_FR -include-resource-bundles Main
7. Hit OK then copy the compiled swc file to the fr_FR subfolder
8. Change the compile arguments to -locale en_US -include-resource-bundles Main
9. Hit OK then copied the compiled swc file to the en_US subfolder
import mx.resources.ResourceBundle;
public class Company
public var NAME_MONKEY:String;
private static var bundle:ResourceBundle;
public function Company(){
NAME_MONKEY = bundle.getString("monkey");
en_US\ contains:
fr_FR\ contains:
Part Two - Add Library to Simple Flex App
1. Created a new Basic flex application
2. Added ${DOCUMENTS}\testlib\bin\{locale}\testlib.swc to the projects Library Path
3. Added some code to my application.mxml file (highlights below)
4. Compiled and ran it (default would be en_US)
5. Changed the project compiler argument to -locale fr_FR
6. Compiled and ran it again
7. In each case the application displayed the correct string
private var company:Company = new Company();
mx:Label text="{company.NAME_MONKEY}"
Part Three - add Library to a localized Flex App
1. In this case the application and the library projects both point to the same resource folder. I basically repeated steps 2 and 3 of part 1 for my Basic Flex App Project, using the same folders and files.
2. I then added another string to the file(s), namely hello=Bonjour and hello=Good Day
3. In my application I put up two labels, one pulling directly from the resource file, the other referencing the class in the swc library and displaying company.NAME_MONKEY.
4. I added the path ${DOCUMENTS}\testlib\bin\en_US\testlib.swc to project library path of the project as I did in step 2 of part 2. (notice i did not use {locale}.
5. When i ran the app i was surprised to discover that even if I ran it with the compile argument of -local fr_FR it still pulled the correct string out of the properties file (pierre), even tho i was pointing only to the en_US version of the swc!
mx:Label text="@Resource(key='hello', bundle='Main')"
mx:Label text="{company.NAME_MONKEY}"
After spending a good chunk of time I finally got Flexbuilder to play along. Here's some things to watch out for.
1. If you change the output path of the flex library to bin/en_US instead of to bin and then manually copying it to en_US, that works. If however you then change it for the fr_FR version, Flexbuilder will nuke the previous bin/en_US folder and the files within
2. If you create your and locale folders directly in the project, you get a duplicate symbol error. By placing the files outside the project and then adding a source path reference this problem goes away. However, Flexbuilder does not handle {locale} on the fly, so you will needed a linked folder to access the files during development.
3. Occasionally you might get another error stating it can't load or find main_properties. I find going into project properties and 'altering' the compiler arguements forces a recompile and makes this error go away.
4. As per my previous blog, if you plan on using foreign characters, make sure the text encoding of the resource files is set to UTF-8.

That concludes my locale adventure thru the world of flexbuilder.

No comments: