跳轉到內容

BlitzMax/Modules/MaxGUI/Localization

Add links
來自華夏公益教科書

MaxGUI.Localization 是一個簡單但功能強大的本地化引擎，您可以用它來本地化您的應用程式。雖然該模組主要設計用於與 MaxGUI 工具包一起使用，但它是獨立的，因此可以單獨匯入到其他 BlitzMax 遊戲和應用程式中，而無需 MaxGUI 其他部分的開銷。

建議您在使用前通讀下面的命令集，以熟悉該模組。

在適用情況下，MaxGUI 編碼人員應使用 LocalizeGadget 命令在 MaxGUI.MaxGUI 中，而不是使用 LocalizeString 命令，以確保在更改語言或本地化設定時更新小工具。

函式

[編輯 | 編輯原始碼]

CreateLanguage

[編輯 | 編輯原始碼]

Function CreateLanguage:TMaxGuiLanguage( name$ )

描述: 建立一個新的空語言，用於 MaxGUI 的本地化系統。

資訊: 如果需要從頭開始建立一個新語言，則提供此函式。在大多數情況下，語言應改為使用 LoadLanguage 從 INI 檔案載入。

使用 DefineLanguageToken、RemoveLanguageToken 和 ClearLanguageTokens 命令新增和修改返回的語言。 SetLanguageName 和 LanguageName 也可能有用。

另見: LoadLanguage、SetLocalizationLanguage、LocalizeString 和 LocalizeGadget.

示例: 

' createlanguage.bmx

Strict

Import MaxGUI.Drivers

' Enable the localization engine, and automatically localize gadgets when they are created
SetLocalizationMode(LOCALIZATION_ON|LOCALIZATION_OVERRIDE)

Global window:TGadget = CreateWindow("{{window_title}}",100,100,320,240,Null,WINDOW_TITLEBAR|WINDOW_STATUS)
	
	Global btnEnglish:TGadget = CreateButton("{{btn_english}}",5,5,100,30,window,BUTTON_RADIO)
	Global btnFrench:TGadget = CreateButton("{{btn_french}}",5,40,100,30,window,BUTTON_RADIO)
	SetButtonState( btnEnglish, True )

' Create a new 'English' language
Global lngEnglish:TMaxGUILanguage = CreateLanguage("English (English)")

DefineLanguageToken( lngEnglish, "window_title", "My Window" )
DefineLanguageToken( lngEnglish, "btn_english", "English" )
DefineLanguageToken( lngEnglish, "btn_french", "French" )

' Create a new 'French' language
Global lngFrench:TMaxGUILanguage = CreateLanguage("Français (French)")

DefineLanguageToken( lngFrench, "window_title", "Ma Fenêtre" )
DefineLanguageToken( lngFrench, "btn_english", "Anglais" )
DefineLanguageToken( lngFrench, "btn_french", "Français" )

' Set the default language
SetLocalizationLanguage( lngEnglish )

Repeat
	SetStatusText window, LanguageName( LocalizationLanguage() )
	Select WaitEvent()
		Case EVENT_GADGETACTION
			Select EventSource()
				Case btnEnglish
					SetLocalizationLanguage( lngEnglish )
				Case btnFrench
					SetLocalizationLanguage( lngFrench )
			EndSelect
		Case EVENT_APPTERMINATE, EVENT_WINDOWCLOSE
			End
	EndSelect
Forever

LoadLanguage

[編輯 | 編輯原始碼]

Function LoadLanguage:TMaxGuiLanguage( url:Object )

描述: 從 INI 文字流載入語言。

資訊: url 可以是檔案路徑或任何其他可讀的 TStream 物件。

INI 文字流必須至少包含一個標記為 '[LanguageDefinition]' 的 INI 部分，以及一個 'LanguageID' 標記，該標記應分配一個適當的語言名稱。

典型的語言 INI 檔案可能如下所示

[LanguageDefinition]

LanguageID = Français (French)
LanguageVersion = v0.1
LanguageAuthor = Various Sources

