Locale - Adobe ActionScript® 3 (AS3 Flash) API 參考

套件	fl.lang
類別	public class Locale
繼承	Locale EventDispatcher Object

語言版本:

ActionScript 3.0

產品版本:

Flash CS3

執行階段版本:

Flash Player 9, AIR 1.0

fl.lang.Locale 類別允許您控制多國語言文字在 SWF 檔中的顯示方式。 Flash 的「字串」面板允許您在動態文字欄位中使用字串 ID 來替代字串常值。這可讓您建立 SWF 檔，顯示從特定語言 XML 檔載入的文字。 XML 檔必須使用「XML 當地語系化交換檔案格式」(XML Localization Interchange File Format，XLIFF)。顯示包含在 XLIFF 檔案中的特定語言字串的方法有三種：

「在執行階段自動執行」- Flash Player 會以 XML 檔案中符合 flash.system.capabilities.language 傳回之預設系統語言碼的字串來取代字串 ID。
「手動使用舞台語言」- 會在編譯階段以字串取代字串 ID，而且 Flash Player 無法加以變更。
「在執行階段透過 ActionScript」- 會在執行階段時使用 ActionScript 來控制字串 ID 的取代作業。此選項可以讓您同時控制取代字串 ID 的時間及語言。

當您想要「在執行階段透過 ActionScript」取代字串 ID 時，可以使用此類別的屬性及方法。

所有適用的屬性及方法都是靜態的，換句話說，可以透過 fl.lang.Locale 類別本身存取它們，毋須透過該類別的實體。

注意： Locale 類別會安裝在Flash 的「編寫」類別路徑，並且自動編譯到 SWF 檔中。因為會將類別編譯到 SWF 中，所以使用 Locale 類別會稍微增加 SWF 的大小。

相關 API 元素

flash.system.Capabilities.language

公用屬性

隱藏繼承公用屬性

顯示繼承公用屬性

	屬性		定義自
		autoReplace : Boolean [靜態] 會決定是否在載入 XML 檔後自動取代字串。	Locale
		constructor : Object 類別物件的參照或是特定物件實體的建構函數。	Object
		languageCodeArray : Array [靜態] [唯讀] 陣列，包含已指定或載入至 FLA 檔之語言的語言碼。	Locale
		stringIDArray : Array [靜態] [唯讀] 陣列，包含所有在 FLA 檔中的字串 ID。	Locale

公用方法

隱藏繼承公用方法

顯示繼承公用方法

	方法		定義自
		addDelayedInstance(instance:Object, stringID:String):* [靜態] 將 {instance, string ID} 配對加入至內部陣列以於日後使用。	Locale
		addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void 會在 EventDispatcher 物件註冊事件偵聽程式，以便讓偵聽程式收到事件的通知。	EventDispatcher
		addXMLPath(langCode:String, path:String):void [靜態] 將 {languageCode and languagePath} 配對加入至內部陣列以於日後使用。	Locale
		checkXMLStatus():Boolean [靜態] 如果已載入 XML 檔，則傳回 true，否則傳回 false。	Locale
		dispatchEvent(event:Event):Boolean 會將事件傳送到事件流程。	EventDispatcher
		getDefaultLang():String [靜態] 預設語言碼是在「字串」面板對話方塊中設定，或藉由呼叫 setDefaultLang() 方法而設定。	Locale
		hasEventListener(type:String):Boolean 會檢查 EventDispatcher 物件是否有對特定的事件類型註冊偵聽程式。	EventDispatcher
		hasOwnProperty(name:String):Boolean 指出物件是否有已定義的指定屬性。	Object
		initialize():void [靜態] 會自動決定要使用的語言，並載入 XML 語言檔案。	Locale
		isPrototypeOf(theClass:Object):Boolean 指出 Object 類別的實體是否位於指定為參數的物件原型鏈中。	Object
		loadLanguageXML(xmlLanguageCode:String, customXmlCompleteCallback:Function = null):void [靜態] 會載入指定的 XML 語言檔案。	Locale
		loadString(id:String):String [靜態] 會傳回目前語言中與指定字串 ID 關聯的字串值。	Locale
		loadStringEx(stringID:String, languageCode:String):String [靜態] 會傳回與指定字串 ID 及語言碼關聯的字串值。	Locale
		propertyIsEnumerable(name:String):Boolean 指出指定的屬性是否存在，以及是否可列舉。	Object
		removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void 會從 EventDispatcher 物件移除偵聽程式。	EventDispatcher
		setDefaultLang(langCode:String):void [靜態] 設定預設語言碼。	Locale
		setLoadCallback(loadCallback:Function):* [靜態] 會設定要在 XML 檔載入後呼叫的回呼函數。	Locale
		setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void 為迴圈作業設定動態屬性的可用性。	Object
		setString(stringID:String, languageCode:String, stringValue:String):void [靜態] 會設定指定之字串 ID 和語言碼的新字串值。	Locale
		toLocaleString():String 傳回代表此物件的字串，根據地區特定慣例進行格式化。	Object
		toString():String 會傳回指定之物件的字串形式。	Object
		valueOf():Object 會傳回指定之物件的基本值。	Object
		willTrigger(type:String):Boolean 檢查此 EventDispatcher 物件是否已註冊事件偵聽程式，或者此物件的任何祖系已為特定事件類型註冊事件偵聽程式。	EventDispatcher

