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

CultureName

Examples: "en", "en-US", "en-US-fabricam"

msLocale:cultureAndRegionModifier

IsNeutralCulture

Used only for neutral cultures; type is always "neutral"

msLocale:cultureInfoVersion

N/A

Currently, "1.0"

msLocale:geoId

GeoId

Example: "244"; this value is specified as text CDATA, instead of with a type attribute.

msLocale:parentName

Parent

Example: "en"

msLocale:specificCulture

CreateSpecificCulture

Example: "en-US"; relevant only for neutral cultures, where it indicates the default specific culture

msLocale:languageNameAbbr

ThreeLetterWindowsLanguageName

Example: "ENU"

msLocale:languageIsoName type="threeLetters"

ThreeLetterISOLanguageName

Example: "eng"; this value is specified as text CDATA, instead of with a type attribute; type is "threeLetters"

msLocale:languageIsoName type="twoLetters"

TwoLetterISOLanguageName

Example: "en"; this value is specified as text CDATA, instead of with a type attribute; type is "twoLetters"

msLocale:nativeDisplayName

CultureNativeName

Examples: "English (United States)", "Deutsch (Deutschland)"

msLocale:englishName

CultureEnglishName

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

RegionNativeName

Examples: " United States", " Deutschland"

msLocale:regionEnglishName

RegionEnglishName

Examples: "United States", "Germany"

msLocale:regionIsoName type="threeLetters"

ThreeLetterISORegionName

Example: "USA"; this value is specified as text CDATA, instead of with a type attribute; type is "threeLetters"

msLocale:regionIsoName type="twoLetters"

TwoLetterISORegionName

Example: "US"; this value is specified as text CDATA, instead of with a type attribute; type is "twoLetters"

msLocale:textInfoName

TextInfo.CultureName

Example: "en-US"

msLocale:sortName

CompareInfo.Name

Examples: "en-US", "de-DE_phoneb"

msLocale:ietfLanguageTag

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

IsRightToLeft

Text layout direction, which can have the following values:

  • "left-to-right"

  • "right-to-left"

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

KeyboardLayoutId

Value is handled as CDATA

msLocale:consoleFallbackName

ConsoleFallbackUICulture

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:

  • "horizontalRightToLeft"

  • "verticalBeforeHorizontal"

  • "verticalBottomToTop"

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

IsMetric

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:

  • width = "216", height = "279" (Letter)

  • width = "216", height = "356" (Legal)

  • width = "297", height = "420" (A3)

  • width = "210", height = "297" (A4)

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

AvailableCalendars

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:

  • "Gregorian"

  • "Gregorian-US"

  • "Japanese"

  • "Taiwan"

  • "Korean"

  • "Hijri"

  • "Thai"

  • "Hebrew"

  • "Gregorian-ME-French"

  • "Gregorian-Arabic"

  • "Gregorian-XLIT-English"

  • "Gregorian-XLIT-French"

calendar

AvailableCalendars

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

AMDesignator

CDATA specifies the text used to label a time before noon, for example, "AM"

pm

PMDesignator

CDATA specifies the text used to label a time after noon, for example, "PM"

dateformat

N/A

A container

timeformat

N/A

A container

eras

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"

MonthNames

A container

monthWidth type="abbreviated"

AbbreviatedMonthNames

A container

monthWidth type="genitive"

MonthGenitiveNames

A container

monthWidth type="genitiveAbbreviated"

AbbreviatedMonthGenitiveNames

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"

DayNames

A container

dayWidth type="abbreviated"

AbbreviatedDayNames

A container

dayWidth type="shorter"

ShortestDayNames

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

FirstDayOfWeek

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

CalendarWeekRule

The type attribute must be one of the following:

  • firstDay

  • firstFourDayWeek

  • firstFullWeek

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"

GetAllDateTimePatterns('D')

A container

msLocale:dateFormatLength type="short"

GetAllDateTimePatterns('d')

A container

msLocale:yearMonth

GetAllDateTimePatterns('Y')

A container for each relevant DateTime pattern; the type attribute specifies a unique zero-based index; there should be no gaps

msLocale:monthDay

MonthDayPattern

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"

GetAllDateTimePatterns('T')

A container

msLocale:timeFormatLength type="short"

GetAllDateTimePatterns('t')

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>

The elements in the following table fall under dates/calendars/calendar/eras.

Element

Property/method

Notes

eraAbbr

GetEraName

A container

eraNames

GetAbbreviatedEraName

A container

Under both dates/calendars/calendar/eras/eraAbbr and dates/calendars/calendar/eras/eraNames should be one era element for each era. For each era element, the type is the number of the era, and the CDATA type indicates the relevant string. For example:

<eras>
   <eraAbbr>
      <era type="0">BC</era>
      <era type="1">AD</era>
   </eraAbbr>
   <eraNames>
      <era type="0">Before Christ</era>
      <era type="1">Anno Domini</era>
   </eraNames>
</eras>

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

NumberDecimalSeparator

Example: "."

group

NumberGroupSeparator

Example: ","

list

TextInfo.ListSeparator

Example: ";"

percentSign

PercentSymbol

Example: "%"

infinity type="positive"

PositiveInfinitySymbol,

Example: "Infinity"

infinity type="negative"

NegativeInfinitySymbol

Example: "-Infinity"

nan

NaNSymbol

"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

CurrencyDecimalSeparator

Example: "."

msLocale:currencyGroupSeparator

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

ISOCurrencySymbol

Example: "$"

displayName

CurrencyNativeName

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

ISOCurrencySymbol

Example: "USD"

msLocale:currencyEnglishName

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

NumberDecimalDigits

Number of decimal places to use in numeric values, specified as CDATA; example: "2"

msLocale:negativePattern

NumberNegativePattern

Format pattern for negative numeric values

msLocale:currencyDecimalDigits

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

CurrencyPositivePattern

Format pattern for positive currency values

msLocale:currencyNagativePattern

CurrencyNegativePattern

Format pattern for negative currency values

msLocale:percentPositivePattern

PercentPositivePattern

Format pattern for positive percent values

msLocale:percentNagativePattern

PercentNegativePattern

Format pattern for negative percent values

msLocale:groupSizes

NumberGroupSizes

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

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

DigitSubstitution

A value that specifies how the graphical user interface displays the shape of a digit; valid settings for the type attribute are:

  • "context" (the default)

  • "none" (always use "0"-"9")

  • "nativeNational" (always substitute)

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>

See Also

Reference

CultureAndRegionInfoBuilder