DOS, OS/2, and UNIX support the use of "country codes" for native language keyboard and text (character set display. Typically, applications that use country codes are developed specifically for a particular language. The country codes do not address the issue of text translation (substitution) between languages.

Some Windows applications developers use multiple resource files — one for each of the languages to be supported. StarView by Star Division takes this a step further: it allows a given resource file to include multiple text string definitions for each text instance. The string set (language) displayed can be configured as required. The disadvantages of using multiple resource files are:

• it requires multiple copies of the application's executable (one for each language);
• switching languages requires application exit, reconfiguration, and restart;
• the person translating the language must be able to use the resource editor;
• it does not address locale issues, such as date formats and monetary values;
• it is not portable to non-Windows environments. DLLs (Dynamic Linked Libraries), which are also used in Windows to provide multilingual support, are subject to similar problems.

It was originally developed to facilitate the design and construction of applications to be used in several European countries, which use many different native languages. The target system consisted of a network of OS/2 workstations used to present selection menus and process simple user input. The applications were to be entirely text-windows oriented, so as to allow users to pick and choose functions from displayed lists and options.

The specific requirements were:

• To support applications written in C.
• To be portable between OS/2, DOS, and UNIX platforms.
• To provide alternate keyboard and character-set support for non-English systems.
• To incorporate support for alternate date, time, monetary, and other locale-related issues.
• To allow for dynamic language switching (during application execution).
• To enable implementation of additional languages after application development without substantial redevelopment effort.
• To eliminate the need for application developers to be familiar with the languages the application would support.

Further, even though it was not designed with the Windows environment in mind, the functionality provided by Xlate does not preclude its use in Windows applications.

The Xlate routines described and demonstrated in this article are written for DOS using Borland C v3.1. Since the code does not use special compiler features, it will easily migrate to other C language compilation environments, including UNIX.

The strings to be replaced are referred to as "Keys," while the substituted strings are referred to as "Results." Keys and Results are created by a language translator (human) as text files, which are called translation files. Translation files have the file extension .trn.

The Xlate call XlateSet establishes the translation table that will be used (until another call to XlateSet is made). For performance reasons, the Xlate system builds the translation table in memory instead of working strictly from the file. To perform a translation, the application calls Xlate's Xlate function, providing it with a Key value. The Result string is returned. The following example shows how this would look in an application:

XlateSet("HELLO"); /* Establish a Translate File */
printf("%s\n", Xlate("Hello World!"));

One additional user-callable Xlate function, XlateFree, releases the allocated memory for any currently loaded translation file. It is not necessary to issue this call when switching translation files because XlateSet does this automatically. Several other Xlate functions, which are used internally and are not user-callable, are discussed later in the "Detailed Xlate Function Descriptions" section.

The second type of translate file is a binary representation of the text-based file, and must have the extension .trb. Using .trb files enhances the performance of the system. At run time, Xlate will attempt to find and load the .trb file. If Xlate can't find this binary file, it will load the text-based file (.trn) instead. You can create a .trb file from a .trn file by running a utility called SPEED_UP. You would normally use this utility after you have completed development and testing of your code. This utility is provided on this month's code disk.

For the purpose of reading an integer value into an application's variable, the translation file line may appear as

[Count][4] Integer number of menus available.

iCount = atoi(Xlate("Count"));

This technique can be used for many other types of configuration information, such as date and monetary formats, as will be shown later.

Even though the application must be written to accommodate the possibility of a variable number of items, the actual number can be defined by the translation file without requiring later modification of the source code.

YY/MM/DD    MM/DD/YY    DD/MM/YY
YY.MM.DD    DD.MM.YY    MM-DD-YY
YY-MM-DD    YYDDD       YYYY/MM/DD

The DateFormatter function in demodate.c (not listed here, but provided on this month's code disk), accepts month, day, and year values and builds the date string according to four entries in the translation file. The four translation file lines define the sequence of the month, day, and year in the date string, and provide the format string that will define the separators.

Time values (and other locale-specific data items) can be formatted for presentation using these techniques as well.

The actual translation (substitution) is triggered by a call to bsearch, which uses the passed-in Key string as the search value, and the translation table as the subject of the search. The XlateSearchCompare function is passed to the bsearch function to define the search method.

If the search fails to find a match, the default Key is used as the Key and the search is performed for that value. (If no default Key is found either, an error string is returned in English.)

Xlate returns a pointer to the Result for the key provided, or if not found, a pointer to the the string "?".

XlateLoad first calls XlateFree to remove any existing translation table from memory. It then attempts to open a binary version (.trb) of the translation file. If XlateLoad can open the binary file it calls function XlateLoadBinary to load the translation table. If XlateLoad can't open the binary file, it attempts to open the text version (.trn) and calls function XlateLoadText if successful.

The binary file's load process is a little more straightforward than its text-based counterpart. This is because the binary file contains a record explicitly indicating the number of Key/Result pairs to be loaded, while the text file does not. So the binary load can be done in one pass, while the text load requires two passes through the text file, once to count Key/Result pairs, and once to actually load them. Also, the text load function XlateLoadText must perform a sort step (done via qsort) which is not required of XlateLoadBinary, Note that XlateLoadText sorts only the Xlate pointers; the Key and Result values are not moved.

• ".TRB" as a file signature. (4 bytes)
• Integer number of translate Key/Result pairs. (2 bytes)
• Repeat for above number of Key/Result pairs of the following:
• Integer length of Key string including NULL terminator. (2 bytes)
• NULL-terminated Key string. (Length in bytes as indicated above.)
• Integer length of Result string including NULL terminator. (2 bytes)
• NULL-terminated Result string. (Length in bytes as indicated above.)
• EOF

XLATE *Xlatebase — a pointer to the translation table allocated in memory;

int XlateLines — the number of entries in the translation table, and

char XlateFile — the current translation file's name.

1. Open the translation file,

2. Read and parse the translation file, counting strings and passing over comments,

3. Rewind the translation file,

4. Allocate memory for the translation table,

5. Read and parse the translation file for Key and Result strings,

6. Allocate memory for the Key and Result strings, and finally,

7. Sort the translation table.

To speed up this process, I've created a utility called SPEED_UP which performs some of these steps for an application before the application is run. SPEED_UP reads a .trn file as input, and by borrowing some of Xlate's functions, builds an image of the translation table in memory. This image is identical to the one that would have been built by the application. After building the table, SPEED_UP writes it to a binary (.trb) file. When the application runs, it will perform only the following steps:

1. Open the translation file, (binary version)

2. Read the size of the table,

3. Allocate table memory,

4. Read Key and Result string lengths and values (No parsing required),

5. Allocate memory and copy Key and Result strings.

The advantage of using SPEED_UP is faster loading of the translation table at run time. The disadvantage is more difficulty in modifying and maintaining translation files. To minimize this disadvantage during development, I've made the Xlate system smart enough to use whichever version of the translation file it can find. (However, the Xlate system will always attempt to load the binary version first.) During development, the programmer need only supply text-based translation files. As long as no binary files are available, the system will automatically use the text-based files.

The source code for the SPEED_UP is included on this month's code disk. Since SPEED_UP uses several of the Xlate functions, module xlate.obj must be included in the link step.