事件

按一下以瞭解事件的詳細資訊

隱藏繼承事件

顯示繼承事件

	事件		摘要	定義自
		activate	[廣播事件] 當 Flash Player 或 AIR 應用程式取得作業系統焦點並成為作用中時傳送。	EventDispatcher
		deactivate	[廣播事件] 當 Flash Player 或 AIR 應用程式失去作業系統焦點並成為非作用中時傳送。	EventDispatcher

屬性詳細資訊

autoReplace

屬性

autoReplace:Boolean

語言版本:

ActionScript 3.0

產品版本:

Flash CS3

執行階段版本:

Flash Player 9, AIR 1.0

會決定是否在載入 XML 檔後自動取代字串。如果設為 true，則等於將文字取代方法設定為在「字串」面板設定「在執行階段自動執行」。換句話說，Flash Player 將決定主機環境的預設語言，並自動以該語言顯示文字。如果設為 false，則等於將文字取代方法設定為在「字串」面板設定「在執行階段透過 ActionScript」。這表示您必須負責載入合適的 XML 檔以顯示文字。

此屬性的預設值會反映您在「字串」面板對話方塊中，為「取代」字串選取的設定：true 代表「在執行階段自動執行」(預設設定)，而 false 則代表「在執行階段透過 ActionScript」.

實作
public static function get autoReplace():Boolean
public static function set autoReplace(value:Boolean):void

範例 ( 如何使用本範例 )

下列範例會使用 Locale.autoReplace 屬性，將英文 XML 檔中的 IDS_GREETING 字串填入「舞台」上以動態方式建立的 greeting_txt 文字欄位。按一下「字串」面板中的「設定」按鈕，開啟「設定」對話方塊。您可以使用「設定」對話方塊，新增英文 (en) 和法文 (fr) 這兩個作用中的語言，並將字串取代方式的選項控制項設定為「在執行階段透過 ActionScript」，然後按一下「確定」。最後，在「字串」面板中輸入 IDS_GREETING 這個字串 ID，並為每個作用中的語言加入文字。

     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

屬性

languageCodeArray:Array [唯讀]

語言版本:

ActionScript 3.0

產品版本:

Flash CS3

執行階段版本:

Flash Player 9, AIR 1.0

陣列，包含已指定或載入至 FLA 檔之語言的語言碼。語言碼不會依照英文字母進行排序。

實作
public static function get languageCodeArray():Array

範例 ( 如何使用本範例 )

下列範例將根據 ComboBox 組件目前的值，載入語言 XML 檔。將 ComboBox 組件拖曳到「舞台」上，並指定實體名稱為 lang_cb。使用「文字工具」建立動態文字欄位，並指定實體名稱為 greeting_txt。在「字串」面板中，新增至少兩個作用中的語言，並將字串取代方式的選項設定為 「在執行階段透過 ActionScript」，然後按一下「確定」。接下來，加入 IDS_GREETING 這個字串 ID，然後為每個作用中的語言輸入文字。最後，在主「時間軸」的「影格 1」中，加入下列 ActionScript 程式碼：

     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

屬性

stringIDArray:Array [唯讀]

語言版本:

ActionScript 3.0

產品版本:

Flash CS3

執行階段版本:

Flash Player 9, AIR 1.0

陣列，包含所有在 FLA 檔中的字串 ID。字串 ID 不會依照英文字母進行排序。

實作
public static function get stringIDArray():Array

範例 ( 如何使用本範例 )

下列範例將針對目前載入的語言 XML 檔，追蹤 Locale.stringIDArray 屬性。按一下「字串」面板中的「設定」按鈕，開啟「設定」對話方塊，接著，新增英文 (en) 和法文 (fr) 這兩個作用中的語言，並將字串取代方式的選項控制項設定為 「在執行階段透過 ActionScript」，然後按一下「確定」。在「字串」面板中，加入 IDS_GREETING 的字串 ID，然後再為每個作用中的語言加入文字。

     Locale.setLoadCallback(localeCallback);
     Locale.loadLanguageXML("fr");
     function localeCallback(success:Boolean) {
      trace(success);
      trace(Locale.stringIDArray); // IDS_GREETING
      trace(Locale.loadStringEx("IDS_GREETING", "fr")); // bonjour
     }

