CultureInfo Class

The CultureInfo class specifies a unique name for each culture, based on RFC 4646 (Windows Vista and later). The name is a combination of an ISO 639 two-letter lowercase culture code associated with a language and an ISO 3166 two-letter uppercase subculture code associated with a country or region.

Note
When passed to a class constructor or a method such as CreateSpecificCulture or GetCultureInfo, the case of a culture name is not significant.

The format for the culture name is languagecode2-country/regioncode2, where languagecode2 is the language code and country/regioncode2 is the subculture code. Examples include ja-JP for Japanese (Japan) and en-US for English (United States). In cases where a two-letter language code is not available, a three-letter code derived from ISO 639-2 is used.

Note that some culture names also specify an ISO 15924 script. For example, "-Cyrl" specifies the Cyrillic script and "-Latn" specifies the Latin script. On Windows Vista and later, a culture name that includes a script is rendered by using the pattern languagecode2-scripttag-country/regioncode2. An example of this type of culture name is uz-Cyrl-UZ for Uzbek (Cyrillic, Uzbekistan). On Windows operating system versions before Windows Vista, a culture name including a script is rendered using the pattern languagecode2-country/regioncode2-scripttag; for example, uz-UZ-Cyrl for Uzbek (Cyrillic, Uzbekistan).

A neutral culture is specified by only the two-letter lowercase language code. For example, "fr" specifies the neutral culture for French, and "de" specifies the neutral culture for German.

Note
There are two culture names that contradict this rule. The cultures Chinese (Simplified), named zh-Hans, and Chinese (Traditional), named zh-Hant, are neutral cultures. The culture names represent the current standard and should be used unless you have a reason for using the older names "zh-CHS" and "zh-CHT".

A culture identifier is a standard international numeric abbreviation and has the components necessary to uniquely identify one of the installed cultures. Your application can use predefined culture identifiers or define custom identifiers.

Certain predefined culture names and identifiers are used by this and other classes in the System.Globalization namespace. Detailed culture information appears in the National Language Support (NLS) API Reference at the Go Global Developer Center.

Remember that the culture names and identifiers represent only a subset of cultures that can be found on a particular computer. Windows versions or service packs can change the available cultures. Applications add custom cultures using the CultureAndRegionInfoBuilder class. Users add their own custom cultures using the Microsoft Locale Builder tool. Microsoft Locale Builder is written in managed code using the CultureAndRegionInfoBuilder class.

Several distinct names are closely associated with a culture, notably the names associated with the following class members:

• CultureInfo.ToString

• CultureInfo.Name

• CompareInfo.Name

See Names Associated with a CultureInfo Object for a discussion of the relationship among these names.

The cultures are generally grouped into three sets: invariant cultures, neutral cultures, and specific cultures.

An invariant culture is culture-insensitive. Your application specifies the invariant culture by name using an empty string ("") or by its identifier. InvariantCulture defines an instance of the invariant culture. It is associated with the English language but not with any country/region. It is used in almost any method in the Globalization namespace that requires a culture.

A neutral culture is a culture that is associated with a language but not with a country/region. A specific culture is a culture that is associated with a language and a country/region. For example, fr is the neutral name for the French culture, and fr-FR is the name of the specific French (France) culture. Note that Chinese (Simplified) and Chinese (Traditional) are also considered neutral cultures.

Creating an instance of a CompareInfo class for a neutral culture is not recommended because the data it contains is arbitrary. To display and sort data, specify both the language and region. Additionally, the Name property of a CompareInfo object created for a neutral culture returns only the country and does not include the region.

The defined cultures have a hierarchy in which the parent of a specific culture is a neutral culture and the parent of a neutral culture is the invariant culture. The Parent property contains the neutral culture associated with a specific culture. Custom cultures should define the Parent property in conformance with this pattern.

If the resources for a specific culture are not available in the operating system, the resources for the associated neutral culture are used. If the resources for the neutral culture are not available, the resources embedded in the main assembly are used. For more information on the resource fallback process, see Packaging and Deploying Resources.

The list of locales in the Windows API is slightly different from the list of cultures supported by the .NET Framework. If interoperability with Windows is required, for example, through the p/invoke mechanism, the application should use a specific culture that is defined for the operating system. Use of the specific culture ensures consistency with the equivalent Windows locale, which is identified with a locale identifier that is the same as LCID.

A DateTimeFormatInfo or a NumberFormatInfo can be created only for the invariant culture or for specific cultures, not for neutral cultures.

