| Package | fl.lang |
| Class | public class Locale |
| Inheritance | Locale  EventDispatcher Object |
| Language Version: | ActionScript 3.0 |
| Product Version: | Flash CS3 |
| Runtime Versions: | Flash Player 9, AIR 1.0 |
-
"automatically at runtime"—Flash Player replaces string IDs with strings from the XML file matching the default system language code returned by flash.system.capabilities.language. -
"manually using stage language"—String IDs are replaced by strings at compile time and cannot be changed by Flash Player. -
"via ActionScript at runtime"—String ID replacement is controlled using ActionScript at runtime. This option gives you control over both the timing and language of string ID replacement.
You can use the properties and methods of this class when you want to replace the string IDs "via ActionScript at runtime."
All of the properties and methods available are static, which means that they are accessed through the fl.lang.Locale class itself rather than through an instance of the class.
Note: The Locale class is installed in the Flash Authoring classpath and is automatically compiled into your SWF files. Using the Locale class increases the SWF file size slightly since the class is compiled into the SWF.
Related API Elements
Public Properties
Hide Inherited Public Properties
Show Inherited Public Properties| Property | Defined By | ||
|---|---|---|---|
| autoReplace : Boolean [static]
Determines whether strings are replaced automatically after loading the XML file. | Locale | ||
 | constructor : Object
