Creating resources

You define localization resources in properties files. These properties files contain key/value pairs and are in UTF-8 format. You typically use these properties files to specify the values of Strings in your applications, such as the label on a button or the items in a drop down list. The following example specifies the values for a form's labels in English:

# locale/en_US/RegistrationForm.properties
registration_title=Registration
submit_button=Submit Form
personname=Name
street_address=Street Address
city=City
state=State
zip=ZIP Code
thanks=Thank you for registering!

Resources can also reference binary assets such as audio files, video files, SWF files, and images. To reference these assets in your properties files, you use the Embed() directive, just as you would include assets in a runtime style sheet. The following example embeds a JPG file as a resource:

flag=Embed("images/unitedstates.jpg")

You can also extract symbols from an embedded SWF file when using the Embed() directive, as the following example shows:

flag=Embed(source="FlagsOfTheWorld.swf", symbol="unitedstates")

To include custom classes, such as a programmatic skin, you can use the ClassReference() directive. The following example embeds the Sorter class in the sortingClasses.en_US package:

SORTER=ClassReference("sortingClasses.en_US.Sorter")

For information on how to use these various types of resources in your application, see Using resources.

You typically store resource properties files in the locale/locale_name subdirectory. You add this directory to your source path so that the compiler can find it when you compile your application. For information on how to compile resources into your Flex application, see Compiling resources into Flex applications.

Compiling resources into Flex applications

After you create the resource properties files, you can either compile them as resource bundles into your application or you compile them into resource modules and load them at run time. If you compile the resources into the application, the compiler converts them to subclasses of the ResourceBundle class, and adds them to the application at compile time. If you compile the resources into resource modules, the compiler converts them to SWF files that you then load at run time on an as-needed basis.

For information on compiling and using resource modules, see Using resource modules.

Compile resources into the application on the command line

Specify one or more locales to compile the application for with the locale compiler option. The value of this option is used by the source-path option to find the resource properties files. The library-path option also uses this value to include localized framework resources.
Specify the location of the resources with the source-path option. You can add the resources for more than one locale by using the {locale} token.
Set the value of the allow-source-path-overlap compiler option to true. This is optional, but if you do not set it, you might get a warning that the source path for the locale is a subdirectory of the project's source path.

In the following example, the LocalizedForm.mxml application uses the resources for a single locale, en_US:

mxmlc -locale=en_US -source-path=c:\myapp\locale\{locale} -allow-source-path-overlap=true c:\myapp\LocalizedForm.mxml

In Adobe® Flex® Builder™, you add the resource directories to the project's source path, and then add additional compiler options. The source-path option tells the compiler where to look for additional source files such as properties files.

Add resource directories to the project's source path

Select Project > Properties.
Select the Source Path tab.
Click the Add Folder button. The Add Folder dialog box appears.
Navigate to the resource properties files' parent directory. Typically, you have locales in parallel directories under a parent directory such as /loc or /locale. For the en_US locale, you might have c:/myapp/loc/en_US directory. You will want to generalize the source path entry so that all locales are included. In this case, append {locale} to the end of the directory path. For example:
```
c:/myapp/loc/{locale}
```
This instructs the compiler to include all directories that match the {locale} token. In this case, en_US. If you add other locales, you only need to add them to the locale option and not the source path, as long as the new locale's resources are parallel to the existing locale's resources. For more information, see Adding new locales.
Click OK to add this directory to your project's source path.

You then add the locale and allow-source-path-overlap options to the Additional Compiler Arguments field on the Flex Compiler pane in the project's properties, as the following example shows:

-locale=en_US -allow-source-path-overlap=true

The locale option instructs the compiler which resource properties files to convert into resource bundles. By default, the en_US locale is supported. If you want to use other locales, you must also generate the framework resource bundles for those locales and that those locale's to the locale option. For more information, see Adding new locales.

The value of the locale option (in this case, en_US) is also used by the library-path option. If you specify multiple locales or change the locale, you will not be required to also change the library path.

The allow-source-path-overlap option lets you avoid a warning that the MXML compiler generates. You typically create a new subdirectory named locale under your project and then a subdirectory under that for each locale. You must explicitly add the locale directory to your source path. The directory where the application's MXML file is located is implicitly added to the source path. In the default Flex Builder project layout, this folder is the project directory and it is therefore the parent of the locale directory. By settings this option to true, you instruct the compiler not to warn you about overlapping values in the source path.

You can specify the locales in the flex-config.xml file by using the <locale> tag, as the following example shows:

<locale>
    <localeElement>en_US</localeElement>
</locale>

To add entries to your source path in the configuration file, you use the <source-path> child tag, as the following example shows:

<source-path>
    <path-element>locale/{locale}</path-element>
</source-path>

The <source-path> tag is commented out by default, so you must first uncomment the tag block.

Properties file syntax

Properties files are parsed as they are in Java. Each line typically takes the form of key=value. The following rules apply to properties files:

