Locale Library

Introduction

Today, computer software is commonly marketed and used globally. But programs that work for users in one country or territory may not work so well in another, because local specifics can turn certain aspects into barriers hampering usability. An obvious barrier is language but there are others. For example, an accounting program would be an utter flop if it didn't support different numeric systems and currencies. Therefore, modern computer applications need to be designed to account for various local conditions, conventions and customs. Otherwise your product – free or commercial – can easily get rejected by users.

The process of adapting software to the linguistic, cultural and technical requirements of a local market is called localization. This process typically entails:

• translation of the application's user interface into the target language
• translation of the application's documentation and help files into the target language
• adaptation to specific writing conventions such as punctuation, number formatting, date and time format etc.
• use of local units of measurement, currency etc.
• use of language-specific sorting rules
• support for a particular character set
• adaptation of keyboard shortcuts (where mnemonics are desirable to be preserved)
• etc.

Amiga software developers are encouraged to use the Locale Library to localize their applications. Additional tools are also available to help in the process.

Locale

In the context of AmigaOS, the term locale refers to a set of parameters defining various language-specific and country-specific properties. Localized Amiga software takes these properties from system files stored on disk, instead of hardcoding them into the application. Thus, no recompiling is required: properly localized Amiga applications dynamically adapt themselves to the current locale.

Locale settings are made on the user level, from the Locale editor found in your Prefs drawer. For example, a Danish user would normally use the editor to select a Danish locale for his/her system.

Accessing Locale Parameters

The Locale Library provides access to the respective settings and parameters via a public data structure called, quite predictably, Locale (see the <libraries/locale.h> include file for definition; the structure is rather extensive). The programmer can query about the individual locale parameters by calling OpenLocale() and then reading from the data structure, the pointer to which is returned as the function result. You will also need this pointer if you want to use certain Locale Library functions.

OpenLocale() takes the name of the locale as parameter. Most applications will pass NULL, indicating the current system locale. The provided data structure is strictly read-only, and the pointer to it can no longer be used after you call CloseLocale().

The following code fragment opens the current system locale, prints the English name of the associated language (as retrieved from the Locale structure), and closes the locale:

struct Locale *currentLocale;
 
if ( (currentLocale = ILocale->OpenLocale(NULL)) )
{
   IDOS->Printf("The language of this locale is %s.\n", currentLocale->loc_LanguageName);
   ILocale->CloseLocale(currentLocale);
}

Standard Locale Strings

The library also provides a set of commonly-used strings, the localized versions of which are part of each locale. These "standard" strings include:

• the names of the days of the week (incl. their abbreviations and alternate forms)
• month names (incl. their abbreviations and alternate forms)
• time reference expressions like "today", "yesterday", "tomorrow" and "future"
• the "yes/no" strings used as response in requester gadgets
• the characters used as quotation marks in the particular language
• the native name of the language ("Deutsch" for German, "Français" for French, etc.).

An AmigaOS application – for example, a calendar or a personal organiser – will not provide these strings but, rather, obtain them from the locale using GetLocaleStr() and a respective string code as defined in <libraries/locale.h>.

The following code fragment opens the current system locale, prints the native name of the language and the localized name of the first month of the year, then closes the locale:

struct Locale *currentLocale;
 
if ( (currentLocale = ILocale->OpenLocale(NULL)) )
{
   IDOS->Printf("The native name of the language is %s.\n", 
                ILocale->GetLocaleStr(currentLocale, LANG_NAME));
   IDOS->Printf("The first month is called %s in this language.\n", 
                ILocale->GetLocaleStr(currentLocale, MON_1));
   ILocale->CloseLocale(currentLocale);
}

Environment Variables

Certain common locale parameters can also be retrieved from global environment variables that the library maintains. These include:

LanguageName

The name of the current default language as used in the system. This is the English name of the language, and it is the same value you would obtain from the loc_LanguageName field of the Locale structure as returned by OpenLocale(NULL).

Language

The name of the current default language as used in the system. This is the localized name of the language as it was used in the past, if available.

Charset

The MIME name of the current default character set as used in the system. Please note that this value does NOT correspond with that of the loc_CodeSet field of the Locale structure returned by OpenLocale(NULL). The Charset environmental variable contains the name of the character set (i.e. a string value), whereas loc_CodeSet provides its IANA number (that is, an integer value).

In a CLI environment (the Shell, for example) you can use the AmigaDOS GETENV command to retrieve and display the respective variable value:

1> GETENV LanguageName
czech

1> GETENV Charset
ISO-8859-2

In program code you need to call the DOS Library function GetVar(). The following snippet shows how to retrieve the name of the current character set:

char charSet[32];
 
if ( IDOS->GetVar("Charset", charSet, sizeof(charSet), GVF_GLOBAL_ONLY) != -1 )
 {
   IDOS->Printf("The current default character set is %s\n", charSet);
 }

Catalogs

For most applications (regardless of the operating system), the grunt of the localization work lies in translating the user interface. This typically involves the translation of all text strings that are used and displayed by the program: window titles, menu- and button labels, various program messages etc. In AmigaOS, all strings translated into a particular language are put into a special binary file called the catalog (also referred to as locale catalog or message catalog).

A separate catalog file is needed for every language that is to be supported by the application, except English. A localized Amiga application is required to provide a full set of built-in strings in English to default to. These strings are part of the application executable and will be used if no catalog files are found – or, of course, if the English language is selected for the current locale.

(to be continued)

Function Reference

The following table gives a brief description of the Locale Library functions. See the SDK/Autodocs for details about each call.

Function	Description
CloseCatalog()	Close a message catalog.
CloseLocale()	Close a locale.
ConvToLower()	Convert a character to lower case.
ConvToUpper()	Convert a character to upper case.
FormatDate()	Generate a date string based on a date formatting template.
FormatString()	Format data into a character stream, assume 16bit-aligned data.
FormatString32()	Format data into a character stream, assume 32bit-aligned data.
GetCatalogStr()	Get a string from a message catalog.
GetLocaleStr()	Get a standard string from a locale.
IsXXXX()	A set of similarly-named functions to determine whether a character is of a certain type.
OpenCatalog()	Open a message catalog.
OpenLocale()	Open a locale.
ParseDate()	Interpret a string according to the date formatting template and convert it into a DateStamp.
StrConvert()	Transform a string according to collation information.
StrnCmp()	Localized string comparison.