A reference to the class object or constructor function for a given object instance. | Object | |
| languageCodeArray : Array [static] [read-only]
An array containing language codes for the languages that have been specified or loaded into the FLA file. | Locale | ||
| prototype : Object [static]
A reference to the prototype object of a class or function object. | Object | |
| stringIDArray : Array [static] [read-only]
An array containing all the string IDs in the FLA file. | Locale | ||
Public Methods
| Method | Defined By | ||
|---|---|---|---|
[static]
Adds the {instance, string ID} pair into the internal array for later use. | Locale | ||
| addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void
Registers an event listener object with an EventDispatcher object so that the listener
receives notification of an event. | EventDispatcher | |
[static]
Adds the {languageCode and languagePath} pair into the internal array for later use. | Locale | ||
[static]
Returns true if the XML file is loaded; false otherwise. | Locale | ||
|
Dispatches an event into the event flow. | EventDispatcher | |
[static]
The default language code as set in the Strings panel dialog box or by calling the setDefaultLang() method. | Locale | ||
|
Checks whether the EventDispatcher object has any listeners registered for a specific type
of event. | EventDispatcher | |
|
Indicates whether an object has a specified property defined. | Object | |
[static]
Automatically determines the language to use and loads the XML language file. | Locale | ||
|
Indicates whether an instance of the Object class is in the prototype chain of the object specified
as the parameter. | Object | |
[static]
Loads the specified XML language file. | Locale | ||
[static]
Returns the string value associated with the given string ID in the current language. | Locale | ||
[static]
Returns the string value associated with the given string ID and language code. | Locale | ||
|
Indicates whether the specified property exists and is enumerable. | Object | |
|
Removes a listener from the EventDispatcher object. | EventDispatcher | |
[static]
Sets the default language code. | Locale | ||
[static]
Sets the callback function that is called after the XML file is loaded. | Locale | ||
|
Sets the availability of a dynamic property for loop operations. | Object | |
[static]
Sets the new string value of a given string ID and language code. | Locale | ||
|
Returns the string representation of this object, formatted according to locale-specific conventions. | Object | |
|
Returns the string representation of the specified object. | Object | |
|
Returns the primitive value of the specified object. | Object | |
|
Checks whether an event listener is registered with this EventDispatcher object or any of
its ancestors for the specified event type. | EventDispatcher | |
Property Detail
autoReplace | property |
autoReplace:Boolean| Language Version: | ActionScript 3.0 |
| Product Version: | Flash CS3 |
| Runtime Versions: | Flash Player 9, AIR 1.0 |
Determines whether strings are replaced automatically after loading the XML file. If set to true, the text
replacement method is equivalent to the Strings panel setting "automatically at runtime". This means that Flash Player
will determine the default language of the host environment and automatically display the text in that language. If set to
false, the text replacement method is equivalent to the Strings panel setting "via ActionScript at runtime".
This means that you are responsible for loading the appropriate XML file to display the text.
The default value of this property reflects the setting that you select for Replace strings in the Strings panel dialog box:
true for "automatically at runtime" (the default setting) and false for "via ActionScript at
runtime".
Implementation
public static function get autoReplace():Boolean public static function set autoReplace(value:Boolean):voidExample ( How to use this example )
The following example uses the
Locale.autoReplace property to populate the dynamically created
greeting_txt text field on the Stage with the contents of the IDS_GREETING string in the English XML file. In
the Strings panel, click the Settings button to open the Settings dialog box. You can add two active languages using the Settings
dialog box: English (en) and French (fr), set the replacement strings radio option to "via ActionScript at runtime",
and click OK. Finally, enter a string ID of IDS_GREETING in the Strings panel, and add text for each active language.
var greeting_txt:TextField = new TextField();
greeting_txt.x = 40;
greeting_txt.y = 40;
greeting_txt.width = 200;
greeting_txt.height = 20;
greeting_txt.autoSize = TextFieldAutoSize.LEFT;
Locale.autoReplace = true;
Locale.addDelayedInstance(greeting_txt, "IDS_GREETING");
Locale.loadLanguageXML("en");
languageCodeArray | property |
languageCodeArray:Array [read-only] | Language Version: | ActionScript 3.0 |
| Product Version: | Flash CS3 |
| Runtime Versions: | Flash Player 9, AIR 1.0 |
An array containing language codes for the languages that have been specified or loaded into the FLA file. The language codes are not sorted alphabetically.
Implementation
public static function get languageCodeArray():ArrayExample ( How to use this example )
The following example loads a language XML file based on the current value of a ComboBox component. You drag a ComboBox component onto the Stage and give it an instance name of
lang_cb. Using the Text tool, you create a dynamic text field and give it an instance name of greeting_txt. In the Strings panel, you add at least two active languages, set the replace strings radio option to "via ActionScript at runtime", and click OK. Next, you add a string ID of IDS_GREETING and enter text for each active language. Finally, you add the following ActionScript code to Frame 1 of the main Timeline:
Locale.setLoadCallback(localeListener);
lang_cb.dataProvider = Locale.languageCodeArray.sort();
lang_cb.addEventListener("change", langListener);
function langListener(eventObj:Object):void {
Locale.loadLanguageXML(eventObj.target.value);
}
function localeListener(success:Boolean):void {
if (success) {
greeting_txt.text = Locale.loadString("IDS_GREETING");
} else {
greeting_txt.text = "unable to load language XML file.";
}
}
stringIDArray | property |
stringIDArray:Array [read-only] | Language Version: | ActionScript 3.0 |
| Product Version: | Flash CS3 |
| Runtime Versions: | Flash Player 9, AIR 1.0 |
An array containing all the string IDs in the FLA file. The string IDs are not sorted alphabetically.
Implementation
public static function get stringIDArray():ArrayExample ( How to use this example )
The following example traces the
Locale.stringIDArray property for the currently loaded language XML file.
Click the Settings button in the Strings panel to open the Settings dialog box. Next, you add two active languages: English (en) and
French (fr), set the replace strings radio control to "via ActionScript at runtime", and click OK. In the Strings
panel, you add a string ID of IDS_GREETING, and then add text for each active language.
Locale.setLoadCallback(localeCallback);
Locale.loadLanguageXML("fr");
function localeCallback(success:Boolean) {
trace(success);
trace(Locale.stringIDArray); // IDS_GREETING
trace(Locale.loadStringEx("IDS_GREETING", "fr")); // bonjour
}
Method Detail
addDelayedInstance | () | method |
public static function addDelayedInstance(instance:Object, stringID:String):*| Language Version: | ActionScript 3.0 |
| Product Version: | Flash CS3 |
| Runtime Versions: | Flash Player 9, AIR 1.0 |
Adds the {instance, string ID} pair into the internal array for later use.
This is primarily used by Flash when the strings replacement method is "automatically at runtime".
Parameters
instance:Object — Instance name of the text field to populate.
| |
stringID:String — Language string ID.
|
* |
Example ( How to use this example )
The following example uses the
autoReplace property and addDelayedInstance() method to populate
a text field on the Stage with the IDS_GREETING string from the English XML language file.
greeting_txt.autoSize = TextFieldAutoSize.LEFT;
Locale.autoReplace = true;
Locale.addDelayedInstance(greeting_txt, "IDS_GREETING");
Locale.loadLanguageXML("en");
addXMLPath | () | method |
public static function addXMLPath(langCode:String, path:String):void| Language Version: | ActionScript 3.0 |
| Product Version: | Flash CS3 |
| Runtime Versions: | Flash Player 9, AIR 1.0 |
Adds the {languageCode and languagePath} pair into the internal array for later use.
This is primarily used by Flash Player when the string's replacement method is "automatically at runtime"
or "via ActionScript at runtime". This method allows you to load XML language files from a custom location
instead of the default location set up by Flash Professional. By default, Flash Professional creates an XML file for each
language in your working directory, under a subdirectory named using your FLA file's name.
Parameters
langCode:String — The language code.
| |
path:String — The XML path to add.
|
Example ( How to use this example )
The following example tells Flash Player that the English ("en") translations are found in the file
"locale/locale_en.xml" file and French ("fr") translations are in the "locale/locale_fr.xml" file relative to your working
directory (example and description provided by Chris Inch, from
http://www.chrisinch.com):
Locale.addXMLPath("en", "locale/locale_en.xml");
Locale.addXMLPath("fr", "locale/locale_fr.xml");
Locale.setLoadCallback(Delegate.create(this, languageLoaded));
Locale.loadLanguageXML("en");
private function languageLoaded(success:Boolean):Void {
trace(Locale.loadString("IDS_HELLO");
checkXMLStatus | () | method |
public static function checkXMLStatus():Boolean| Language Version: | ActionScript 3.0 |
| Product Version: | Flash CS3 |
| Runtime Versions: | Flash Player 9, AIR 1.0 |
Returns true if the XML file is loaded; false otherwise.
Boolean — Returns true if the XML file is loaded; false otherwise.
|
Example ( How to use this example )
The following example uses an interval to check every 10 milliseconds to see if the language file has successfully
loaded. Once the XML file has loaded, the
greeting_txt text field instance on the Stage is populated with the
IDS_GREETING string from the language XML file.
Locale.setLoadCallback(localeCallback);
Locale.loadLanguageXML("en");
// create interval to check if language XML file is loaded
var locale_int:Number = setInterval(checkLocaleStatus, 10);
function checkLocaleStatus():void {
if (Locale.checkXMLStatus()) {
clearInterval(locale_int);
trace("clearing interval @ " + getTimer() + " ms");
}
}
// callback function for Locale.setLoadCallback()
function localeCallback(success:Boolean):void {
greeting_txt.text = Locale.loadString("IDS_GREETING");
}
getDefaultLang | () | method |
public static function getDefaultLang():String| Language Version: | ActionScript 3.0 |
| Product Version: | Flash CS3 |
| Runtime Versions: | Flash Player 9, AIR 1.0 |
The default language code as set in the Strings panel dialog box or by calling the setDefaultLang() method.
String — Returns the default language code.
|
Related API Elements
Example ( How to use this example )
The following example creates a variable called
defLang, which is used to hold the initial default language
for the Flash document. You click the Settings button in the Strings panel to launch the Settings dialog box. Then you add two active
languages: English (en) and French (fr), set the replace strings radio control to "via ActionScript at runtime", and
click OK. In the Strings panel, you add a string ID of IDS_GREETING, and then add text for each active language.
var defLang:String = "fr";
Locale.setDefaultLang(defLang);
Locale.setLoadCallback(localeCallback);
Locale.loadLanguageXML(Locale.getDefaultLang());
function localeCallback(success:Boolean) {
if (success) {
trace(Locale.stringIDArray); // IDS_GREETING
trace(Locale.loadString("IDS_GREETING"));
} else {
trace("unable to load XML");
}
}
initialize | () | method |
public static function initialize():void| Language Version: | ActionScript 3.0 |
| Product Version: | Flash CS3 |
| Runtime Versions: | Flash Player 9, AIR 1.0 |
Automatically determines the language to use and loads the XML language file.
This is primarily used by Flash when the strings replacement method is "automatically at runtime".
Example ( How to use this example )
This example shows how to use the
initialize() method to automatically populate the greeting_txt
text field on the Stage with the user's current OS language. Instead of using the initialize() method directly,
use the string replacement method of "automatically at runtime".
trace(System.capabilities.language);
Locale.autoReplace = true;
Locale.addDelayedInstance(greeting_txt, "IDS_GREETING");
Locale.initialize();
loadLanguageXML | () | method |
public static function loadLanguageXML(xmlLanguageCode:String, customXmlCompleteCallback:Function = null):void| Language Version: | ActionScript 3.0 |
| Product Version: | Flash CS3 |
| Runtime Versions: | Flash Player 9, AIR 1.0 |
Loads the specified XML language file.
Parameters
xmlLanguageCode:String — The language code for the XML language file that you want to load.
| |
customXmlCompleteCallback:Function (default = null) |
Example ( How to use this example )
The following example uses the
loadLanguageXML() method to load the English (en) XML language file. Once the
language file loads, the localeCallback() method is called and populates the greeting_txt text field on
the Stage with the contents of the IDS_GREETING string in the XML file.
Locale.setLoadCallback(localeCallback);
Locale.loadLanguageXML("en");
// create interval to check if language XML file is loaded
var locale_int:Number = setInterval(checkLocaleStatus, 10);
function checkLocaleStatus():void {
if (Locale.checkXMLStatus()) {
clearInterval(locale_int);
trace("clearing interval @ " + getTimer() + " ms");
}
}
// callback function for Locale.setLoadCallback()
function localeCallback(success:Boolean):void {
greeting_txt.text = Locale.loadString("IDS_GREETING");
}
loadString | () | method |
public static function loadString(id:String):String| Language Version: | ActionScript 3.0 |
| Product Version: | Flash CS3 |
| Runtime Versions: | Flash Player 9, AIR 1.0 |
Returns the string value associated with the given string ID in the current language.
Parameters
id:String — The identification (ID) number of the string to load.
|
String — The string value associated with the given string ID in the current language.
|
Related API Elements
Example ( How to use this example )
The following example uses an interval to check every 10 milliseconds to see if the language file has successfully
loaded. Once the XML file has loaded, the
greeting_txt text field instance on the Stage is populated with the
IDS_GREETING string from the XML language file.
Locale.setLoadCallback(localeCallback);
Locale.loadLanguageXML("en");
// create interval to check if language XML file is loaded
var locale_int:Number = setInterval(checkLocaleStatus, 10);
function checkLocaleStatus():void {
if (Locale.checkXMLStatus()) {
clearInterval(locale_int);
trace("clearing interval @ " + getTimer() + " ms");
}
}
// callback function for Locale.setLoadCallback()
function localeCallback(success:Boolean):void {
greeting_txt.text = Locale.loadString("IDS_GREETING");
}
loadStringEx | () | method |
public static function loadStringEx(stringID:String, languageCode:String):String| Language Version: | ActionScript 3.0 |
| Product Version: | Flash CS3 |
| Runtime Versions: | Flash Player 9, AIR 1.0 |
Returns the string value associated with the given string ID and language code.
To avoid unexpected XML file loading, loadStringEx() does not load the XML language file if the XML file is not
already loaded. You should decide on the right time to call the loadLanguageXML() method if you want to load a XML
language file.
Parameters
stringID:String — The identification (ID) number of the string to load.
| |
languageCode:String — The language code.
|
String — The string value associated with the given string ID in the language specified by the languageCode parameter.
|
Related API Elements
Example ( How to use this example )
The following example uses the
loadStringEx() method to trace the value of the IDS_GREETING
string for the currently loaded French language XML file.
Locale.setLoadCallback(localeCallback);
Locale.loadLanguageXML("fr");
function localeCallback(success:Boolean) {
trace(success);
trace(Locale.stringIDArray); // IDS_GREETING
trace(Locale.loadStringEx("IDS_GREETING", "fr")); // bonjour
}
setDefaultLang | () | method |
public static function setDefaultLang(langCode:String):void| Language Version: | ActionScript 3.0 |
| Product Version: | Flash CS3 |
| Runtime Versions: | Flash Player 9, AIR 1.0 |
Sets the default language code.
Parameters
langCode:String — A string representing a language code.
|
Related API Elements
Example ( How to use this example )
The following example creates a variable called
defLang, which is used to hold the initial default language for the Flash document. You click the Settings button in the Strings panel to open the Settings dialog box. Then you add two active languages: English (en) and French (fr), set the replace strings radio control to "via ActionScript at runtime", and click OK. In the Strings panel, you add a string ID of IDS_GREETING, and then add text for each active language.
var defLang:String = "fr";
Locale.setDefaultLang(defLang);
Locale.setLoadCallback(localeCallback);
Locale.loadLanguageXML(Locale.getDefaultLang());
function localeCallback(success:Boolean) {
if (success) {
trace(Locale.stringIDArray); // IDS_GREETING
trace(Locale.loadString("IDS_GREETING"));
} else {
trace("unable to load XML");
}
}
setLoadCallback | () | method |
public static function setLoadCallback(loadCallback:Function):*| Language Version: | ActionScript 3.0 |
| Product Version: | Flash CS3 |
| Runtime Versions: | Flash Player 9, AIR 1.0 |
Sets the callback function that is called after the XML file is loaded.
Parameters
loadCallback:Function — The function to call when the XML language file loads.
|
* |
Example ( How to use this example )
The following example uses an interval to check every 10 milliseconds to see if the language file has successfully
loaded. Once the XML file has loaded, the
greeting_txt text field instance on the Stage is populated with the
IDS_GREETING string from the XML language file.
Locale.setLoadCallback(localeCallback);
Locale.loadLanguageXML("en");
// create interval to check if language XML file is loaded
var locale_int:Number = setInterval(checkLocaleStatus, 10);
function checkLocaleStatus():void {
if (Locale.checkXMLStatus()) {
clearInterval(locale_int);
trace("clearing interval @ " + getTimer() + " ms");
}
}
// callback function for Locale.setLoadCallback()
function localeCallback(success:Boolean):void {
greeting_txt.text = Locale.loadString("IDS_GREETING");
}
setString | () | method |
public static function setString(stringID:String, languageCode:String, stringValue:String):void| Language Version: | ActionScript 3.0 |
| Product Version: | Flash CS3 |
| Runtime Versions: | Flash Player 9, AIR 1.0 |
Sets the new string value of a given string ID and language code.
Parameters
stringID:String — The identification (ID) number of the string to set.
| |
languageCode:String — The language code.
| |
stringValue:String — A string value.
|
Example ( How to use this example )
The following example uses the
setString() method to set the IDS_WELCOME string for both English
(en) and French (fr).
Locale.setString("IDS_WELCOME", "en", "hello");
Locale.setString("IDS_WELCOME", "fr", "bonjour");
trace(Locale.loadStringEx("IDS_WELCOME", "en")); // hello
Mon Nov 28 2011, 06:48 AM -08:00