Guiliani  Version 2.4 revision 5970 (build 3)
Internationalization

Introduction

Since most products will be aimed at an international market, with customers all over the globe, they need a multilingual user interface, which allows the users to operate it in their native language.

Developing a GUI in multiple languages imposes some challenges on the developer. The most obvious one is that texts should not be represented by simple strings within the source code anymore. If you wish to change them at runtime, or allow an external translation bureau to easily translate all texts, it soon becomes pretty clear that a dedicated language management mechanism is required. In Guiliani this can be found in form of the CGUILocalisationHandler class.

The localisation handler

The localisation handler (CGUILocalisationHandler) maps abstract text identifiers onto actual text strings in a given language. Having this mapping allows you to reference text independent of the chosen language, simply by its ID. When browsing through Guiliani's API you will therefore find that most interfaces will allow you to hand over a text either by a string or by using a text ID. If you simply wish to display a static non-internationalized text, then a string will do for you. In case you need a text to be translated when changing languages, use text IDs instead.

Accessing the localisation handler can be done comfortably via the GETLOCALEHDL helper macro. Its interface allows you to retrieve the string mapped to an ID, to set the string behind an ID, or to load a complete language file. Please refer to the localisation handler's API documentation for detailed help.

Language files

Language files for Guiliani are UTF-8 encoded plain text files. They are typically, though not necessarily, marked by the ending .lng. The order in which text strings appear line by line inside the language file must correspond to the order of the corresponding text IDs in the UserTextResource.h file. You can edit these files using your favourite editor as long as it supports reading/writing UTF-8 encoded files (e.g. the standard Windows Editor does support UTF-8). Be aware that the language-file must contain a BOM (Byte Order Mark) as the first three bytes. These bytes should thus read: 0xef, 0xbb, 0xbf.

Unicode strings

Most languages will use characters that are not part of the standard ASCII set. This is where Unicode comes into play. Without going into too much detail, as there is plenty of comprehensive documentation on this topic available on the web, it is important to know that Unicode is a standard for the consistent representation of text on computers, allowing you to represent almost any known written character, ranging from simple Latin, via Greek or Cyrillic, to Klingon.

Now there are various ways of encoding Unicode. An encoding maps (possibly a subset of) the range of Unicode code points to sequences of values in some fixed-size range, termed code values. The most common encodings are UTF-8 and UTF-16. Both have their advantages and disadvantages and depending on your target platform and font-engine of choice, it may be desirable to use one or the other. Guiliani features a smart string class called eC_String, which is capable of storing strings in either of the two formats, and to convert between them (and plain ASCII). You will notice that Guiliani will make use of this class and avoid using plain CHAR or WCHAR pointers.