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

## 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:
INI files support the following escape sequence characters:
| INI Escape Sequence | BlitzMax Equivalent |
| \r | ~r |
| \n | ~n |
| \t | ~t |
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 ( #;: ).
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:
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:
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.
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):
| Localization Token | Token Will Be Replaced With... |
| AppDir | The value of the AppDir global constant. |
| AppFile | The value of the AppFile global constant. |
| AppTitle | The value of the AppTitle global constant. |
| LaunchDir | The value of the LaunchDir global constant. |
| GCMemAlloced | 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) 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:
| 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.
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.