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.

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 ( #;: ).

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:

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.

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):

The value returned by the GCMemAlloced function (at the moment the token is parsed).

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:

Localization Token

Default Format

Sample Output

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

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: {{LanguageID}}. This should represent the language name e.g. 'Français (French)'.

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

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

Information: The mode can be set to:

Constant

Meaning

LOCALIZATION_OFF

Any localized gadgets will display their localizedtext$ as their actual text.

LOCALIZATION_ON

Localized gadgets will use the current language to display their text.

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.