Specifying Locales with NLS

  • Article

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

The national language support functions enable you to target an application for a specific locale. A locale is a collection of language-related user preference information represented as a list of values. Each system has at least one installed locale and often has many locales from which the user can choose.

The system assigns a locale to each thread. Initially, the system assigns the system default locale to the thread. This default locale is set by the user when the system is installed or through the Regional Settings program in Control Panel. If a thread is run in a process belonging to a user, the system assigns the user-default locale to the thread.

Each locale has a unique locale identifier (LCID), which is a 32-bit value that consists of a language identifier and a sort identifier. The LCID is constructed using the MAKELCID macro. The following illustration shows the format of the bits in an LCID.

+-------------+---------+-------------------------+
|   Reserved  | Sort ID |      Language ID        |
+-------------+---------+-------------------------+
31         20 19     16 15                      0   bit

The following locale identifiers are predefined:

  • LOCALE_SYSTEM_DEFAULT, which identifies the system default locale.
  • LOCALE_USER_DEFAULT, which identifies the locale of the current user.
  • LOCALE_NEUTRAL, which identifies the default language-neutral locale.

The LOCALE_NEUTRAL identifier is the same as LOCALE_USER_DEFAULT. An application can retrieve the current locale identifiers by using the GetSystemDefaultLCID and GetUserDefaultLCID functions.

Note

If you specify a locale with the LCID (Locale ID) parameter and that locale is not installed or available on the Windows® phone, the function fails with ERROR_INVALID_PARAMETER. To determine whether the locale is supported or not, call IsValidLocale.

A language identifier is a standard international numeric abbreviation for a country/region. Each language has a unique language identifier (LANGID), which is a 16-bit value that consists of a primary language identifier and a secondary language identifier. The LANGID is constructed using the MAKELANGID macro. The following illustration shows the format of the bits in a LANGID.

+-------------------------+-------------------------+
|  Secondary Language ID  |   Primary Language ID   |
+-------------------------+-------------------------+
15                    10  9                         0   bit

The following language identifiers are predefined:

  • LANG_SYSTEM_DEFAULT, which identifies the system default language.
  • LANG_USER_DEFAULT, which identifies the language of the current user.

An application can retrieve the current language identifiers by using the GetSystemDefaultLangID and GetUserDefaultLangID functions.

It is often necessary to get specific information on available languages and locales in order to handle strings appropriately. Each element of locale information has a corresponding LCTYPE constant. To get the locale information, call the GetLocaleInfo function with the constant that corresponds to the information that is needed.

Most LCTYPE constants are mutually exclusive, so usually only one type of information can be retrieved at a time. The exceptions to this are LOCALE_NOUSEROVERRIDE, LOCALE_USE_CP_ACP, and LOCALE_RETURN_NUMBER, which can combined with other LCTYPE constants by using the binary OR operator.

Locale information is always stored and manipulated as a null-terminated string. No binary data is allowed; any numeric values must be specified as text. Each type of information has a particular format. In addition, several of the types are linked together, so that changing one changes the value of the other as well.

Although a specified locale identifier may be supported, it is not available for use by an application unless it is also installed.

In This Section

  • Defining Calendar Formats
    Describes how to use the CALTYPE constants to specify a default and alternate calendar type for a locale.
  • Programming with Unicode and NLS
    Describes the Unicode standard, and shows how to work with Unicode surrogates. Describes how to specify locales with National Language Support (NLS).