Creating resources

You define resource bundles in resource properties files. These properties files contain key/value pairs and are in UTF-8 format. You commonly 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 embed binary assets such as audio files, video files, SWF files, and images. To embeds 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 MySorter class in the sortingClasses.en_US package:

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

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

You typically store resource properties files in a locale/locale_name subdirectory. You add this directory to your source path so that the compiler can find it when you compile your application, and append the locale to the locale compiler option. 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 ResourceBundleclass, 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

  1. 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.

  2. 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.

  3. 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 a custom resource bundle 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® Flash® 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 in Flash Builder

  1. Select Project > Properties.

  2. Select the Source Path tab.

  3. Click the Add Folder button. The Add Folder dialog box appears.

  4. 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.

  5. 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, all locales listed under the framework/bundles directory are supported (including en_US, de_DE, ru_RU, and ja_JP). If you want to use resource bundles for other locales, you must also generate the framework resource bundles for those locales and add 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 Flash Builder project layout, this folder is the project directory and it is therefore the parent of the locale directory. By settings the allow-source-path-overlap 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.

  • Lines that contain only whitespace are ignored.

Adding new locales

To add new locales to your projects:

  1. 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 Flash 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>
  2. 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.

  3. Create the framework resource bundles for the new locale, if the framework resource bundles do not already exist. You can see a list of the supported bundles by looking at the directory list under framework/bundles. The supported list includes en_US, ja_JP, fr_FR, ru_RU, and es_ES.

The locale option defines what locale’s resources 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 many common locales are included in the Flex SDK.

To use any supported locale, you do not need to do anything other than create properties files for your locale. For locales that are not included, such as en_IN, in addition to creating the new properties files, you must also create new framework locale files before compiling your Flex application.

To create a locale’s framework resources, use the copylocale utility in the /sdk/bin directory. For Flash Builder, the copylocale utility is located in flash_builder_install/sdks/4.6.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 en_IN locale, use the following command:

copylocale en_US en_IN

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 other locale directories. In this example, it creates the locale/en_IN directory. This utility also creates SWC files in the new directory, including the framework_rb.swc and rpc_rb.swc files.

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 the ResourceBundle class

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.