Lines in properties files are not terminated by semi-colons or other characters.
You can use an equals sign, a colon, or whitespace to separate the key from the value; for example:
```
key = value
key : value
key value
```
To add a comment to your properties file, start the line with a # or !. You can insert whitespace before the # or ! on a comment line. The following are examples of comments in a properties file:
```
! This is a comment.
# This is a comment.
```
Whitespace at the beginning of a value is stripped. Trailing whitespace is not stripped from the value.
You can use standard escape sequences such as \n (newline), \r (return), \t (tab), \u0020 (space), and \\ (backslash).
Backslash-space is an escape sequence for a space; for example, if a value starts with a space, you must write it as backslash-space or the compiler will interpret it as optional whitespace preceding the value. You are not required to escape spaces within a value. The following example starts the value with a space:
```
key =\ value
```
You can continue a line by ending it with a backslash. Leading whitespace on the next line is stripped.
Backslashes that are not part of an escape sequence are removed. For example, \A is just A.
You are not required to escape a double quote or a single quote.
You can use the parsing rules from Flex 2 if you set the compatibility-version compiler option to 2.0.1. For more information, see Backward compatibility.
Lines that contain only whitespace are ignored.

Adding new locales

To add new locales to your projects:

Add the locale to the locale compiler option. This is typically a comma-separated list, as the following example shows:
```
-locale=en_US,es_ES
```
In Flex builder, you add this in the Additional Compiler Arguments field of the Flex Compiler properties panel. If you edit the flex-config.xml file, you add locales by using the following syntax:
```
<locale>
    <locale-element>en_US</locale-element>
    <locale-element>es_ES</locale-element>
</locale>
```
Ensure that the new locale's resource properties files are in the source path. The source path entry for localized resources typically uses the {locale} token so that all new locales are automatically added to the source path, as long as those locales' resource directories have the same parent directory.
Create the framework resource bundles for the new locale.

The locale option defines what locales to include on the source path. It also instructs the compiler to include the localized framework resources for the specified locales. Framework components such as Label and Button use resources, just like your application and custom components can use resources. The resources required by these classes are located in the libraries like framework.swc or in separate resource bundle libraries. By default, framework resources for the en_US locale are included in the Flex SDK. If you add a locale to your Flex application, you must generate the framework resources for that locale.

To use the en_US locale, you do not need to do anything other than create properties files for your locale. For all other locales, such as ja_JP, fr_FR, or es_ES, in addition to creating the new properties files, you must also create new framework locale files before compiling your Flex application.

Typically, you begin adding a new locale by creating a new resource properties file. The following example specifies the values for a registration form's labels in Spanish:

# locale/es_ES/RegistrationForm.properties
registration_title=Registro
submit_button=Someta La Forma
personname=Nombre
street_address=Dirección De la Calle
city=Ciudad
state=Estado
zip=Código postal
thanks=¡Gracias por registrarse!

You create a separate properties files for each locale, and store it in a new directory under the locale directory in your project. You name the directory the same as the new locale. For example, if the locale is es_ES, then you store the new resources properties file in the locale/es_ES directory. If you have not already specified a source path, you add this resource directory to the source path as described in Compiling resources into Flex applications.

When adding other locales, you must also include the framework resources for that locale. The en_US locale is already provided. For all other locales, you must create the framework resources. To create a locale's framework resources, use the copylocale utility in the /sdk/bin directory. For Flex Builder, the copylocale utility is located in flex_builder_install/sdks/3.0.0/bin. You can only execute this utility from the command line.

The syntax for the copylocale utility is as follows:

copylocale original_locale new_locale

For example, to create the framework locale files for the es_ES locale, use the following command:

copylocale en_US es_ES

This utility creates a new directory under frameworks/locale/locale_name. The name of this directory matches the name of the new locale. This directory is parallel to the en_US directory. In this example, it creates the locale/es_ES directory. This utility also creates the following SWC files in the new directory:

airframework_rb.swc
framework_rb.swc
rpc_rb.swc

These resources must be in the library path. By default, the locale/{locale} entry is already set for your library-path compiler option, so you do not need to change any configuration options.

When you compile your application, and add the new locale to the locale option, the compiler includes the localized framework resources in the SWC files for that new locale.

About resource bundles

Resource bundles are classes that wrap resource properties files. They define the key/values pairs as properties of the class.

Flex includes resource bundles for the framework. They take the form of SWC files and are located in the frameworks/locale/locale directory. You can examine the framework resource properties files by extracting the contents of the SWC files in that directory and opening them in a text editor. For more information, see Editing framework resource properties.

For each resource properties file, the Flex compiler generates a class that extends the ResourceBundle class, and adds that class to the application. The name of the class is the name of the properties file, with an underscore replacing the period in the filename.

The generated ResourceBundle class overrides a single method, getContent(), which returns an object that defines the values in the properties file. For example, if you use the RegistrationForm.properties file, the compiler generates the following class:

public class RegistrationForm_properties extends ResourceBundle {
    override protected function getContent():Object {
        var properties:Object = {};
        properties["registration_button"] = "Registration";
        properties["submit_button"] = "Submit Form";
        properties["personname"] = "Name";
        properties["street"] = "Street Address";
        properties["city"] = "City";
        properties["state"] = "State";
        properties["zip"] = "ZIP Code";
        properties["thanks"] = "Thank you for registering!";
        return properties;
    }
}

To view the generated classes, you can set the keep-generated-actionscript compiler option to true when you compile your application with an existing resource properties file.

You can write your own classes that extend the ResourceBundle class rather than create resource properties files that the compiler then uses to generate the resource bundle classes. You can then use those classes if you include them in your project. For more information, see Creating resource bundles at run time.

Adobe Flex 3 Help

Creating resources

Compiling resources into Flex applications

Properties file syntax

Adding new locales

About resource bundles