; Toolbar Tips
tb_new                                       = "Nouveau"
tb_open                                      = "Ouvrir"
tb_close                                     = "Fermer"
tb_save                                      = "Enregistrer"
tb_cut                                       = "Couper"
tb_copy                                      = "Copier"
tb_paste                                     = "Coller"
...
tb_home                                      = "Page d'Accueil"
tb_back                                      = "Précédente"
tb_forward                                   = "Suivante"

; Tabs
tab_help                                     = "Aide"
tab_output                                   = "Sortie"
tab_locked:%1                                = "construction:%1"

; Time Format, by example: 13:09:02
; h = 1 (12 hour clock)       hh = 13 (24 hour clock)
; m = 9 (without leading 0)   mm = 09 (including leading 0)
; s = 2 (without leading 0)   ss = 02 (including leading 0)
; pp = {{pm}} (or '{{am}}' from 00:00 -> 11:59)

longtime = hh:mm:ss pp
shorttime = {{longtime}}          ; We want short time to be formatted exactly like {{longtime}}

; Date Format, by example: 9th June 2009
; d = 9    dd = 09    ddd = {{Wed}}    dddd = {{Wednesday}}
; m = 6    mm = 06    mmm = {{Jun}}    mmmm = {{June}}
; yy = 09  yyyy = 2009             oo = {{th}}

longdate = dddd doo mmmm dddd     ; e.g. Wednesday 9th June 2009
shortdate = dd/mm/yy              ; e.g. 09/06/09

; AM / PM
am = AM
pm = PM

; Ordinals

st = e
nd = er
rd = e
th = e

; Days of the week

Monday = "Lundi"
Mon = "Lun"
Tueday = "Mardi"
Tue = "Mar"
Wednesday = "Mercredi"
Wed = "Mer"
Thursday = "Jeudi"
Thu = "Jeu"
Friday = "Vendredi"
Fri = "Ven"
Saturday = "Samedi"
Sat = "Sam"
Sunday = "Dimanche"
Sun = "Dim"

INI 檔案支援以下轉義序列字元

INI 轉義序列 BlitzMax 等效項
\\ ~\ 
\r ~r
\n ~n
\t ~t
\# #
\; ;
\: :

只有當 INI 鍵的值用引號括起來時，才嚴格要求使用最後三個轉義序列。例如，以下定義預計將評估為相同的字串（#;:）。

MyToken = \#\;\:
MyToken = "#;:"
MyToken = "\#\;\:"

使用 DefineLanguageToken、RemoveLanguageToken 和 ClearLanguageTokens 命令新增和修改返回的語言。 SetLanguageName 和 LanguageName 也可能有用。

要從頭開始構建新語言，請改用 CreateLanguage 命令。

另見: SetLocalizationLanguage、SaveLanguage、LocalizeString 和 LocalizeGadget.

SaveLanguage

[編輯 | 編輯原始碼]

Function SaveLanguage( language:TMaxGuiLanguage, url:Object )

描述: 將語言作為 INI 部分儲存到提供的流。

資訊: url 可以是檔案路徑或任何其他可寫入的 TStream 物件。

如果 url 是以 "/" 或 "\" 結尾的字串，則假定 url 是目錄路徑，並將附加預設檔名，如下所示

url = String(url) + LanguageName(language).Split(" ")[0] + ".language.ini"

警告: 此命令將自動覆蓋提供的/生成的路徑上的任何現有檔案。

另見: LoadLanguage、SetLocalizationLanguage、LocalizeString 和 LocalizeGadget.

SetLanguageName

[編輯 | 編輯原始碼]

Function SetLanguageName( language:TMaxGuiLanguage, name$ )

描述: 重新定義語言的名稱。

資訊: 另見: LanguageName、LoadLanguage、CreateLanguage 和 SetLocalizationLanguage.

LanguageName

[編輯 | 編輯原始碼]

Function LanguageName$( language:TMaxGuiLanguage )

描述: 返回語言的名稱。

