Locale.library

The most important functions of locale.library for localizing are OpenCatalog(), GetCatalogStr(), and CloseCatalog(). AROS applications often have the files locale.c and locale.h with some wrapper functions. The function "_" (yes, the underline is the function name) returns the string for a given message ID. It is written in such a way that it falls back to the built-in language when a catalog can't be opened. The function "__" additionally casts the string to an IPTR. This is useful for many Zune applications.

Note that a version number of 0 means that any version of the catalog can be opened, while any positive number means: open the catalog with the given version number.

locale.c:

#include <exec/types.h>
#include <proto/locale.h>

#define CATCOMP_ARRAY
#include "strings.h"

#define CATALOG_NAME     "myapp.catalog"
#define CATALOG_VERSION  3

struct Catalog *catalog;


CONST_STRPTR _(ULONG id)
{
    if (LocaleBase != NULL && catalog != NULL)
    {
        return GetCatalogStr(catalog, id, CatCompArray[id].cca_Str);
    }
    else
    {
        return CatCompArray[id].cca_Str;
    }
}

VOID Locale_Initialize(VOID)
{
    if (LocaleBase != NULL)
    {
        catalog = OpenCatalog(NULL, CATALOG_NAME, OC_Version, CATALOG_VERSION, TAG_DONE);
    }
    else
    {
        catalog = NULL;
    }
}

VOID Locale_Deinitialize(VOID)
{
    if(LocaleBase != NULL && catalog != NULL) CloseCatalog(catalog);
}

locale.h:

#ifndef _LOCALE_H_
#define _LOCALE_H_

#include <exec/types.h>

#define CATCOMP_NUMBERS
#include "strings.h"

CONST_STRPTR _(ULONG ID);       /* Get a message, as a STRPTR */
#define __(id) ((IPTR) _(id))   /* Get a message, as an IPTR */

VOID Locale_Initialize(VOID);
VOID Locale_Deinitialize(VOID);

#endif /* _LOCALE_H_ */

Modify the code of you application

Replace all strings which should be translate-able by a call of the "_" function with a message identifier as the parameter.

E.g. puts("Hello world"); becomes puts(_(MSG_HelloWorld));

These IDs must be unique and should give the translator a hint about the usage of the strings.

E.g.: MSG_ERR_Application, MSG_MEN_Open, MSG_GAD_Cancel

Include locale.h with #include "locale.h" in all source files which now contain message identifiers.

Call the functions Locale_Initialize at the init stage of your application, and call Locale_Deinitialize during its clean-up.

Catalog description file

The next step, is to create a catalog description file. Create a subdirectory with the name catalogs. Put a file with the name myapp.cd in this directory.

The format of this file is:

message ID (ID number/min. string length/max. string length)
native string

In most cases, you won't need the attributes within the round brackets and will simply write (//). No empty lines are allowed in the file, and comments start with ";".

Example:

MSG_HelloWorld (//)
Hello World
;
MSG_ERR_Application (//)
Can't create application
;
MSG_GAD_Cancel (//)
Cancel

If you want to split a string over several lines you have to append \ to the lines.

Build system

The locale.library searches for the catalogs in two places: PROGDIR:Catalogs and LOCALE:Catalogs, of which the latter should be used for AROS system applications only. A location should be decided upon, and a MetaMake file (mmakefile.src) should be created in the appropriate catalogs directory.

An example of a MetaMake file for catalogs in LOCALE:Catalogs, when you're localising an AROS system application:

include $(TOP)/config/make.cfg

%build_catalogs mmake=workbench-utilities-myapp \
            name=myapp subdir=System/Utilities

An example of a MetaMake file for catalogs in PROGDIR:Catalogs. The directory should be a subdirectory of your application's directory:

include $(TOP)/config/make.cfg

CATDIR := $(CONTRIBDIR)/Utilities/myapp/Catalogs

#MM contrib-utilities-myapp-catalogs

%build_catalogs mmake=contrib-utilities-myapp-catalogs \
            name=myapp subdir= dir=$(CATDIR)

The MetaMake file for the application has to take the MetaMake target for the catalogs as prerequisite. This ensures that the header with the strings is rebuild when the catalog description has changed.

If you have followed the instruction above, it would be a good idea to test whether the application still builds. Call make in the AROS directory.

If everything works well you should now have the file strings.h in the directory with the source code of your application.

Catalog translation file

Before starting a translation, LOCALE:Languages/ should be checked to see whether the intended language is indeed supported by AROS.

Once confirmed the application can finally be translated into another language. Enter the catalogs subdirectory and create a language translation file with the FlexCat tool. FlexCat must be in the search path. The file name must be same name as in LOCALE:Languages, but with a ct suffix, rather than language.

e.g.:

FlexCat myapp.cd NEWCTFILE=deutsch.ct
FlexCat myapp.cd NEWCTFILE=français.ct

The result file will look like this:

## version $VER: XX.catalog XX.XX ($TODAY)
## language X
## codeset 0
;
;
MSG_HelloWorld

; Hello World
;
MSG_ERR_Application

; Can't open application
;
MSG_GAD_Cancel

; Cancel

Replace the 'X' with valid information and fill the empty lines with the translated strings.

Sometimes the strings to be translated contain placeholders, like %d, %s, etc. It's important that you keep these placeholders in the translated strings in the same order.

FlexCat allows some control sequences, like \n (newline) and \f (formfeed). See the FlexCat documentation for more possibilities.

Complete translation file:

## version $VER: myapp.catalog 3.1 (18.04.2006)
## language deutsch
## codeset 0
;
;
MSG_HelloWorld
Hallo Welt
; Hello World
;
MSG_ERR_Application
Kann Applikation nicht erzeugen
; Can't create application
;
MSG_GAD_Cancel
Abbrechen
; Cancel

Note that the version number (in this case "3"), should match the version number used in OpenCatalog().

Now you can call make again to test if the catalogs are created.

Updating

One of the strengths of FlexCat is that it can update catalogs without deleting existing strings:

FlexCat myapp.cd deutsch.ct NEWCTFILE=deutsch.ct