Creating resources

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.

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.

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.

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.