<< AmigaBasic
>> WindowPtr

How do I localize my program?

Suggest, you want to write a HelloLocalWorld.c. Your final program will look like this:

    #include "HelloLocalWorld_Cat.h"
    #include <clib/exec_protos.h>

    struct Library *LocaleBase;

    void main(int argc, char *argv[])

        /* Open the locale.library. No kill, if not successfull.
           (Just use the builtin catalog strings instead.) Note, that
           we open locale.library here, even if our compiler supports
        LocaleBase = OpenLibrary("locale.library", 38);
        OpenHelloLocalWorldCatalogs(NULL, NULL);


        if (LocaleBase) CloseLibrary(LocaleBase);

The routine GetString checks, if the wished catalogs are available and returns a pointer to either the builtin string or the catalog string. (In my case the german string.)

You see, the main difference besides the minor opening and closing stuff (OpenLibrary, OpenHelloLocalWorldCatalogs, ...) is to replace strings with a function call. Hence we need a file `HelloLocalWorld_Cat.c', which holds OpenHelloLocalWorld, GetString, CloseHelloLocalWorld and the builtin strings (this could be an array, where

        array[MSG_Hello] = "Hello, local world.\n";
is defined) and an include file `HelloLocalWorld_Cat.h', which defines the message ID's like MSG_Hello. You don't need to know, how these files work internally, especially you don't need to know locale.library!

There are some catalog generators (in what follows: CGs) available (`CatComp', for devlopers only, KitCat, german docs only, `MakeCat', which I don't know and FlexCat, which I recommend, because it is most flexible in the generated source and supports catalogs on 2.0 and any language, even Amiga-E, Cluster, Pascal, ... and besides that: I'm the author ;-) are tools, that create HelloLocalWorld_Cat.h, HelloLocalWorld_Cat.c and the real catalogs for you. (The above code might differ slightly between the different CGs.) (See Aminet, directory `dev/misc'.)

Of course they need to know how to use them. First create a so-called catalog-description file. This could look like this:

    ; Lines beginning with a semicolon are comment lines.
    # language english
    ; the language of the builtin strings
    # version 0
    ; the catalog version (0 = any)
    MSG_Hello (1/15/30)
    Hello, local world
Any string is defined by a line like the last two lines above: MSG_Hello is the message-ID, (1/15/30) says, that the value of MSG_Hello should be 1 (you may omit this, in which case just the next free number is used) and the string must not be shorter than 15 characters or longer than 30 characters. (These may be omitted too.)

Now write your program. Once you are ready, use the CGs to create a so-called catalog translation file. (One for any language different than the builtin.) In my case (german) this could look like this:

    ; Lines beginning with a semicolon are comment lines.
    ## language deutsch
    ; the catalog language (german)
    ## version $VER: Deutsch.catalog 1.0 (22.12.93)
    ; the catalog files version string

    ; Hello, local world
Note the empty line after the message ID. (The arguments of ## language and ## version would be missing as well.) You have to fill in the german strings here. Again using the CGs you create a catalog file from this. Additionally note, that no informations on the strings ID or length are behind MSG_Hello. They are taken from the catalog description file.

Once you change the program (adding strings, changing the string length) you change the catalog description as well, use the CGs in the same way to update the catalog translation and hence the catalogs.

<< AmigaBasic >> WindowPtr