BlitzMax/Modules/MaxGUI/Localization

MaxGUI.Localization is a simple yet powerful localization engine that you can use to localize your applications. Although the module is designed primarily for use with the MaxGUI toolkit, it is self-contained and so can be imported into other BlitzMax games and applications separately, without the overhead of the rest of MaxGUI.

It is recommended that you read through the command set below to familiarize yourself with the module before use.

Whenever applicable, MaxGUI coders should use the LocalizeGadget command in MaxGUI.MaxGUI in favour of LocalizeString to ensure that gadgets are updated when the language or localization settings are changed.

=Functions=

CreateLanguage
Function CreateLanguage:TMaxGuiLanguage( name$ )

Description: Create a new empty language to be used with MaxGUI's localization system.

Information: This function is provided in case it is necessary to create a new language from scratch. In the majority of cases, languages should instead be loaded from INI files using LoadLanguage.

Use the DefineLanguageToken, RemoveLanguageToken and ClearLanguageTokens commands to add to and modify the returned language. SetLanguageName and LanguageName may also be useful.

See Also: LoadLanguage, SetLocalizationLanguage, LocalizeString and LocalizeGadget.

Example: ' 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("",100,100,320,240,Null,WINDOW_TITLEBAR|WINDOW_STATUS) Global btnEnglish:TGadget = CreateButton("",5,5,100,30,window,BUTTON_RADIO) Global btnFrench:TGadget = CreateButton("",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 )

Description: Load a language from an INI text stream.

Information: url can be a filepath or any other readable TStream object.

The INI text stream must contain, at minimum, an INI section labelled '[LanguageDefinition]' and a 'LanguageID' token which should be assigned an appropriate language name.

A typical language ini file may look something like:

[LanguageDefinition]

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

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"
 * Toolbar Tips

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


 * 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 = &#123;&#123;pm&#125;&#125; (or '&#123;&#123;am&#125;&#125;' from 00:00 -> 11:59)

longtime = hh:mm:ss pp shorttime = &#123;&#123;longtime&#125;&#125;         ; We want short time to be formatted exactly like &#123;&#123;longtime&#125;&#125;


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

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

am = AM pm = PM
 * AM / 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 files support the following escape sequence characters:

