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.
* See the documentation for mx.resources.IResourceBundle
* for information about how you typically create resource
* bundles from properties files.
A single ResourceManager object implementing the IResourceManager
* 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).
All classes that extend UIComponent, Formatter, or Validator
* have a resourceManager property
* that provides a reference to the object implementing this interface.
* Other classes can call ResourceManager.getInstance()
* to obtain this object.
Resource retrieval methods such as getString()
* search for resources in the locales specified
* by the localeChain property.
* By changing this property, you can make your application
* suddenly use, for example, Japanese rather than English resources.
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" which have only resources in them,
* and load them with the loadResourceModule() method
* of IResourceManager.
* 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.
[ "en_US" ],
* which specifies one or more locales to be searched for resources.
*
* When you call the ResourceManager methods getObject(),
* getString(), getStringArray(),
* getNumber(), getInt(),
* getUint(), getBoolean(), or
* getClass() to get the value of a resource,
* you specify a bundle name and a resource name,
* but not a locale.
* The ResourceManager starts with the first locale in the
* localeChain and looks for a ResourceBundle
* with the specified bundle name for that locale.
* If such a ResourceBundle exists, and the specified resource
* exists in it, then the value of that resource is returned.
* Otherwise, the ResourceManager proceeds on to the other
* locales in the localeChain.
This scheme makes it possible to have locales that do not
* necessarily contain a complete set of localized resources.
* For example, if you are localizing your application for
* Indian English rather than U.S. English, you need only
* supply resources for the en_IN locale in which the
* Indian spelling or usage differs from that in the U.S.,
* and then set the localeChain property
* to [ "en_IN", "en_US" ].
Many framework classes assume that they can always
* obtain, from some locale, the resources that they expect,
* and they will throw errors if they cannot do so.
* Therefore, you must ensure that the localeChain
* always contains a complete set of resources.
* Unless you have done a complete localization of all the
* framework's resources as well as your own application's
* resources, you can keep the "en_US" locale
* at the end of your localeChain to ensure this.
Setting this property causes the ResourceManager to dispatch
* a "change" Event.
Each call to this method returns a new event-dispatching object
* that you can use to learn how the loading is progressing
* and whether it completes successfully or results in an error.
* This object dispatches ResourceEvent.PROGRESS,
* ResourceEvent.COMPLETE, and
* ResourceEvent.ERROR events.
When the module has been loaded, the resource bundles
* are added to the ResourceManager, but the localeChain
* is left unchanged.
* If the update parameter is true,
* the update() method will be called.
update() method when the module finishes loading.
*
* @param applicationDomain The ApplicationDomain passed to the
* load() method of the IModuleInfo class
* that loads the resource module.
* This parameter is optional and defaults to null.
*
* @param securityDomain The SecurityDomain passed to the
* load() method of the IModuleInfo class
* that loads the resource module.
* This parameter is optional and defaults to null.
*
* @return An object that is associated with this particular load operation
* that dispatches ResourceEvent.PROGRESS,
* ResourceEvent.COMPLETE, and
* ResourceEvent.ERROR events.
*
* @see mx.events.ResourceEvent
* @see mx.resources.IResourceManager#update()
*
* @langversion 3.0
* @playerversion Flash 9
* @playerversion AIR 1.1
* @productversion Flex 3
*/
function loadResourceModule(url:String, update:Boolean = true,
applicationDomain:ApplicationDomain = null,
securityDomain:SecurityDomain = null):
IEventDispatcher;
/**
* Begins unloading a loaded resource module.
*
* When the module is unloaded, its resource bundles
* are removed from the ResourceManager, but the localeChain
* is left unchanged.
* If the update parameter is true,
* the update() method will be called.
update() method when the module finishes unloading.
*
* @langversion 3.0
* @playerversion Flash 9
* @playerversion AIR 1.1
* @productversion Flex 3
*/
function unloadResourceModule(url:String, update:Boolean = true):void;
/**
* Adds the specified ResourceBundle to the ResourceManager
* so that its resources can be accessed by ResourceManager
* methods such as getString().
*
* @param resourceBundle The resource bundle to be added.
* @param useWeakReference Determines if the ResourceManager
* keeps a weak reference to the resource bundle.
* If useWeakReference is true then the ResourceManager
* provides a weak reference to the resource bundle. When the
* caller chooses to use a weak reference it becomes the
* caller's responsibility to keep a hard reference the resource bundle
* so it is not garbaged collected prematurely. If useWeakReference is
* false, the ResourceManager keeps a hard reference to the resource
* bundle so it will not be garbage collected.
*
* When a Flex sub-application or module automatically adds its compiled
* resource bundles to the ResourceManager, it calls the addResourceBundle()
* with useWeakReference set to true, to avoid becoming pinned in memory.
* If you create resource bundles at runtime in a sub-application or
* module, you should do the same. You then need to hold on to these
* resource bundles with a hard reference to prevent them from being
* garbage collected.
getString().
*
* @param locale A locale string such as "en_US".
*
* @param bundleName A bundle name such as "MyResources".
*
* @see mx.resources.IResourceBundle
*
* @langversion 3.0
* @playerversion Flash 9
* @playerversion AIR 1.1
* @productversion Flex 3
*/
function removeResourceBundle(locale:String, bundleName:String):void;
/**
* Removes all ResourceBundles for the specified locale
* from the ResourceManager so that their resources
* can no longer be accessed by ResourceManager methods
* such as getString().
*
* @param locale A locale string such as "en_US".
*
* @see mx.resources.IResourceBundle
*
* @langversion 3.0
* @playerversion Flash 9
* @playerversion AIR 1.1
* @productversion Flex 3
*/
function removeResourceBundlesForLocale(locale:String):void;
/**
* Dispatches a change event from the
* ResourceManager.
*
* This causes binding expressions to re-evaluate
* if they involve the ResourceManager methods
* getObject(), getString(),
* getStringArray(), getNumber(),
* getInt(), getUint(),
* getBoolean(), or getClass().
This also causes the resourcesChanged() method
* of a UIComponent, Formatter, or Validator to execute.
* Many components implement this method to update
* their state based on the latest resources.
The order of locales in this array is not specified.
* * @return An Array of locale Strings. * * @langversion 3.0 * @playerversion Flash 9 * @playerversion AIR 1.1 * @productversion Flex 3 */ function getLocales():Array /* of String */; /** * Returns an Array of Strings specifying all locales for which * ResourceBundle objects exist in the ResourceManager, * ordered using user preferences as reported by *Capabilities.language or
* Capabilities.languages.
*
* @return An Array of locale Strings.
*
* @langversion 3.0
* @playerversion Flash 9
* @playerversion AIR 1.1
* @productversion Flex 3
*/
function getPreferredLocaleChain():Array /* of String */;
/**
* Returns an Array of Strings specifying the bundle names
* for all ResourceBundle objects that exist in the ResourceManager
* and that belong to the specified locale.
*
* The order of bundle names in this Array is not specified.
* * @param locale A locale string such as"en_US".
*
* @return An Array of bundle names.
*
* @see mx.resources.IResourceBundle
*
* @langversion 3.0
* @playerversion Flash 9
* @playerversion AIR 1.1
* @productversion Flex 3
*/
function getBundleNamesForLocale(locale:String):Array /* of String */;
/**
* Returns a ResourceBundle with the specified locale
* and bundleName that has been previously added
* to the ResourceManager with addResourceBundle().
* If no such ResourceBundle exists, this method returns null.
*
* @param locale A locale string such as "en_US".
*
* @param bundleName A bundle name such as "MyResources".
*
* @return The ResourceBundle with the specified locale
* and bundleName if one exists; otherwise null.
*
* @see mx.resources.IResourceBundle
*
* @langversion 3.0
* @playerversion Flash 9
* @playerversion AIR 1.1
* @productversion Flex 3
*/
function getResourceBundle(locale:String,
bundleName:String):IResourceBundle;
/**
* Searches the locales in the localeChain
* for the specified resource and returns
* the first resource bundle in which it is found.
* If the resource isn't found, this method returns null.
*
* @param bundleName A bundle name such as "MyResources".
*
* @param resourceName The name of a resource in the resource bundle.
*
* @return The first ResourceBundle in the localeChain
* that contains the specified resource, or null.
*
* @langversion 3.0
* @playerversion Flash 9
* @playerversion AIR 1.1
* @productversion Flex 3
*/
function findResourceBundleWithResource(
bundleName:String,
resourceName:String):IResourceBundle;
[Bindable("change")]
/**
* Gets the value of a specified resource as an Object.
*
* The value is returned exactly as it is stored
* in the content Object of the ResourceBundle,
* with no conversion.
* If the resource was compiled from a properties files,
* the resource value in the content Object
* is always a String unless you used the Embed()
* or ClassReference() directive, in which case
* it is a Class.
* Use the getString(), getStringArray(),
* getNumber(), getInt()
* getUint(), getBoolean(), and
* getClass() methods to convert the value
* to more specific types.
If the specified resource is not found,
* this method returns undefined.
null to search all locales
* in the localeChain.
* This parameter is optional and defaults to null;
* you should seldom need to specify it.
*
* @return The resource value, exactly as it is stored
* in the content Object,
* or undefined if the resource is not found.
*
* @langversion 3.0
* @playerversion Flash 9
* @playerversion AIR 1.1
* @productversion Flex 3
*/
function getObject(bundleName:String, resourceName:String,
locale:String = null):*;
[Bindable("change")]
/**
* Gets the value of a specified resource as a String,
* after substituting specified values for placeholders.
*
* This method calls getObject()
* and then casts the result to a String.
If a parameters Array is passed to this method,
* the parameters in it are converted to Strings
* and then substituted, in order, for the placeholders
* "{0}", "{1}", and so on, in the String
* before it is returned.
If the specified resource is not found,
* this method returns null.
toString() method
* before being substituted.
*
* @param locale A specific locale to be used for the lookup,
* or null to search all locales
* in the localeChain.
* This parameter is optional and defaults to null;
* you should seldom need to specify it.
*
* @return The resource value, as a String,
* or null if it is not found.
*
* @langversion 3.0
* @playerversion Flash 9
* @playerversion AIR 1.1
* @productversion Flex 3
*/
function getString(bundleName:String, resourceName:String,
parameters:Array = null,
locale:String = null):String;
[Bindable("change")]
/**
* Gets the value of a specified resource as an Array of Strings.
*
* This method assumes that the resource value is a String
* containing a comma-separated list of items.
* It calls the getString() method, splits the String
* into items at the commas, and trims white space
* before and after each item.
* It is useful if you have written a line such as:
* COUNTRIES=India, China, Japan
*
*
* in a properties file and you want to obtain the value
* [ "India", "China", "Japan" ]
* rather than the value "India, China, Japan".
If the specified resource is not found,
* this method returns null.
null to search all locales
* in the localeChain.
* This parameter is optional and defaults to null;
* you should seldom need to specify it.
*
* @return The resource value, as an Array of Strings,
* or null if it is not found.
*
* @langversion 3.0
* @playerversion Flash 9
* @playerversion AIR 1.1
* @productversion Flex 3
*/
function getStringArray(bundleName:String,
resourceName:String,
locale:String = null):Array /* of String */;
[Bindable("change")]
/**
* Gets the value of a specified resource as a Number.
*
* This method calls getObject()
* and casts the result to a Number.
* It is useful if you have written a line such as:
* LONGITUDE=170.3
*
*
* in a properties file and want to obtain the value
* 170.3 rather than "170.3".
If the specified resource is not found,
* this method returns NaN.
null to search all locales
* in the localeChain.
* This parameter is optional and defaults to null;
* you should seldom need to specify it.
*
* @return The resource value, as a Number,
* or NaN if it is not found.
*
* @langversion 3.0
* @playerversion Flash 9
* @playerversion AIR 1.1
* @productversion Flex 3
*/
function getNumber(bundleName:String, resourceName:String,
locale:String = null):Number;
[Bindable("change")]
/**
* Gets the value of a specified resource as an int.
*
* This method calls getObject()
* and casts the result to an int.
* It is useful if you have written a line such as:
* MINIMUM=5
*
*
* in a properties file and want to obtain the value
* 5 rather than "5".
If the specified resource is not found, * this method returns 0.
* * @param bundleName The name of a resource bundle. * * @param resourceName The name of a resource in the resource bundle. * * @param locale A specific locale to be used for the lookup, * ornull to search all locales
* in the localeChain.
* This parameter is optional and defaults to null;
* you should seldom need to specify it.
*
* @return The resource value, as an int,
* or 0 if it is not found.
*
* @langversion 3.0
* @playerversion Flash 9
* @playerversion AIR 1.1
* @productversion Flex 3
*/
function getInt(bundleName:String, resourceName:String,
locale:String = null):int;
[Bindable("change")]
/**
* Gets the value of a specified resource as a uint.
*
* This method calls the getObject() method
* and casts the result to a uint.
* It is useful if you have written a line such as:
* MINIMUM=5
*
*
* in a properties file and want to obtain the value
* 5 rather than "5".
If the specified resource is not found, * this method returns 0.
* * @param bundleName The name of a resource bundle. * * @param resourceName The name of a resource in the resource bundle. * * @param locale A specific locale to be used for the lookup, * ornull to search all locales
* in the localeChain.
* This parameter is optional and defaults to null;
* you should seldom need to specify it.
*
* @return The resource value, as a uint,
* or 0 if it is not found.
*
* @langversion 3.0
* @playerversion Flash 9
* @playerversion AIR 1.1
* @productversion Flex 3
*/
function getUint(bundleName:String, resourceName:String,
locale:String = null):uint;
[Bindable("change")]
/**
* Gets the value of a specified resource as a Boolean.
*
* This method first calls getString()
* and converts the result to lowercase.
* It then returns true
* if the result was "true".
* and false otherwise.
If the specified resource is not found,
* this method returns false.
null to search all locales
* in the localeChain.
* This parameter is optional and defaults to null;
* you should seldom need to specify it.
*
* @return The resource value, as a Boolean,
* or false if it is not found.
*
* @langversion 3.0
* @playerversion Flash 9
* @playerversion AIR 1.1
* @productversion Flex 3
*/
function getBoolean(bundleName:String, resourceName:String,
locale:String = null):Boolean;
[Bindable("change")]
/**
* Gets the value of a specified resource as a Class.
*
* This method calls getObject()
* and coerces it to type Class using the as operator.
* The result will be null if the resource value
* was not a class reference.
* It is useful if you have written a lines such as
* IMAGE=Embed("image.jpg")
* BUTTON_SKIN=ClassReference("skins.ButtonSkin_en_US")
*
*
* in a properties file and want to obtain
* the Class that the Embed()
* or ClassReference() directive produced.
If the specified resource is not found,
* this method returns null.
null to search all locales
* in the localeChain.
* This parameter is optional and defaults to null;
* you should seldom need to specify it.
*
* @return The resource value, as a Class,
* or null if it is not found.
*
* @langversion 3.0
* @playerversion Flash 9
* @playerversion AIR 1.1
* @productversion Flex 3
*/
function getClass(bundleName:String, resourceName:String,
locale:String = null):Class;
/**
* Creates instances of all ResourceBundle subclasses that were compiled into the SWF
* and adds them to the ResourceManager.
*
* For example, if the locales parameter is [ "en_US", "ja_JP" ]
* and the bundleNames parameter is [ "core", "controls" ],
* then four resource bundles will be installed.
This method is used only by classes that implement the IFlexModuleFactory interface.
* * @param applicationDomain The ApplicationDomain that is used to look up the resource bundle * classes by name. * * @param locales An Array of Strings that specify the locales for which the SWF was compiled. * * @param bundleNames An Array of Strings that specify the names of the resource bundles * that were compiled into the SWF. * * @param useWeakReference A flag that specifyies whether the resource bundles should be * intalled into the ResourceManager using a weak reference. * * @return An Array of the ResourceBundle instances that were created * and added to the ResourceManager. * * @see mx.core.IFlexModuleFactory * * @langversion 3.0 * @playerversion Flash 9 * @playerversion AIR 1.1 * @productversion Flex 3 */ function installCompiledResourceBundles( applicationDomain:ApplicationDomain, locales:Array /* of String */, bundleNames:Array /* of String */, useWeakReference:Boolean = false):Array; /** * Initializes thelocaleChain property of the ResourceManager
* using an algorithm that compares the operating system's list of user-preferred
* locales with the list of locales available in the SWF.
*
* For example, if the user has indicated in the operating system that she
* prefers French, and the SWF was compiled for the locales en_US, fr_FR, and de_DE,
* then the localeChain will be set so that the first locale in it
* is fr_FR.
This method is used only by classes that implement the IFlexModuleFactory interface.
* * @param compiledLocales An Array of Strings specifying the locales * for which the SWF was compiled. * * @see mx.core.IFlexModuleFactory * * @langversion 3.0 * @playerversion Flash 9 * @playerversion AIR 1.1 * @productversion Flex 3 */ function initializeLocaleChain(compiledLocales:Array):void; } }