方法詳細資訊

addDelayedInstance

()

方法

public static function addDelayedInstance(instance:Object, stringID:String):*

語言版本:

ActionScript 3.0

產品版本:

Flash CS3

執行階段版本:

Flash Player 9, AIR 1.0

將 {instance, string ID} 配對加入至內部陣列以於日後使用。當字串取代方式設為 "automatically at runtime" 時，Flash 主要是使用這個方法。

參數

	`instance:Object` — 要填入之文字欄位的實體名稱。

	`stringID:String` — 語言字串 ID。

傳回值

*

範例 ( 如何使用本範例 )

下列範例會使用 autoReplace 屬性和 addDelayedInstance() 方法，將英文 XML 語言檔案中的 IDS_GREETING 字串填入「舞台」上的文字欄位。

     greeting_txt.autoSize = TextFieldAutoSize.LEFT;
     Locale.autoReplace = true;
     Locale.addDelayedInstance(greeting_txt, "IDS_GREETING");
     Locale.loadLanguageXML("en");

addXMLPath

()

方法

public static function addXMLPath(langCode:String, path:String):void

語言版本:

ActionScript 3.0

產品版本:

Flash CS3

執行階段版本:

Flash Player 9, AIR 1.0

將 {languageCode and languagePath} 配對加入至內部陣列以於日後使用。當字串取代方式設為 "automatically at runtime" 或 "via ActionScript at runtime" 時，Flash Player 主要是使用這個方法。這個方法可以讓您從自訂的位置載入 XML 語言檔案，不必從 Flash Professional 設定的預設位置來載入。根據預設值，Flash Professional 會為工作目錄中的每一種語言建立 XML 檔案，然後放到 FLA 檔案名稱之下的子目錄中。

參數

	`langCode:String` — 語言碼。

	`path:String` — 要增加的 XML 路徑。

範例 ( 如何使用本範例 )