If DateTimeFormatInfo.Calendar is the TaiwanCalendar but the Thread.CurrentCulture is not set to "zh-TW", then DateTimeFormatInfo.NativeCalendarName, DateTimeFormatInfo.GetEraName, and DateTimeFormatInfo.GetAbbreviatedEraName return an empty string ("").

When preparing software to handle custom cultures, consider the following:

• Custom cultures can have values that exceed the ranges of the Microsoft-shipped cultures. For example, some cultures have unusually long month names, unexpected date or time formats, or other unusual data.

• Respect the user's culture data values; for example, the user might want a 24-hour clock or a yyyyMMdd date format.

• Remember that custom cultures override default values. Therefore, you cannot consider culture data to be stable. Country names, date formats, spellings, etc., will probably change in the future. If your application needs to serialize using this data, as for the DateTime formatting and parsing functions, it should use the invariant culture or a specific format.

Except for the invariant culture, culture data is dynamic. This is true even for the predefined cultures. For example, countries or regions adopt new currencies, change their spellings of words, or change their preferred calendar, and culture definitions change to track this. Custom cultures are subject to change without notice, and any specific culture might be overridden by a custom replacement culture. Also, as discussed below, an individual user can override cultural preferences. Applications should always obtain culture data at run time.

Caution
When saving data, your application should use the invariant culture, use a binary format, or use a specific culture-independent format. Data saved according to the current values associated with a particular culture, other than the invariant culture, might become unreadable or might change in meaning if that culture changes.

When a CultureInfo object is serialized, all that is actually stored is Name and UseUserOverride. It is successfully de-serialized only in an environment where that Name has the same meaning. The following three examples show why this is not always the case:

• If CultureTypes indicates CultureTypes.WindowsOnlyCultures, and if that culture was first introduced in Windows Vista, it is not possible to de-serialize it on Windows XP. Similarly, if the culture was first introduced in Windows XP Service Pack 2, it is not possible to de-serialize it for a Windows XP system on which the culture has not been installed.

• If CultureTypes indicates CultureTypes.UserCustomCulture, and the computer on which it is de-serialized does not have this user custom culture installed, it is not possible to de-serialize it.

• If CultureTypes indicates CultureTypes.ReplacementCultures, and the computer on which it is de-serialized does not have this replacement culture, it de-serializes to the same name, but not all of the same characteristics. For example, if "en-US" is a replacement culture on computer A, but not on computer B, and if a CultureInfo object referring to this culture is serialized on computer A and de-serialized on computer B, then none of the custom characteristics of the culture are transmitted. The culture de-serializes successfully, but with a different meaning.

Starting in the .NET Framework version 2.0, the CultureInfo constructor supports using Windows locales, which are equivalent to cultures, to automatically generate cultures that do not exist in the .NET Framework. For more information, see Cultures Generated from Windows Locales.

The user might choose to override some of the values associated with the current culture of Windows through the regional and language options portion of Control Panel. For example, the user might choose to display the date in a different format or to use a currency other than the default for the culture. In general, your applications should honor these user overrides.

If UseUserOverride is true and the specified culture matches the current culture of Windows, the CultureInfo uses those overrides, including user settings for the properties of the DateTimeFormatInfo instance returned by the DateTimeFormat property, and the properties of the NumberFormatInfo instance returned by the NumberFormat property. If the user settings are incompatible with the culture associated with the CultureInfo, for example, if the selected calendar is not one of the OptionalCalendars, the results of the methods and the values of the properties are undefined.

For cultures that use the euro, .NET Framework and Windows XP set the default currency as euro. However, older versions of Windows do not. Therefore, if the user of an older version of Windows has not changed the currency setting through the regional and language options portion of Control Panel, the currency might be incorrect. To use the .NET Framework default setting for the currency, the application should use a CultureInfo constructor overload that accepts a useUserOverride parameter and set it to false.

The Spanish (Spain) culture uses two culture identifiers, 0x0C0A using the default international sort order, and 0x040A using the traditional sort order. If the CultureInfo is constructed using the es-ES culture name, the new CultureInfo uses the default international sort order. For the traditional sort order, the object is constructed using the name es-ES_tradnl. For information on other cultures that have alternate sorts, see Comparing and Sorting Data for a Specific Culture.

This class implements the ICloneable interface to enable duplication of CultureInfo objects. It also implements IFormatProvider to supply formatting information to applications.

There are unique considerations when using a thread associated with a CultureInfo object. For more information about cultures and application domains, see Application Domains and Threads.