Describing a Culture with LDML Data
When your application saves a culture with Save, the resulting XML representation of the CultureAndRegionInfoBuilder object follows the format of Locale Data Markup Language (LDML) version 1.1. The CreateFromLdml method is the inverse of Save, and loads from this XML file.
Most of the meaningful data that describes a culture is contained in special elements within the XML file. LDML special elements allow for product-specific annotation and data.
The .NET Framework uses the special element to contain data drawn from the msLocale schema, https://schemas.microsoft.com/globalization/2005/carib/ldml. As is normal for a schema, this URI provides a unique name but is not the URL of an actual document.
Most of the relevant XML elements correspond to properties or return values from methods of the classes that describe a culture, such as CultureAndRegionInfoBuilder and CultureInfo. A small number of elements are specific to Windows instead of the .NET Framework, and are not included as properties of CultureAndRegionInfoBuilder.
For more information about the LDML standard, see Unicode Technical Standard #35, "Locale Data Markup Language (LDML)," at the Unicode home site.
Windows-only Elements
Several elements in this topic are described as "Windows only". They are relevant for unmanaged Windows code, but are not relevant for the .NET Framework. If your application creates an LDML file outside of the .NET Framework, and uses the framework to register it, the file becomes available to Windows as well as to the .NET Framework. In the .NET Framework, if your application starts with an existing culture definition, then modifies and saves it as a custom culture, the Windows-only elements pass through intact from the original culture to the saved culture.
Identity Elements
The following table describes the identity elements.
Element |
Notes |
---|---|
version |
LDML 1.1; format is <version number="1.1">ldml version 1.1</version> |
generation |
Time when the date file was generated, for example, <generation date="2006-08-28" /> |
special |
A container, with all content drawn from the msLocale schema |
The following are identity/special elements. Except as noted, all values are specified by the type attribute. For example:
<identity>
…
<special xmlns:msLocale="https://schemas.microsoft.com/globalization/2005/carib/ldml">
<!-- A typical case… -->
<msLocale:cultureAndRegionInfoName type="en-US-fabricam"/>
...
<!-- …but here are some examples that use CDATA -->
<msLocale:geoId>244</msLocale:geoId>
<msLocale:languageIsoName type="twoLetters">
en
</msLocale:languageIsoName>
...
</special>
</identity>
The following table describes properties and methods corresponding to the identity elements.
Element |
Property/method |
Notes |
---|---|---|
msLocale:cultureAndRegionInfoName |
Examples: "en", "en-US", "en-US-fabricam" |
|
msLocale:cultureAndRegionModifier |
Used only for neutral cultures; type is always "neutral" |
|
msLocale:cultureInfoVersion |
N/A |
Currently, "1.0" |
msLocale:geoId |
Example: "244"; this value is specified as text CDATA, instead of with a type attribute. |
|
msLocale:parentName |
Example: "en" |
|
msLocale:specificCulture |
Example: "en-US"; relevant only for neutral cultures, where it indicates the default specific culture |
|
msLocale:languageNameAbbr |
Example: "ENU" |
|
msLocale:languageIsoName type="threeLetters" |
Example: "eng"; this value is specified as text CDATA, instead of with a type attribute; type is "threeLetters" |
|
msLocale:languageIsoName type="twoLetters" |
Example: "en"; this value is specified as text CDATA, instead of with a type attribute; type is "twoLetters" |
|
msLocale:nativeDisplayName |
Examples: "English (United States)", "Deutsch (Deutschland)" |
|
msLocale:englishName |
Examples: "English (United States)", German (Germany) |
|
msLocale:countryCode |
N/A |
Windows only; value is specified as CDATA; with the sole exception of Canada ( code 2), this value is identical to the International Calling Code for telephony; on Windows, it is accessed through GetLocaleInfo or GetLocaleInfoEx with the LCTYPE specified as LOCALE_ICOUNTRY |
msLocale:regionNativeName |
Examples: " United States", " Deutschland" |
|
msLocale:regionEnglishName |
Examples: "United States", "Germany" |
|
msLocale:regionIsoName type="threeLetters" |
Example: "USA"; this value is specified as text CDATA, instead of with a type attribute; type is "threeLetters" |
|
msLocale:regionIsoName type="twoLetters" |
Example: "US"; this value is specified as text CDATA, instead of with a type attribute; type is "twoLetters" |
|
msLocale:textInfoName |
Example: "en-US" |
|
msLocale:sortName |
Examples: "en-US", "de-DE_phoneb" |
|
msLocale:ietfLanguageTag |
Example: "en-US" |
|
msLocale:englishLanguage |
Windows only |
Examples: "English", "German" |
Layout Element
The following table describes the layout element.
Element |
Notes |
---|---|
special |
A container; all content comes from the msLocale schema |
The element in the following table falls under layout/special.
Element |
Property/method |
Notes |
---|---|---|
msLocale:direction |
Text layout direction, which can have the following values:
Example: <msLocale:Direction type="left-to-right" /> |
Characters Element
The following table describes the characters element.
Element |
Notes |
---|---|
special |
A container; all content comes from the msLocale schema |
The following table describes characters/special elements. Except as noted, all values are specified by the type attribute.
Element |
Property/method |
Notes |
---|---|---|
msLocale:keyboardLayout |
Value is handled as CDATA |
|
msLocale:consoleFallbackName |
Example: "en-US" |
|
msLocale:fontSignature |
N/A |
A container for further content from the msLocale schema |
mslocale:scripts |
N/A |
A container for further content from the msLocale schema |
The following elements fall under characters/special/msLocale:fontSignature:
msLocale:unicodeRanges
msLocale:defaultCodePages
msLocale:codePages
Each of these elements is strictly a container for further content drawn from the msLocale schema.
The elements in the following table fall under characters/special/msLocale:fontSignature/msLocale:unicodeRanges. All values are specified by the type attribute. This is Windows-only information and corresponds, in part, to the Windows LOCALESIGNATURE structure.
Element |
Property/method |
Notes |
---|---|---|
msLocale:range |
N/A |
Windows only; a value between 0 and 122, representing a bit number in the Unicode subset bitfield (USB), contained in the Windows FONTSIGNATURE structure; this element can occur multiple times |
msLocale:layoutProgress |
N/A |
Windows only; possible values:
|
The elements below fall under characters/special/msLocale:fontSignature/msLocale:defaultCodePages and characters/special/msLocale:fontSignature/msLocale:codePages:
msLocale:ansiCodePage
msLocale:ansiOemCodePage
msLocale:oemCodePage
Each of these elements is strictly a container for msLocale:codePage elements, having values specified by the type attribute.
Element |
Notes |
---|---|
msLocale:codePage |
A code page; must be appropriate to the element in which it is contained; for example, code page "1252" is a Windows ANSI code page and falls under msLocale:ansiCodePage; code page "932" is an ANSI/OEM code page, and falls under msLocale:ansiOemCodePage; code page "855" is an OEM code page, and falls under msLocale:oemCodePage |
Under characters/special/msLocale:fontSignature/msLocale:defaultCodePages should be one of the following:
A single msLocale:ansiOemCodePage element containing a single msLocale:codePage element
A single msLocale:ansiCodePage element containing a single msLocale:codePage element, and a single msLocale:oemCodePage element containing a single msLocale:codePage element
The msLocale:defaultCodePages data is Windows-only data. The characters/special/msLocale:fontSignature/msLocale:codePages data is also Windows-only information. It lists all code pages that can support the specified language and script. Therefore, it is possible for this list to have multiple code pages of the same type. For example:
<msLocale:codePages>
<msLocale:ansiCodePage>
...
</msLocale:ansiCodePage>
<msLocale:oemCodePage>
<msLocale:codePage type="864" />
<msLocale:codePage type="708" />
</msLocale:oemCodePage>
</msLocale:codePages>
The elements in the following table fall under characters/special/msLocale:fontSignature/msLocale:scripts. All values are specified by the type attribute. This is Windows-only information. There is no way to set this data in Windows, but it corresponds to the return of the Windows GetStringScripts function.
Element |
Property/method |
Notes |
---|---|---|
msLocale:script |
N/A |
Windows only; a four-letter IS0 15924 code for a script, such as "Latn" (Latin) or "Cyrl" (Cyrillic); this element can occur any number of times |
Measurement Elements
The following table defines the elements that fall under measurement.
Element |
Property/method |
Notes |
---|---|---|
measurementSystem |
The type attribute is either "metric" or "US" |
|
paperSize |
N/A |
Windows only; this element is a container for a height and a width element; possible values are:
|
Dates Element
The only element that falls under dates is the calendars element. This is a container element only.
Note
The.NET Framework uses POSIX rules to interpret date and time formats from a standard LDML element, that is, an element drawn from the LDML namespace instead of the msLocale schema. For example, the AM/PM indicator is "a". Elements in the msLocale schema follow Microsoft rules for date and time formats. For example, the AM/PM designator is specified by the "tt" format pattern.
The following table describes elements that fall under dates/calendars. All values are specified by the type attribute.
Element |
Property/method |
Notes |
---|---|---|
default |
A default calendar; the type attribute is either "metric" or "US"; in Microsoft-generated files, the default calendar always matches AvailableCalendars[0] Possible calendar values are:
|
|
calendar |
Indicator for available calendars; this element can be repeated, once for each available calendar; possible type attribute values are the same as for default; this element also functions as a container for elements that provide data about the calendar Note For non-default calendars, this element is normally empty. Thus, if "Gregorian" and "Gregorian-US" are both available, and "Gregorian" is the default, the element for "Gregorian-US" is just <calendar type=" Gregorian-US" />. |
The elements in the following table fall under dates/calendars/calendar. All values are specified by the type attribute.
Element |
Property/method |
Notes |
---|---|---|
months |
N/A |
A container |
days |
N/A |
A container |
week |
N/A |
A container |
am |
CDATA specifies the text used to label a time before noon, for example, "AM" |
|
pm |
CDATA specifies the text used to label a time after noon, for example, "PM" |
|
dateformat |
N/A |
A container |
timeformat |
N/A |
A container |
Under dates/calendars/calendar/months is a single monthContext element, which must have the type attribute of "format". Under dates/calendars/calendar/months/monthContext should be four monthWidth elements.
Element |
Property/method |
Notes |
---|---|---|
monthWidth type="wide" |
A container |
|
monthWidth type="abbreviated" |
A container |
|
monthWidth type="genitive" |
A container |
|
monthWidth type="genitiveAbbreviated" |
A container |
Under dates/calendars/calendar/months/monthContext/monthWidth should be one month element for each month of the year. There should be 12 or 13 of these, depending on the calendar. For each months element, the type is the number of the month, and the CDATA type indicates the relevant string. For example:
...
<calendar type="Gregorian">
<months>
<monthContext type="format">
<monthWidth type="wide">
<month type="1">January</month>
<month type="2">February</month>
<month type="3">March</month>
...
</monthWidth>
<monthWidth type="abbreviated">
<month type="1">Jan</month>
<month type="2">Feb</month>
<month type="3">Mar</month>
...
</monthWidth>
...
</monthContext>
</months>
</calendar>
Under dates/calendars/calendar/days is a single dayContext element, which must have a type attribute of "format". Under dates/calendars/calendar/days/dayContext should be three dayWidth elements.
Element |
Property/method |
Notes |
---|---|---|
dayWidth type="wide" |
A container |
|
dayWidth type="abbreviated" |
A container |
|
dayWidth type="shorter" |
A container |
Under dates/calendars/calendar/days/dayContext/dayWidth should be one day element for each day of the week. For each day element, the type is one of the values "sun", "mon", "tue", "wed", "thu", "fri", "sat". The CDATA type indicates the relevant string. For example:
...
<calendar type="Gregorian">
<days>
<dayContext type="format">
<dayWidth type="wide">
<day type="sun">Sunday</month>
<day type="mon">Monday</month>
<day type="tue">Tuesday</month>
...
</dayWidth>
...
</dayContext>
</days>
</calendar>
The elements in the following table fall under dates/calendars/calendar/week.
Element |
Property/method |
Notes |
---|---|---|
firstDay |
Attribute day must be one of the following: "sun", "mon", "tue", "wed", "thu", "fri", "sat" |
|
special |
N/A |
A container; all content comes from the msLocale schema |
The elements in the following table fall under dates/calendars/calendar/week/special.
Element |
Property/method |
Notes |
---|---|---|
msLocale:weekRule |
The type attribute must be one of the following:
|
The element in the following table falls under dates/calendars/calendar/dateformats.
Element |
Notes |
---|---|
special |
A container; all content comes from the msLocale schema |
The elements in the following table fall under dates/calendars/calendar/dateformats/special. All values are specified by the type attribute.
Element |
Property/method |
Notes |
---|---|---|
msLocale:dateFormatLength type="long" |
A container |
|
msLocale:dateFormatLength type="short" |
A container |
|
msLocale:yearMonth |
A container for each relevant DateTime pattern; the type attribute specifies a unique zero-based index; there should be no gaps |
|
msLocale:monthDay |
A container |
The elements in the following table fall under dates/calendars/calendar/dateformats/special/msLocale:dateFormatLength. All values are specified by the type attribute.
Element |
Property/method |
Notes |
---|---|---|
msLocale:default |
N/A |
Value that corresponds to the type attribute of the default format; in Microsoft-generated LDML files, default is always "0" |
msLocale:dateFormat |
GetAllDateTimePatterns ('D'), GetAllDateTimePatterns ('d') |
A container for each relevant DateTime format pattern; the type attribute specifies a unique zero-based index; there should be no gaps |
The following elements are containers for msLocale:pattern elements that give their values as CDATA types:
dates/calendars/calendar/dateformats/special/msLocale:dateFormatLength /msLocale:dateformat
dates/calendars/calendar/dateformats/special/msLocale:yearMonth
dates/calendars/calendar/dateformats/special/msLocale:monthDay
For example:
<dateFormats>
<special xmlns:msLocale="https://schemas.microsoft.com/globalization/2005/carib/ldml">
<msLocale:dateFormatLength type="long">
<msLocale:default type="0"/>
<msLocale:dateFormat type="0">
<msLocale:pattern>dddd, MMMM dd, yyyy</pattern>
</msLocale:dateFormat>
<msLocale:dateFormat type="1">
<msLocale:pattern>MMMM dd, yyyy</pattern>
</msLocale:dateFormat>
...
</msLocale:dateFormatLength>
...
<msLocale:yearMonth type="0">
<msLocale:pattern>MMMM, yyyy</msLocale:pattern>
</msLocale:yearMonth>
<msLocale:yearMonth type="1">
<msLocale:pattern>mm, yy</msLocale:pattern>
</msLocale:yearMonth>
<msLocale:monthDay>
<msLocale:pattern>MMMM dd</msLocale:pattern>
</msLocale:monthDay>
</special>
</dateFormats>
The element in the following table falls under dates/calendars/calendar/timeformats.
Element |
Notes |
---|---|
special |
A container; all content comes from the msLocale schema |
The elements in the following table fall under dates/calendars/calendar/timeformats/special. All values are specified by the type attribute.
Element |
Property/method |
Notes |
---|---|---|
msLocale:durationFormats |
N/A |
Windows only; a container |
msLocale:timeFormatLength type="long" |
A container |
|
msLocale:timeFormatLength type="short" |
A container |
The elements in the following table fall under dates/calendars/calendar/dateformats/special/msLocale:durationFormats. All values are specified by the type attribute.
Element |
Property/method |
Notes |
---|---|---|
msLocale:default |
N/A |
Windows only; value corresponding to the type attribute of the default format; in Microsoft-generated files, the default is always "0" |
msLocale:durationFormat |
N/A |
Windows only. A container for each relevant DateTime value; the type attribute specifies a unique zero-based index; there should be no gaps |
The elements in the following table fall under dates/calendars/calendar/dateformats/special/msLocale:timeFormatLength. All values are specified by the type attribute.
Element |
Property/method |
Notes |
---|---|---|
msLocale:default |
N/A |
Value corresponding to the type attribute of the default format; in Microsoft-generated files, the default is always "0" |
msLocale:timeFormat |
GetAllDateTimePatterns ('T'), GetAllDateTimePatterns ('t') |
A container for each relevant DateTime value; the type attribute specifies a unique zero-based index; there should be no gaps |
The following elements are containers for msLocale:pattern elements that give their values as CDATA types:
dates/calendars/calendar/dateformats/special/msLocale:durationFormats/msLocale:durationFormat
dates/calendars/calendar/dateformats/special/msLocale:timeFormatLength/msLocale:timeformat
For example:
<timeFormats>
<special xmlns:msLocale="https://schemas.microsoft.com/globalization/2005/carib/ldml">
<msLocale:durationFormats>
<msLocale:default type="0" />
<msLocale:durationFormat type="0">
<msLocale:pattern>HH:mm:ss</msLocale:pattern>
</msLocale:durationFormat>
</msLocale:durationFormats>
<msLocale:timeFormatLength type="long">
<msLocale:default type="0"/>
<msLocale:timeFormat type="0">
<msLocale:pattern>h:mm:ss tt</msLocale:pattern>
</msLocale:timeFormat>
<msLocale:timeFormat type="1">
<msLocale:pattern>h:mm:ss a</msLocale:pattern>
</timeFormat>
...
</timeFormatLength>
...
</special>
</timeFormats>
Numbers Elements
The following table defines the elements that fall under numbers.
Element |
Notes |
---|---|
symbols |
A container |
currencies |
A container |
special |
A container; all content comes from the msLocale schema |
Elements Under numbers/symbols
The elements in the following table fall under numbers/symbols. Except as noted, these elements give their data as the CDATA type.
Element |
Property/method |
Notes |
---|---|---|
decimal |
Example: "." |
|
group |
Example: "," |
|
list |
Example: ";" |
|
percentSign |
Example: "%" |
|
infinity type="positive" |
Example: "Infinity" |
|
infinity type="negative" |
Example: "-Infinity" |
|
nan |
"Not a number" symbol. Example: "NaN". |
|
special |
N/A |
A container; all content comes from the msLocale schema |
The elements in the following table fall under numbers/symbols/special. Except as noted, these elements give their data as the CDATA type.
Element |
Property/method |
Notes |
---|---|---|
msLocale:currencyDecimalSeparator |
Example: "." |
|
msLocale:currencyGroupSeparator |
Example: "," |
|
msLocale:leadingZero |
N/A |
Windows only; no CDATA; type attribute must be either "yes" or "no" to allow or disallow leading zeros |
For example:
<symbols>
<decimal>.</decimal>
<group>,</group>
…
<infinity type="positive">Infinity</infinity>
<infinity type="negative">-Infinity</infinity>
…
<special xmlns:msLocale="https://schemas.microsoft.com/globalization/2005/carib/ldml">
<msLocale:currencyDecimalSeparator>
.
</msLocale:currencyDecimalSeparator>
<msLocale:currencyGroupSeparator>
,
</msLocale:currencyGroupSeparator>
<msLocale:leadingZero type="yes" />
</special>
</symbols>
Elements Under numbers/currencies
The element in the following table falls under numbers/currencies.
Element |
Notes |
---|---|
currency |
A container; type attribute must be specified as "default" |
The elements in the following table fall under numbers/currencies/currency. Except as noted, these elements give their data as the CDATA type.
Element |
Property/method |
Notes |
---|---|---|
symbol |
Example: "$" |
|
displayName |
Example: "Dollar" |
|
special |
N/A |
A container; all content comes from the msLocale schema |
The elements in the following table fall under numbers/currencies/currency/special. Except as noted, these elements give their data as the CDATA type.
Element |
Property/method |
Notes |
---|---|---|
msLocale:isoCurrency |
Example: "USD" |
|
msLocale:currencyEnglishName |
Example: "Dollar" |
For example:
<currencies>
<currency type="default">
<symbol>$</symbol>
<displayName>Dollar</displayName>
<special xmlns:msLocale="https://schemas.microsoft.com/globalization/2005/carib/ldml">
<msLocale:isoCurrency>USD</msLocale:isoCurrency>
<msLocale:currencyEnglishName>
Dollar
</msLocale:currencyEnglishName>
</special>
</currency>
The elements in the following table fall under numbers/currencies/special. All values are specified by the type attribute unless otherwise noted.
Element |
Property/method |
Notes |
---|---|---|
msLocale:decimalDigits |
Number of decimal places to use in numeric values, specified as CDATA; example: "2" |
|
msLocale:negativePattern |
Format pattern for negative numeric values |
|
msLocale:currencyDecimalDigits |
Number of decimal places to use in currency values; in contrast to msLocale:decimalDigits, this element is specified in the type attribute.Example: "2" |
|
msLocale:currencyPositivePattern |
Format pattern for positive currency values |
|
msLocale:currencyNagativePattern |
Format pattern for negative currency values |
|
msLocale:percentPositivePattern |
Format pattern for positive percent values |
|
msLocale:percentNagativePattern |
Format pattern for negative percent values |
|
msLocale:groupSizes |
Number of digits in each group to the left of the decimal in numeric values; actual grouping size is specified as the CDATA type; the type attribute serves to serialize this; there can be any number of these elements, each with a unique type attribute, serialized starting from "0"; value starts from the least significant group of digits |
|
msLocale:nativeDigits |
Native digits equivalent to the Western digits 0 through 9, one for each digit; the type attribute is a digit "0" through "9"; the CDATA type specifies the character used to represent a digit |
|
msLocale:digitSubstitution |
A value that specifies how the graphical user interface displays the shape of a digit; valid settings for the type attribute are:
|
For example:
<numbers>
...
<special xmlns:msLocale="https://schemas.microsoft.com/globalization/2005/carib/ldml">
<msLocale:decimalDigits>2</msLocale:decimalDigits>
<msLocale:negativePattern type="1"/>
<msLocale:currencyDecimalDigits type="2"/>
<msLocale:currencyPositivePattern type="0"/>
<msLocale:currencyNegativePattern type="0"/>
<msLocale:percentNegativePattern type="0"/>
<msLocale:percentPositivePattern type="0"/>
<msLocale:groupSizes type="0">3</msLocale:groupSizes>
<msLocale:currencyGroupSizes type="0">
3
</msLocale:currencyGroupSizes>
<msLocale:nativeDigits type="0">0</msLocale:nativeDigits>
<msLocale:nativeDigits type="1">1</msLocale:nativeDigits>
...
<msLocale:nativeDigits type="9">9</msLocale:nativeDigits>
<msLocale:digitSubstitution type="context"/>
</special>
</numbers>