資訊: 另見: SetLanguageName、LoadLanguage、CreateLanguage 和 SetLocalizationLanguage.

DefineLanguageToken

[編輯 | 編輯原始碼]

Function DefineLanguageToken( language:TMaxGuiLanguage, token$, value$ )

描述: 為本地化令牌定義特定於語言的值。

資訊: 本地化令牌不區分大小寫，如果語言中已存在令牌定義，則令牌值將被此最新的 value$ 覆蓋。

另見: LoadLanguage、CreateLanguage、SaveLanguage 和 SetLocalizationLanguage.

LanguageTokenDefinition

[編輯 | 編輯原始碼]

Function LanguageTokenDefinition$( language:TMaxGuiLanguage, token$ )

描述: 查詢特定語言的令牌值。

資訊: 本地化令牌不區分大小寫，並且要麼與語言一起載入，要麼使用 DefineLanguageToken 命令定義。

如果在語言中找不到顯式令牌定義，則返回 token$ 字串，因為它被傳遞。

另見: LoadLanguage、CreateLanguage、SaveLanguage 和 SetLocalizationLanguage.

RemoveLanguageToken

[編輯 | 編輯原始碼]

Function RemoveLanguageToken( language:TMaxGuiLanguage, token$ )

描述: 從語言中刪除令牌定義。

資訊: 唯一不能刪除的令牌是 'LanguageID'，因為每種語言都需要定義此令牌 - 它定義了語言名稱。如果未定義匹配的令牌，則命令將靜默返回。

注意: 本地化令牌不區分大小寫，因此以下所有命令都請求刪除相同的令牌

RemoveLanguageToken( language, "WelcomeMessage" )
RemoveLanguageToken( language, "WELCOMEMESSAGE" )
RemoveLanguageToken( language, "welcomemessage" )
RemoveLanguageToken( language, "WeLcOmEmEsSaGe" )

另見: ClearLanguageTokens、DefineLanguageToken、LoadLanguage、CreateLanguage、SaveLanguage 和 SetLocalizationLanguage.

ClearLanguageTokens

[編輯 | 編輯原始碼]

Function ClearLanguageTokens( language:TMaxGuiLanguage )

描述: 刪除語言中定義的所有令牌。

資訊: 唯一不會被刪除的令牌是 'LanguageID'，因為每種語言都需要定義此令牌 - 它定義了語言名稱。

另見: RemoveLanguageToken、DefineLanguageToken、LoadLanguage、CreateLanguage、SaveLanguage 和 SetLocalizationLanguage.

LocalizeString

[編輯 | 編輯原始碼]

Function LocalizeString$( localizationstring$ )

描述: 返回字串的本地化版本。

資訊: 此函式接受一個引數: localizationstring$。

本地化字串就像任何其他字串一樣，除了用一對雙花括號括起來的任何短語都被識別為本地化令牌。例如，以下所有示例都使用有效的本地化字串。 

LocalizeString("{{welcomemessage}}")                      'Localization token(s): welcomemessage
LocalizeString("{{apptitlelabel}}: {{AppTitle}}")         'Localization token(s): apptitlelabel, AppTitle
LocalizeString("Current Time: {{CurrentTime}}")           'Localization token(s): CurrentTime

本地化標記不區分大小寫，可以由任意組合的字母數字字元組成。 首先，會測試標記是否是保留字。 以下標記當前被保留（雖然將來可能會新增更多）：

本地化標記 標記將被替換為...
AppDir 全域性常量的值 AppDir。
AppFile 全域性常量的值 AppFile。
AppTitle 全域性常量的值 AppTitle。
LaunchDir 全域性常量的值 LaunchDir。
GCMemAlloced 函式返回的值 GCMemAlloced（在解析標記時）。

還有一些保留的日期和時間標記，它們將使用當前語言中定義的任何格式顯示當前日期和時間（在解析時）。 如果沒有明確定義匹配的格式，則格式預設設定為