The bottom three escape sequences are only strictly required if the value of the INI key is enclosed in quotes. For example, the following definitions are expected to evaluate to the same string ( #;: ).

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

Use the DefineLanguageToken, RemoveLanguageToken and ClearLanguageTokens commands to add to and modify the returned language. SetLanguageName and LanguageName may also be useful.

To construct a new language from scratch, use the CreateLanguage command instead.

See Also: SetLocalizationLanguage, SaveLanguage, LocalizeString and LocalizeGadget.

SaveLanguage
Function SaveLanguage( language:TMaxGuiLanguage, url:Object )

Description: Saves a language as an INI section to the supplied stream.

Information: url can be a filepath or any other writable TStream object.

If url is a string ending in "/" or "\", it is assumed that url is a directory path and a default filename will be appended like so:

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

WARNING: This command will automatically overwrite any existing file at the supplied/resulting file path.

See Also: LoadLanguage, SetLocalizationLanguage, LocalizeString and LocalizeGadget.

SetLanguageName
Function SetLanguageName( language:TMaxGuiLanguage, name$ )

Description: Redefine a language's name.

Information: See Also: LanguageName, LoadLanguage, CreateLanguage and SetLocalizationLanguage.

LanguageName
Function LanguageName$( language:TMaxGuiLanguage )

Description: Returns a language's name.

Information: See Also: SetLanguageName, LoadLanguage, CreateLanguage and SetLocalizationLanguage.

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

Description: Define a language-specific value for a localization token.

Information: Localization tokens are case insensitive, and if a token definition already exists in the language the token value will be overwritten with this most recent value$.

See Also: LoadLanguage, CreateLanguage, SaveLanguage and SetLocalizationLanguage.

LanguageTokenDefinition
Function LanguageTokenDefinition$( language:TMaxGuiLanguage, token$ )

Description: Look-up the value of a token for a specific language.

Information: Localization tokens are case insensitive, and are either loaded in with the language or defined using the DefineLanguageToken command.

If an explicit token definition is not found in the language, the token$ string is returned as it was passed.

See Also: LoadLanguage, CreateLanguage, SaveLanguage and SetLocalizationLanguage.

RemoveLanguageToken
Function RemoveLanguageToken( language:TMaxGuiLanguage, token$ )

Description: Remove a token definition from a language.

Information: The only token which cannot be removed is 'LanguageID' as every language requires this one token to be defined - it defines the language name. If a matching token isn't already defined, then the command returns silently.

Note: Localization tokens are case insensitive so the following commands are all requesting the same token to be removed:

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

See Also: ClearLanguageTokens, DefineLanguageToken, LoadLanguage, CreateLanguage, SaveLanguage and SetLocalizationLanguage.

ClearLanguageTokens
Function ClearLanguageTokens( language:TMaxGuiLanguage )

Description: Removes all the tokens defined in a language.

Information: The only token which will not be removed is 'LanguageID' as every language requires this one token to be defined - it defines the language name.

See Also: RemoveLanguageToken, DefineLanguageToken, LoadLanguage, CreateLanguage, SaveLanguage and SetLocalizationLanguage.

LocalizeString
Function LocalizeString$( localizationstring$ )

Description: Returns the localized version of a string.

Information: This function takes one parameter: localizationstring$.

A localization string is just like any other string except that any phrase enclosed in a double pair of curly-braces is identified as a localization token. For example, the following examples all use valid localization strings.

LocalizeString("&#123;&#123;welcomemessage&#125;&#125;")                     'Localization token(s): welcomemessage LocalizeString("&#123;&#123;apptitlelabel&#125;&#125;: &#123;&#123;AppTitle&#125;&#125;")        'Localization token(s): apptitlelabel, AppTitle LocalizeString("Current Time: &#123;&#123;CurrentTime&#125;&#125;")          'Localization token(s): CurrentTime

Localization tokens are case insensitive, and may be made up of any combination of alphanumeric characters. Firstly, the token is tested to see if it is a reserved word. The following tokens are currently reserved (although more maybe added in the future):

There are also some reserved date and time tokens which will display the current date and time (at the moment of parsing) using any formats defined in the current language. If there are no matching formats explicitly defined, the formats default to:

Notice how any text-based time and date information is wrapped in curly braces. These tokens will be localized, just like any other token, and so can be modified by adding a corresponding entry to the localization language.

This also demonstrates the ability of the localization parser to handle nested tokens. To prevent lock- ups, the localization parser checks for cyclic token definitions, and if one is encountered the token will be simply replaced with '!ERROR!' and the offending localization string will be identified in the warning message written to standard error.

If and only if the localization token isn't reserved will the current localization language be queried. If no localization language is selected, or if there is no matching token defined in the current language, the token will simply be stripped of its curly braces in the returned string. Each language is required to have at least one token defined: &#123;&#123;LanguageID&#125;&#125;. This should represent the language name e.g. 'Français (French)'.

NOTE: This function requires the LOCALIZATION_ON flag to be set (see SetLocalizationMode) otherwise the function will simply return localizationstring$ exactly as it was passed (including any curly braces).

See Also: SetLocalizationMode, LocalizationMode, SetLocalizationLanguage and LocalizationLanguage.

SetLocalizationMode
Function SetLocalizationMode( mode:Int = LOCALIZATION_ON )

Description: Enable or disable the localization engine, and set other localization modes.

Information: The mode can be set to:

Either mode can be combined (btiwse OR'd) with LOCALIZATION_OVERRIDE, which will cause gadgets to become automatically 'localized' when they are created, with any text$ parameters supplied to the CreateGadget functions being interpreted as localization strings.

If any window menus are localized, UpdateWindowMenu may have to be called on all relevant windows for the text changes to be visible.

See Also: LocalizationMode, SetLocalizationLanguage, LocalizationLanguage and LocalizeGadget.

LocalizationMode
Function LocalizationMode:Int

Description: Returns the value previously set using SetLocalizationMode.

Information: The default value for a MaxGUI program is LOCALIZATION_OFF.

See SetLocalizationMode for valid modes, and their corresponding constants.

SetLocalizationLanguage
Function SetLocalizationLanguage( language:TMaxGUILanguage )

Description: Set the language to be used by MaxGUI's localization system.

Information: Languages can be loaded from files/streams using LoadLanguage and created from scratch using CreateLanguage.

This function will automatically update the text of any gadget marked as 'localized' using LocalizeGadget.

If any window menus are localized, UpdateWindowMenu may have to be called on all relevant windows for the text changes to be visible.

See Also: LocalizationLanguage, SetLocalizationMode, LocalizationMode and LocalizeString.

LocalizationLanguage
Function LocalizationLanguage:TMaxGUILanguage

Description: Returns the current language used by MaxGUI's localization system.

Information: Use the DefineLanguageToken, RemoveLanguageToken and ClearLanguageTokens commands to add to and modify the returned language. SetLanguageName and LanguageName may also be useful.

Information: See Also: SetLocalizationLanguage, SetLocalizationMode, LocalizationMode and LocalizeGadget.