//////////////////////////////////////////////////////////////////////////////// // // Licensed to the Apache Software Foundation (ASF) under one or more // contributor license agreements. See the NOTICE file distributed with // this work for additional information regarding copyright ownership. // The ASF licenses this file to You under the Apache License, Version 2.0 // (the "License"); you may not use this file except in compliance with // the License. You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // //////////////////////////////////////////////////////////////////////////////// package mx.resources { /** * The IResourceBundle and IResourceManager interfaces work together * to provide localization support for Flex applications. * *

There are three main concepts involved in localization: * locales, resources, and resource bundles.

* *

A locale specifies a language and a country * for which your application has been localized. * For example, the locale "en_US" * specifies English as spoken in the United States. * (See the mx.resources.Locale class for more information.)

* *

A resource is a named value that is locale-dependent. * For example, your application might have a resource * whose name is "OPEN" * and whose value for an English locale is "Open" * but whose value for a French locale is "Ouvrir".

* *

A resource bundle is a named group of resources * whose values have been localized for a particular locale. * A resource bundle is identified by the combination of its * bundleName and its locale, * and has a content Object that contains * the name-value pairs for the bundle's resources.

* *

The IResourceBundle interface represents a specific resource bundle. * However, most applications will only need to use IResourceManager. * A single ResourceManager object implementing this interface * manages multiple resource bundles, possibly for multiple locales, * and provides access to the resources that they contain. * For example, you can retrieve a specific resource as a String by calling * resourceManager.getString(bundleName, resourceName). * By changing the localeChain property of the ResourceManager, * you can change which resource bundles are searched for resource values.

* *

Generally, you do not create resource bundles yourself; * instead, they are usually compiled from ~~.properties files. * A properties file named MyResources.properties * produces a resource bundle with "MyResources" * for its bundleName. * You generally produce multiple versions of each properties file, * one for each locale that your application supports.

* *

Flex properties files are similar to Java properties files, * except that they also support MXML's Embed() * and ClassReference() directives. * These directives work the same way in a properties file * as they do in a CSS file, producing class references. * Also, the encoding for Flex properties files * is always assumed to be UTF-8.

* *

The Flex framework's resources have been localized * for U.S. English (the "en_US" locale) and * for Japanese (the "ja_JP" locale). * The framework resources are organized into multiple bundles * corresponding to framework packages; for example, the "formatters" * bundle is used by classes in the mx.formatters package. * (There is also a "SharedResources" bundle for resources used by * multiple packages.)

* *

The properties files for the framework resources, * such as formatters.properties, can be found in the * frameworks/projects/framework/bundles/{locale}/src directories * of the Flex SDK. * Your applications normally link against the Flex framework * as a precompiled library, framework.swc, * in the frameworks/libs directory. * This library has no resources in it. * Instead, the framework resources have been compiled into separate * resource bundle libraries such as framework_rb.swc. * These are located in the frameworks/locales/{locale} directories * and your application must also link in one or more of these.

* *

You are free to organize your application's own resources * into whatever bundles you find convenient. * If you localize your application for locales * other than "en_US" and "ja_JP", * you should localize the framework's properties files for those locales * as well and compile additional resource bundle libaries for them.

* *

When your application starts, the ResourceManager is automatically * populated with whatever resource bundles were compiled * into the application. * If you create a code module, by default the resources that its classes * need are compiled into the module. * When the module is loaded into an application, any bundles that the * application does not already have are added to the ResourceManager.

* *

You can compile "resource modules" that have only resources in them, * and load them with the loadResourceModule() method * of the ResourceManager. * With resource modules, you can support multiple locales by loading * the resources you need at run time rather than compiling them into * your application.

* *

Although the ResourceManager is normally populated with resource bundles * that were compiled into your application or loaded from modules, * you can also programmatically create resource bundles and add them * to the ResourceManager yourself with the addResourceBundle() * method.

* * @see mx.resources.ResourceBundle * @see mx.resources.IResourceManager * @see mx.resources.ResourceManager * * @langversion 3.0 * @playerversion Flash 9 * @playerversion AIR 1.1 * @productversion Flex 3 */ public interface IResourceBundle { //-------------------------------------------------------------------------- // // Properties // //-------------------------------------------------------------------------- //---------------------------------- // bundleName //---------------------------------- /** * A name that identifies this resource bundle, * such as "MyResources". * *

This read-only property is set * when a resource bundle is constructed.

* *

Resource bundles that are automatically created from compiled * properties files have bundle names based on the names of those files. * For example, a properties file named MyResources.properties * will produce a resource bundle whose bundleName * is "MyResources".

* *

The ResourceManager can manage multiple bundles with the same * bundleName as long as they have different values * for their locale property.

* * @langversion 3.0 * @playerversion Flash 9 * @playerversion AIR 1.1 * @productversion Flex 3 */ function get bundleName():String; //---------------------------------- // content //---------------------------------- /** * An object containing key-value pairs for the resources * in this resource bundle. * *

In general, you should access resources by using IResourceManager * methods such as getString(), rather than directly * accessing them in a resource bundle. * However, if you are programmatically creating your own * resource bundles, you can initialize them with resources, * as follows:

* * 
     *  var rb:IResourceBundle = new ResourceBundle("fr_FR", "MyResources");
     *  rb.content["LANGUAGE"] = "Francais";
     *  rb.content["GREETING"] = "Bonjour";
     *
* *

When a resource bundle is produced by compiling a properties * file, its resource values are either of type String or Class. * For example, if the properties file contains

* * 
     *  LANGUAGE=English
     *  MINIMUM_AGE=18
     *  ENABLED=true
     *  LOGO=Embed("logo.png")
     *
* *

then the value of the LANGUAGE resource * is the String "English", * the value of the MINIMUM_AGE resource * is the String "18", * the value of the ENABLED resource * is the String "true", * and the value of the LOGO resource * is a Class that represents the embedded PNG file.

* *

You can use IResourceManager methods such as getInt() * and getBoolean() to convert resource strings like * "18" and "true" into the type * that your code expects.

* * @langversion 3.0 * @playerversion Flash 9 * @playerversion AIR 1.1 * @productversion Flex 3 */ function get content():Object; //---------------------------------- // locale //---------------------------------- /** * The locale for which this bundle's resources have been localized. * This is a String such as "en_US" for U.S. English. * *

This read-only property is set * when a resource bundle is constructed.

* *

Resource bundles that are automatically created from compiled * properties files have locales based on the * -compiler.locale option of the mxmlc or compc compilers. * For example, suppose that you compile your application with the option * -compiler.locale=en_US,ja_JP and that you have specified * -compiler.source-path=resources/{locale} so that * your application's resources, located in * resources/en_US/MyResources.properties and * resources/ja_JP/MyResources.properties, are found. * Then your application will have two resource bundles * whose bundleName is "MyResources", * one whose locale is "en_US" * and one whose locale is "ja_JP".

* * @langversion 3.0 * @playerversion Flash 9 * @playerversion AIR 1.1 * @productversion Flex 3 */ function get locale():String; } }