本地化標記 預設格式 示例輸出
ShortTime "hh:mm pp" 02:36 {{pm}}
LongTime "hh:mm:ss" 14:36:51
ShortDate "dd/mm/yy" 04/08/09
LongDate "dddd doo mmmm yyyy" {{Monday}} 4{{th}} {{August}} 2009

注意如何將任何基於文字的日期和時間資訊包含在花括號中。 這些標記將被本地化，就像任何其他標記一樣，因此可以透過向本地化語言新增相應的條目來修改它們。

這也演示了本地化解析器處理巢狀標記的能力。 為了防止死鎖，本地化解析器會檢查迴圈標記定義，如果遇到迴圈標記定義，則該標記將簡單地替換為“！ERROR！”，並且違規的本地化字串將在寫入標準錯誤的警告訊息中標識。

當且僅當本地化標記不是保留字時，才會查詢當前本地化語言。 如果沒有選擇本地化語言，或者當前語言中沒有定義匹配的標記，則該標記將在返回的字串中簡單地刪除其花括號。 每個語言都必須至少定義一個標記：{{LanguageID}}。 這應該代表語言名稱，例如“Français (French)”。

注意：此功能需要設定 LOCALIZATION_ON 標誌（請參閱 SetLocalizationMode），否則該功能將簡單地返回 localizationstring$，就像它被傳遞時的樣子（包括任何花括號）。

另請參閱：SetLocalizationMode、LocalizationMode、SetLocalizationLanguage 和 LocalizationLanguage。

SetLocalizationMode

[edit | edit source]

Function SetLocalizationMode( mode:Int = LOCALIZATION_ON )

描述：啟用或停用本地化引擎，並設定其他本地化模式。

資訊：該模式可以設定為

常量 含義
LOCALIZATION_OFF 任何本地化的小部件將顯示其 localizedtext$ 作為其實際文字。
LOCALIZATION_ON 本地化小部件將使用當前語言來顯示其文字。

這兩種模式都可以與 LOCALIZATION_OVERRIDE 組合（按位或運算），這將導致小部件在建立時自動“本地化”，任何提供給 CreateGadget() 函式的 text$ 引數都被解釋為本地化字串。

如果任何視窗選單已本地化，則可能需要在所有相關視窗上呼叫 UpdateWindowMenu 才能使文字更改可見。

另請參閱：LocalizationMode、SetLocalizationLanguage、LocalizationLanguage 和 LocalizeGadget。

LocalizationMode

[edit | edit source]

Function LocalizationMode:Int()

描述：返回先前使用 SetLocalizationMode 設定的值。

資訊：MaxGUI 程式的預設值為 LOCALIZATION_OFF。

請參閱 SetLocalizationMode 以瞭解有效模式及其相應的常量。

SetLocalizationLanguage

[edit | edit source]

Function SetLocalizationLanguage( language:TMaxGUILanguage )

描述：設定 MaxGUI 的本地化系統要使用的語言。

資訊：可以使用 LoadLanguage 從檔案/流載入語言，並可以使用 CreateLanguage 從頭開始建立語言。

此函式將自動更新使用 LocalizeGadget 標記為“本地化”的任何小部件的文字。

如果任何視窗選單已本地化，則可能需要在所有相關視窗上呼叫 UpdateWindowMenu 才能使文字更改可見。

另請參閱：LocalizationLanguage、SetLocalizationMode、LocalizationMode 和 LocalizeString。

LocalizationLanguage

[edit | edit source]

Function LocalizationLanguage:TMaxGUILanguage()

描述：返回 MaxGUI 的本地化系統使用的當前語言。

資訊：使用 DefineLanguageToken、RemoveLanguageToken 和 ClearLanguageTokens 命令來新增和修改返回的語言。 SetLanguageName 和 LanguageName 也可能有用。


資訊：另請參閱：SetLocalizationLanguage、SetLocalizationMode、LocalizationMode 和 LocalizeGadget。

Retrieved from "https://wikibook.tw/w/index.php?title=BlitzMax/Modules/MaxGUI/Localization&oldid=2063459"
華夏公益教科書