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).

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).

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.