Localization

This is a localization module utilizing the power and speed of the BaH.Libxml module to enable you to create and use easily maintainable localization files.

What is Localization?

Localization allows you to create an application (or game) that works in more than one language. This gives your application appeal to a much wider audience than it might otherwise. Many commercial applications support different languages (or locales), usually accessible via a menu option or preferences.

The International Standards Organization (ISO) is a body which, amongst other things, maintains a list of world-wide languages. Each language has a two letter (ISO 639-1) or three letter (ISO 639-2) code representation. For example, the two-letter ISO code for English is "en".
The Locale module caters for all two letter ISO codes, and some of three letters. In all, the Locale module knows about 190 individual languages.

In addition to the language codes with their English names, the Locale module includes (for most of the entries) the language name in its native script. For example, the entry for "de" has "German" as the English text, and "Deutsch" as the native text.
This could allow you, for instance, to include a native language selection menu, rather than a list of languages in English.

How do I localize my program?

Normally, when you write your application, you embed the text (for button, label, DrawText, etc) directly in the code,

CreateButton("Save", 100, 90, 100, 28, window)

..

DrawText "Press Fire To Start", 460, 500

Rather than hard-coding text into your application you store all the text in an external Blitz Locale File (BLF) which is loaded when the application starts. Then, when you want to display a piece of text, you call the GetLocaleText function using a specific "tag" that represents the word or sentence :

CreateButton(GetLocaleText("save"), 100, 90, 100, 28, window)

..

DrawText GetLocaleText("firetostart"), 460, 500

It's as simple and easy as that.

Since the Locale module is designed with flexibility in mind, you can of course call GetLocaleText with the desired Locale as a parameter too. Which ever way suits your needs best.

What does the BLF file look like?

The Blitz Locale File format is basically an XML file. This is what a (very small) BLF file might look like:

<?xml version="1.0" encoding="UTF-8" ?>
<locale default="en">
	<tag name="apptitle">
		<trans lang="en">Blitz Locale File Builder</trans>
	</tag>
	<tag name="menuopen">
		<trans lang="en" value="79">&Open</trans>
		<trans lang="af" value="79">&Oop</trans>
	</tag>
</locale>

As you can see, the format is very simple: A tag with a list of translated texts.
When you want to add a new supported language, you add the required <lang... entries for each tag. No recompilation is usually required (unless the BLF file is incbin'd, of course).

How about some examples

There are a few examples to help you get to grips with the Locale module, as well as a fully working application (see the next section).
The examples consist of :

• example_01.bmx - Loads a multi-language BLF file and outputs each set of translations in turn to the console.
• example_02.bmx - Displays a list of all the system locale entries.

I'm lazy. Isn't there a utility program to help make BLF files?

Available from within the locale.mod folder is another named "utils". Here you will find a small GUI application (with source) called BLFBuilder. (Note: to compile this, you will need the MaxGUI module).
BLFBuilder can be used to create and maintain BLF files if you'd rather not create them yourself by hand. As you'd expect, it supports all the languages of the Locale module, and makes the task of maintaining your BLF files a breeze. In fact, BLFBuilder itself was used to create its own BLF file!

Using BLFBuilder

The main window consists of three areas :

1. List of tag names which are used by your application in calls to GetLocaleText.
2. Languages in use for this particular BLF file.
3. The actual tag text for the specific language.

To add a new tag, click on Add in the Tags section. This creates a new entry "NEWTAG" which you can rename.

Once you have decided on the name of your tag, you need to select a language with which to apply some text to the tag. When you initially select a language that has no text associated to the particular tag, it is indicated in the Tags list by a plus-sign (+) next to the tag name. This lets you know which tags need some text.

Selecting a language enables the Text section, where you are free to add as much text for the tag as you need, including newlines and tabs.
There is also an optional "value" field you can use to set an integer. As with the text field, this value is both tag and language specific.

Obviously, the most important feature of the Locale module is that it handles multiple languages. So you will probably find a time when you need to add a new language to your BLF file. In the Language section, you simply click on Add to bring up the new language selection window. This window lists ALL languages not currently in use by your current BLF file. Simply scroll to the language you wish to add, select it, and press OK.

The new language will appear in both the languages list and the Default language combobox.
As before, choosing this new language will cause the Tags list to show which of the tags do not currently have text for that particular language. Once you've added some text, the Tag list will reflect the new status of that tag.

The View menu enables you to change the way languages are displayed, either in English or the native script.

You can switch between either, at any time, and the lists are updated immediately. The language selection window will also display them in their native script.

Since BLFBuilder is built on top of the Locale module framework, it is also multilingual. The Language menu allows you to switch freely between any of the currently support languages.

All the various texts throughout the application will be changed when a different language is chosen.

Functions Summary

Functions

Module Information