以下範例會告訴 Flash Player 說英文 ("en") 翻譯已經在工作目錄相對的 "locale/locale_en.xml" 檔案中找到，而且法文 ("fr") 翻譯已經在 "locale/locale_fr.xml" 檔案中找到 (Chris Inch 提供的範例和說明，網址為 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

()

方法

public static function checkXMLStatus():Boolean

語言版本:

ActionScript 3.0

產品版本:

Flash CS3

執行階段版本:

Flash Player 9, AIR 1.0

如果已載入 XML 檔，則傳回 true，否則傳回 false。

傳回值

Boolean — 如果已載入 XML 檔，則傳回 true，否則傳回 false。

範例 ( 如何使用本範例 )

下列範例會以每 10 毫秒做為時間間隔，檢查是否已成功載入語言檔案。 XML 檔一經載入，語言 XML 檔中的 IDS_GREETING 字串便會填入「舞台」上的 greeting_txt 文字欄位實體。

     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

()

方法

public static function getDefaultLang():String

語言版本:

ActionScript 3.0

產品版本:

Flash CS3

執行階段版本:

Flash Player 9, AIR 1.0

預設語言碼是在「字串」面板對話方塊中設定，或藉由呼叫 setDefaultLang() 方法而設定。

傳回值

String — 會傳回預設語言碼。

相關 API 元素

Locale.setDefaultLang()

範例 ( 如何使用本範例 )

下列範例將建立名為 defLang 的變數，用來保留 Flash 文件的初始預設語言。按一下「字串」面板中的「設定」按鈕，啟動「設定」對話方塊。接著，新增英文 (en) 和法文 (fr) 這兩個作用中的語言，並將字串取代方式的選項控制項設定為「在執行階段透過 ActionScript」，然後按一下「確定」。在「字串」面板中，加入 IDS_GREETING 的字串 ID，然後再為每個作用中的語言加入文字。

     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

()

方法

public static function initialize():void

語言版本:

ActionScript 3.0

產品版本:

Flash CS3

執行階段版本:

Flash Player 9, AIR 1.0

會自動決定要使用的語言，並載入 XML 語言檔案。當字串取代方式設為 "automatically at runtime" 時，Flash 主要是使用這個方法。

範例 ( 如何使用本範例 )

此範例會顯示如何使用 initialize() 方法，將使用者目前的 OS 語言自動填入「舞台」上的 greeting_txt 文字欄位。如果不直接使用 initialize() 方法，請使用「在執行階段自動執行」的字串取代方法。

     trace(System.capabilities.language);
     Locale.autoReplace = true;
     Locale.addDelayedInstance(greeting_txt, "IDS_GREETING");
     Locale.initialize();

loadLanguageXML

()

方法

public static function loadLanguageXML(xmlLanguageCode:String, customXmlCompleteCallback:Function = null):void

語言版本:

ActionScript 3.0

產品版本:

Flash CS3

執行階段版本:

Flash Player 9, AIR 1.0

會載入指定的 XML 語言檔案。

參數

	`xmlLanguageCode:String` — 要載入之 XML 語言檔案的語言碼。

	`customXmlCompleteCallback:Function` (default = `null`) — 要在 XML 語言檔案載入時呼叫的自訂回呼函數。

範例 ( 如何使用本範例 )

下列範例會使用 loadLanguageXML() 方法，載入英文 (en) XML 語言檔案。語言檔案一經載入，便會呼叫 localeCallback() 方法，並將 XML 語言檔案中的 IDS_GREETING 字串填入「舞台」上的 greeting_txt 文字欄位。

     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

()

方法

public static function loadString(id:String):String

語言版本:

ActionScript 3.0

產品版本:

Flash CS3

執行階段版本:

Flash Player 9, AIR 1.0

會傳回目前語言中與指定字串 ID 關聯的字串值。

參數

id:String — 要載入之字串的辨識碼 (ID)。

傳回值

String — 目前語言中與指定字串 ID 關聯的字串值。

相關 API 元素

Locale.loadStringEx()

範例 ( 如何使用本範例 )

     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

()

方法

public static function loadStringEx(stringID:String, languageCode:String):String

語言版本:

ActionScript 3.0

產品版本:

Flash CS3

執行階段版本:

Flash Player 9, AIR 1.0

會傳回與指定字串 ID 及語言碼關聯的字串值。為了避免載入預期之外的 XML 檔，如果尚未載入 XML 檔，loadStringEx() 就不會載入 XML 語言檔。如果您要載入 XML 語言檔，則應該決定呼叫 loadLanguageXML() 的適當時機。

參數

	`stringID:String` — 要載入之字串的辨識碼 (ID)。

	`languageCode:String` — 語言碼。

傳回值

String — 在 languageCode 參數指定的語言中，與指定字串 ID 關聯的字串值。

相關 API 元素

Locale.loadString()

範例 ( 如何使用本範例 )

下列範例會使用 loadStringEx() 方法，追蹤目前所載入之法文語言 XML 檔的 IDS_GREETING 字串值。

     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

()

方法

public static function setDefaultLang(langCode:String):void

語言版本:

ActionScript 3.0

產品版本:

Flash CS3

執行階段版本:

Flash Player 9, AIR 1.0

設定預設語言碼。

參數

langCode:String — 代表語言碼的字串。

相關 API 元素

Locale.getDefaultLang()

範例 ( 如何使用本範例 )

下列範例將建立名為 defLang 的變數，用來保留 Flash 文件的初始預設語言。按一下「字串」面板中的「設定」按鈕，開啟「設定」對話方塊，接著，新增英文 (en) 和法文 (fr) 這兩個作用中的語言，並將字串取代方式的選項控制項設定為「在執行階段透過 ActionScript」，然後按一下「確定」。在「字串」面板中，加入 IDS_GREETING 的字串 ID，然後再為每個作用中的語言加入文字。

     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

()

方法

public static function setLoadCallback(loadCallback:Function):*

語言版本:

ActionScript 3.0

產品版本:

Flash CS3

執行階段版本:

Flash Player 9, AIR 1.0

會設定要在 XML 檔載入後呼叫的回呼函數。

參數

loadCallback:Function — 要在 XML 語言檔案載入時呼叫的函數。

傳回值

*

範例 ( 如何使用本範例 )

     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

()

方法

public static function setString(stringID:String, languageCode:String, stringValue:String):void

語言版本:

ActionScript 3.0

產品版本:

Flash CS3

執行階段版本:

Flash Player 9, AIR 1.0

會設定指定之字串 ID 和語言碼的新字串值。

參數

	`stringID:String` — 要設定之字串的識別碼 (ID)。

	`languageCode:String` — 語言碼。

	`stringValue:String` — 字串值。

範例 ( 如何使用本範例 )

下列範例會使用 setString() 方法，設定英文 (en) 及法文 (fr) 的 IDS_WELCOME 字串。

     Locale.setString("IDS_WELCOME", "en", "hello");
     Locale.setString("IDS_WELCOME", "fr", "bonjour");
     trace(Locale.loadStringEx("IDS_WELCOME", "en")); // hello

法律聲明 | 線上隱私權政策

Locale - AS3 Flash

套件x

語言元素

附錄

套件 fl.lang

autoReplace

languageCodeArray

stringIDArray

addDelayedInstance

addXMLPath

checkXMLStatus

getDefaultLang

initialize

loadLanguageXML

loadString

loadStringEx

setDefaultLang

setLoadCallback

setString