### Locale Classes

This file contains information about the following subjects:

- Access to Locale Resources
- Locale Iteration

The locale classes consist of ILocaleKey, which gives you access to the resources associated with a particular locale, and ILocaleKeyIterator, which lets you iterate through the locally installed locales.

This figure illustrates how locales can be grouped by language (as for English) or by geographical location (as for Switzerland):

#### Access to Locale Resources

The primary class you use to work with locales is ILocaleKey. ILocaleKey acts as an identifier for a specific locale and is used as a parameter for functions that create a particular type of localizable object. For example, the ICollation::createCollation function takes an ILocaleKey object that indicates what language the collation should reflect. On the other hand, the ILocaleKey::displayName function lets you display the locale name in any language for which a name is provided. Each type of international object should provide a displayName function, such as ICollation::displayName.

When you need a localized object, create an ILocaleKey object to define the locale with which to associate the object. A given object can be associated with more than one locale. Thus, a collation object for English could be associated with many--or even all--English-speaking locales (United States, Canada, United Kingdom, Jamaica, and so on). The set of objects associated with a locale can be open-ended; you are free to associate new objects with the locale.

Use ILocaleKey to identify the locale for which you want to access localized resources. You can use ILocaleKey to specify a particular locale (such as U.S. English) or to specify the default locale on the current host. ILocaleKey gives you access to both host-specific and portable objects associated with a given locale.

ILocaleKey supports two ways to describe a specific locale:

- Using the host locale ID (an `unsigned long` value) for the current platform. For example, on Win32 platforms the locale identifier for United States English is 0x0409.
- Using the portable POSIX identifier. This has three parts:
  - A two-character language identifier, for example, "EN" for English or "ZH" for Chinese.
  - A two-character region identifier, for example, "US" for the United States or "TW" for Taiwan.
  - A single-character extension used in a few cases where the standard "language_region" POSIX identifier maps to multiple, distinctive locales. For example, the "NO_NO" identifier maps to both the Bokmâl Norwegian and Nynorsk Norwegian locales. An extension lets you provide a unique identifier for each.

When you use a locale key to obtain an object for a given locale, the system does the following:

1. If there is a corresponding host object for that locale, the system returns it.
2. If there is no corresponding host object for that locale, the system looks for an object that corresponds to the same language.
3. If there are no corresponding host objects, the system looks for a corresponding portable object.
4. If there is no corresponding portable object, the system throws an exception.

This figure shows the interface for ILocaleKey:

- languageID and setLanguageID let you access the language identifier portion of the locale ID. Two special language identifiers, "C" and "POSIX," indicate the POSIX C locale. If you specify one of these language identifiers, the region and extension are set to null. If you set the language identifier to a null string, the locale key is set to the default host locale.
- regionID and setRegionID let you access the region identifier portion of the locale ID.
- extension and setExtension let you access the extension used to uniquely identify locales whose POSIX IDs map to more than one locale.
- posixID and setPosixID let you access the entire POSIX identifier string. This string has the format "fLanguageID_fRegionIDfExtension," for example, "ES_ESM."
- hostID and setHostID let you access the host identifier.
  (hostID and setHostID are supported only on Windows platforms.)
- isCLocale indicates whether the locale key references the C (POSIX) locale.
- defaultLocale is a static function that returns a locale key for the current default locale.
- displayName returns a localized, displayable name for the locale. You specify the locale in which to display the name and a lookup strategy for finding the name:
  - kExactLocale--Return the display name only for the exact locale specified.
  - kExactLanguage--If there is no name for the exact locale specified, return the name from another locale with the same language identifier.
  - kAnyLanguage--If there is no name in the specified locale or language, return the name in the default locale and language. This is the default option.

#### Locale Iteration

Use ILocaleKeyIterator to iterate through the locales available on the current hosts. Because ILocaleKeyIterator iterates through currently installed locales (rather than all locales supported by the locale mechanism), it may not reflect the full set of supported locales. You do not need to initialize an ILocaleKeyIterator object--when constructed, it automatically references the first locale key in the list.

This figure shows the interface for ILocaleKeyIterator:

- operator* returns the locale key referenced by the iterator.
- operator-> returns a `const` pointer to the locale key referenced by the iterator.
- operator++ and operator-- advance the iterator to the next or previous locale key.
- reset sets the iterator to reference the first locale key.
- operator bool and end return `true` if the iterator references the last locale key.

Locale Names

Getting a Key for a Locale
Getting an Object from the Current Default Locale
Getting an Object from a Specific Locale
Iterating Through Available Locales