Internationalization and Localization

The uDraw(Graph) user interface can be configured for most languages in order to provide native texts for the end user. The system is pre-configured for English (default) and German locales, but the text output of the user interface can be customized by experienced users to show character sets that are supported by the Unicode/UTF-8 encoding. Note that the layout of dialog windows cannot be manipulated, which might be inconvenient for languages not written from left to right. All text elements of the user interface are stored in plain language files that can be edited by the user.

Basics: Language Files and Language Keys

A language file contains a mapping between language keys and language values (both strings), so one key/value pair occurs in each line of the file. The value is the translation of the corresponding key for the particular language.

A separate language file is used for all available languages. The set of keys is identical in all files, so only the values may vary. A particular language file is chosen at initialization time by considering environment variable $UDG_LANG, see below. The language file is loaded into a translation table when starting uDraw(Graph). All text messages, buttons, menus etc. are represented by language keys internally. When a particular text (language key) has to be displayed, it is first converted into the native language according to the translation table.

This mechanism for internationalization can even be used by uDraw(Graph) applications. With command special(add_language(...)), the application can provide an additional language file with its own language keys and values. When the application extends or configures the uDraw(Graph) user interface by its own menus, icons etc., it can use the language keys (from both the application and preconfigured language files) for particular string parameters which are marked with type lang_string in the grammar for API commands and configuration files. Language keys can be used in a string parameter by starting with an initial "#%" sequence, followed by the key as it is written in the language file. You cannot use the language key inside of a larger string. Here is an example showing how to use a language key in the string parameter of an API command:

Position and naming of language files

The recommended default directory for all language files is directory "$UDG_HOME/lib/uDrawGraph". When uDraw(Graph) is started, it looks for the language file in the current start directory and afterwards in the default directory. The system will not start if it cannot find at least one language file according to the following selection rules.

All language file names look like "uDrawGraph_C.lang". This can be split into three parts, where the first one ("uDrawGraph_") and the last one (".lang") are fixed and the second part is the current language setting ("C" in this case which is the default language). The current language is retrieved from environment variable $UDG_LANG. So for example you can switch to the German user interface by setting "$UDG_LANG" to value "de" before starting uDraw(Graph). This will use the language file "uDrawGraph_de.lang", located in the default directory. After the start, the language setting is fixed.

Syntax and Layout of Language Files

The syntax of language files is very easy. At each line of the file, you have to use exactly two strings that are separated by white space. The first string is the language key and the second string is the language value, see example above. Please enclose the language value in double quotes, although this is only necessary when the the value contains white space. So in the example above, it would be a failure to replace the bullets by white space (e.g. no keys like "PrintDlg Landscape").

The language keys you can find in the "uDrawGraph_C.lang" default file are hard coded in uDraw(Graph), so if you want to provided an additional translation file, make sure that you keep the keys as is, especially the exact number. Some keys with particular endings have a special semantic, whereas all others may have an arbitrary string as value. For keys ending with ".mne", the value has to be an integer which specifies the position of the character that should be underlined in a menu and used as a mnemonic (see section about user interface configuration for more information). Here, a value of "-1" means no mnemonic. The keys ending with ".mod" define the modifier key used for keyboard bindings of menus and should only have the values Control, Meta, Alt, Shift or "" (for no modifier). The accelerator for the keyboard binding is defined by the language keys ending with ".acc". Their value should contain only a single character. Please note that accelerators have to be mutually exclusive with respect to the complete user interface and mnemonics have to be mutually exclusive for each menu.

To avoid mistakes, it is recommended to copy the standard language file "uDrawGraph_C.lang" in the default directory (see above) as a basis for a new language file.

Preconditions for Language Files

Every language file is checked against the default language file, so even if your actual language setting is different, the default file ("uDrawGraph_C.lang") must always be present to be used as reference. So make sure that you do not edit the default file in order to avoid serious problems. Each language file must declare a special key "Version" with the uDraw(Graph) version number the file is written for. The required number of language keys is hard coded in uDraw(Graph), so make sure that your own language files matches the default file with respect to the exact number and name of keys. A language value must be specified for all language keys in the file.