1## Unicode Technical Standard #35 2 3# Unicode Locale Data Markup Language (LDML)<br/>Part 4: Dates 4 5|Version|45 | 6|-------|------------------| 7|Editors|Peter Edberg and <a href="tr35.md#Acknowledgments">other CLDR committee members</a>| 8 9For the full header, summary, and status, see [Part 1: Core](tr35.md). 10 11### _Summary_ 12 13This document describes parts of an XML format (_vocabulary_) for the exchange of structured locale data. This format is used in the [Unicode Common Locale Data Repository](https://www.unicode.org/cldr/). 14 15This is a partial document, describing only those parts of the LDML that are relevant for date, time, and time zone formatting. For the other parts of the LDML see the [main LDML document](tr35.md) and the links above. 16 17### _Status_ 18 19<!-- _This is a draft document which may be updated, replaced, or superseded by other documents at any time. 20Publication does not imply endorsement by the Unicode Consortium. 21This is not a stable document; it is inappropriate to cite this document as other than a work in progress._ --> 22 23_This document has been reviewed by Unicode members and other interested parties, and has been approved for publication by the Unicode Consortium. 24This is a stable document and may be used as reference material or cited as a normative reference by other specifications._ 25 26> _**A Unicode Technical Standard (UTS)** is an independent specification. Conformance to the Unicode Standard does not imply conformance to any UTS._ 27 28_Please submit corrigenda and other comments with the CLDR bug reporting form [[Bugs](tr35.md#Bugs)]. Related information that is useful in understanding this document is found in the [References](tr35.md#References). For the latest version of the Unicode Standard see [[Unicode](tr35.md#Unicode)]. For a list of current Unicode Technical Reports see [[Reports](tr35.md#Reports)]. For more information about versions of the Unicode Standard, see [[Versions](tr35.md#Versions)]._ 29 30## <a name="Parts" href="#Parts">Parts</a> 31 32The LDML specification is divided into the following parts: 33 34* Part 1: [Core](tr35.md#Contents) (languages, locales, basic structure) 35* Part 2: [General](tr35-general.md#Contents) (display names & transforms, etc.) 36* Part 3: [Numbers](tr35-numbers.md#Contents) (number & currency formatting) 37* Part 4: [Dates](tr35-dates.md#Contents) (date, time, time zone formatting) 38* Part 5: [Collation](tr35-collation.md#Contents) (sorting, searching, grouping) 39* Part 6: [Supplemental](tr35-info.md#Contents) (supplemental data) 40* Part 7: [Keyboards](tr35-keyboards.md#Contents) (keyboard mappings) 41* Part 8: [Person Names](tr35-personNames.md#Contents) (person names) 42* Part 9: [MessageFormat](tr35-messageFormat.md#Contents) (message format) 43 44## <a name="Contents" href="#Contents">Contents of Part 4, Dates</a> 45 46* [Overview: Dates Element, Supplemental Date and Calendar Information](#Overview_Dates_Element_Supplemental) 47* [Calendar Elements](#Calendar_Elements) 48 * [Elements months, days, quarters, eras](#months_days_quarters_eras) 49 * [Elements monthPatterns, cyclicNameSets](#monthPatterns_cyclicNameSets) 50 * [Element dayPeriods](#dayPeriods) 51 * [Element dateFormats](#dateFormats) 52 * [Element timeFormats](#timeFormats) 53 * [Element dateTimeFormats](#dateTimeFormats) 54 * [Element dateTimeFormat](#dateTimeFormat) 55 * Table: [Date-Time Combination Examples](#Date_Time_Combination_Examples) 56 * [Elements availableFormats, appendItems](#availableFormats_appendItems) 57 * Table: [Mapping Requested Time Skeletons To Patterns](#Mapping_Requested_Time_Skeletons_To_Patterns) 58 * [Matching Skeletons](#Matching_Skeletons) 59 * [Missing Skeleton Fields](#Missing_Skeleton_Fields) 60 * [Element intervalFormats](#intervalFormats) 61* [Calendar Fields](#Calendar_Fields) 62* [Supplemental Calendar Data](#Supplemental_Calendar_Data) 63 * [Calendar Data](#Calendar_Data) 64 * [Calendar Preference Data](#Calendar_Preference_Data) 65 * [Week Data](#Week_Data) 66 * Table: [Week Designation Types](#Week_Designation_Types) 67 * [First Day Overrides](#first-day-overrides) 68 * [Time Data](#Time_Data) 69 * [Day Period Rule Sets](#Day_Period_Rule_Sets) 70 * [Day Period Rules](#Day_Period_Rules) 71 * [Fixed periods](#Fixed_periods) 72 * [Variable periods](#Variable_periods) 73 * [Parsing Day Periods](#Parsing_Day_Periods) 74* [Time Zone Names](#Time_Zone_Names) 75 * Table: [timeZoneNames Elements Used for Fallback](#timeZoneNames_Elements_Used_for_Fallback) 76 * [Metazone Names](#Metazone_Names) 77* [Supplemental Time Zone Data](#Supplemental_Time_Zone_Data) 78 * [Metazones](#Metazones) 79 * [Windows Zones](#Windows_Zones) 80 * [Primary Zones](#Primary_Zones) 81* [Using Time Zone Names](#Using_Time_Zone_Names) 82 * [Time Zone Format Terminology](#Time_Zone_Format_Terminology) 83 * [Goals](#Time_Zone_Goals) 84 * [Parsing](#Time_Zone_Parsing) 85* [Date Format Patterns](#Date_Format_Patterns) 86 * Table: [Date Format Pattern Examples](#Date_Format_Pattern_Examples) 87 * Table: [Date Field Symbol Table](#Date_Field_Symbol_Table) 88 * [Localized Pattern Characters (deprecated)](#Localized_Pattern_Characters) 89 * [AM / PM](#Date_Patterns_AM_PM) 90 * [Eras](#Date_Patterns_Eras) 91 * [Week of Year](#Date_Patterns_Week_Of_Year) 92 * [Week Elements](#Date_Patterns_Week_Elements) 93* [Parsing Dates and Times](#Parsing_Dates_Times) 94 95## <a name="Overview_Dates_Element_Supplemental" href="#Overview_Dates_Element_Supplemental">Overview: Dates Element, Supplemental Date and Calendar Information</a> 96 97```xml 98<!ELEMENT dates (alias | (calendars?, fields?, timeZoneNames?, special*)) > 99``` 100 101The LDML top-level `<dates>` element contains information regarding the format and parsing of dates and times, the formatting of date/time intervals, and the naming of various calendar elements. 102 103* The `<calendars>` element is described in [Calendar Elements](#Calendar_Elements). 104* The `<fields>` element is described in [Calendar Fields](#Calendar_Fields). 105* The `<timeZoneNames>` element is described in [Time Zone Names](#Time_Zone_Names). 106* The formats use pattern characters described in [Date Format Patterns](#Date_Format_Patterns). 107 108```xml 109<!ELEMENT supplementalData ( …, calendarData?, calendarPreferenceData?, weekData?, timeData?, …, timezoneData?, …, metazoneInfo?, …, dayPeriodRuleSet*, metaZones?, primaryZones?, windowsZones?, …) > 110``` 111 112The relevant top-level supplemental elements are listed above. 113 114* The `<calendarData>`, `<calendarPreferenceData>`, `<weekData>`, `<timeData>`, and `<dayPeriodRuleSet>` elements are described in [Supplemental Calendar Data](#Supplemental_Calendar_Data). 115* The `<timezoneData>` element is deprecated and no longer used; the `<metazoneInfo>` element is deprecated at this level, and is now only used as a sub-element of `<metaZones>`. 116* The `<metaZones>`, `<primaryZones>`, and `<windowsZones>` elements are described in [Supplemental Time Zone Data](#Supplemental_Time_Zone_Data). 117 118## <a name="Calendar_Elements" href="#Calendar_Elements">Calendar Elements</a> 119 120```xml 121<!ELEMENT calendars (alias | (calendar*, special*)) > 122<!ELEMENT calendar (alias | (months?, monthPatterns?, days?, quarters?, dayPeriods?, eras?, cyclicNameSets?, dateFormats?, timeFormats?, dateTimeFormats?, special*))> 123<!ATTLIST calendar type NMTOKEN #REQUIRED > 124``` 125 126The `<calendars>` element contains multiple `<calendar>` elements, each of which specifies the fields used for formatting and parsing dates and times according to the calendar specified by the `type` attribute (e.g. "gregorian", "buddhist", "islamic"). The behaviors for different calendars in a locale may share certain aspects, such as the names for weekdays. They differ in other respects; for example, the Japanese calendar is similar to the Gregorian calendar but has many more eras (one for each Emperor), and years are numbered within each era. All calendar data inherits either from the Gregorian calendar or other calendars in the same locale (and if not present there then from the parent up to root), or else inherits directly from the parent locale for certain calendars, so only data that differs from what would be inherited needs to be supplied. See _[Multiple Inheritance](tr35.md#Multiple_Inheritance)_. 127 128Each calendar provides—directly or indirectly—two general types of data: 129 130* _Calendar symbols, such as names for eras, months, weekdays, and dayPeriods._ Names for weekdays, quarters and dayPeriods are typically inherited from the Gregorian calendar data in the same locale. Symbols for eras and months should be provided for each calendar, except that the "Gregorian-like" Buddhist, Japanese, and Minguo (ROC) calendars also inherit their month names from the Gregorian data in the same locale. 131* _Format data for dates, times, and date-time intervals._ Non-Gregorian calendars inherit standard time formats (in the `<timeFormats>` element) from the Gregorian calendar in the same locale. Most non-Gregorian calendars (other than Chinese and Dangi) inherit general date format data (in the `<dateFormats>` and `<dateTimeFormats>` elements) from the "generic" calendar format data in the same locale, which in turn inherits from Gregorian. 132 133Calendars that use cyclicNameSets and monthPatterns (such as Chinese and Dangi) have additional symbols and distinct formats, and typically inherit these items (along with month names) from their parent locales, instead of inheriting them from Gregorian or generic data in the same locale. 134 135The primary difference between Gregorian and "generic" format data is that date formats in "generic" usually include era with year, in order to provide an indication of which calendar is being used (Gregorian calendar formats may also commonly include era with year when Gregorian is not the default calendar for the locale). Otherwise, the "generic" date formats should normally be consistent with those in the Gregorian calendar. The "generic" calendar formats are intended to provide a consistent set of default formats for non-Gregorian calendars in the locale, so that in most cases the only data items that need be provided for non-Gregorian calendars are the era names and month names (and the latter only for calendars other than Buddhist, Japanese, and Minguo, since those inherit month names from Gregorian). 136 137### <a name="months_days_quarters_eras" href="#months_days_quarters_eras">Elements months, days, quarters, eras</a> 138 139```xml 140<!ELEMENT months ( alias | (monthContext*, special*)) > 141<!ELEMENT monthContext ( alias | (default*, monthWidth*, special*)) > 142<!ATTLIST monthContext type ( format | stand-alone ) #REQUIRED > 143<!ELEMENT monthWidth ( alias | (month*, special*)) > 144<!ATTLIST monthWidth type ( abbreviated| narrow | wide) #REQUIRED > 145<!ELEMENT month ( #PCDATA )* > 146<!ATTLIST month type ( 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 ) #REQUIRED > 147<!ATTLIST month yeartype ( standard | leap ) #IMPLIED > 148 149<!ELEMENT days ( alias | (dayContext*, special*)) > 150<!ELEMENT dayContext ( alias | (default*, dayWidth*, special*)) > 151<!ATTLIST dayContext type ( format | stand-alone ) #REQUIRED > 152<!ELEMENT dayWidth ( alias | (day*, special*)) > 153<!ATTLIST dayWidth type NMTOKEN #REQUIRED > 154<!ELEMENT day ( #PCDATA ) > 155<!ATTLIST day type ( sun | mon | tue | wed | thu | fri | sat ) #REQUIRED > 156 157<!ELEMENT quarters ( alias | (quarterContext*, special*)) > 158<!ELEMENT quarterContext ( alias | (default*, quarterWidth*, special*)) > 159<!ATTLIST quarterContext type ( format | stand-alone ) #REQUIRED > 160<!ELEMENT quarterWidth ( alias | (quarter*, special*)) > 161<!ATTLIST quarterWidth type NMTOKEN #REQUIRED > 162<!ELEMENT quarter ( #PCDATA ) > 163<!ATTLIST quarter type ( 1 | 2 | 3 | 4 ) #REQUIRED > 164 165<!ELEMENT eras (alias | (eraNames?, eraAbbr?, eraNarrow?, special*)) > 166<!ELEMENT eraNames ( alias | (era*, special*) ) > 167<!ELEMENT eraAbbr ( alias | (era*, special*) ) > 168<!ELEMENT eraNarrow ( alias | (era*, special*) ) > 169``` 170 171The month and quarter names are identified numerically, starting at 1. The weekday names are identified with short strings, since there is no universally-accepted numeric designation. 172 173Month, day, and quarter names may vary along two axes: the width and the context. 174 175The context is either _format_ (the default), the form used within a complete date format string (such as "Saturday, November 12"), or _stand-alone_, the form for date elements used independently, such as in calendar headers. The _stand-alone_ form may be used in any other date format that shares the same form of the name. For month names, this is typically the nominative grammatical form, and might also be used in patterns such as "LLLL y" (month name + year). The _format_ form is an additional form that can be used in contexts where it is different than the stand-alone form. For example, in many languages, patterns that combine month name with day-of-month (and possibly other elements) may require the month name to be in a grammatical form such as genitive or partitive. 176* In past versions of CLDR, the distinction between format and stand-alone forms was used to control capitalization (with stand-alone forms using titlecase); however, this can be controlled separately and more precisely using the `<contextTransforms>` element as described in _[ContextTransform Elements](tr35-general.md#Context_Transform_Elements)_, so both format and stand-alone forms should generally use middle-of-sentence capitalization. 177* However, if in a given language, certain context/width combinations are always used in a titlecase form — for example, stand-alone narrow forms for months or weekdays — then these should be provided in that form. 178* The distinctions between stand-alone (e.g. LLLL) and format (e.g. MMMM) forms are only relevant for how date elements are used within a date format. They are not intended to reflect how a date format is used within a sentence. For example, they are not intended to be used to generate the dative form of a date format when that format is used after a preposition that takes dative form. 179 180The width can be _wide_ (the default), _abbreviated_, or _narrow_; for days only, the width can also be _short,_ which is ideally between the abbreviated and narrow widths, but must be no longer than abbreviated and no shorter than narrow (if short day names are not explicitly specified, abbreviated day names are used instead). Note that for `<monthPattern>`, described in the next section: 181 182* There is an additional context type _numeric_ 183* When the context type is numeric, the width has a special type _all_ 184 185The format values must be distinct for the wide, abbreviated, and short widths. However, values for the narrow width in either format or stand-alone contexts, as well as values for other widths in stand-alone contexts, need not be distinct; they might only be distinguished by context. For example, "S" may be used both for Saturday and for Sunday. The narrow width is typically used in calendar headers; it must be the shortest possible width, no more than one character (or grapheme cluster, or exemplar set element) in stand-alone values (not including punctuation), and the shortest possible widths (in terms of grapheme clusters) in format values. The short width (if present) is often the shortest unambiguous form. 186 187Era names should be distinct within each of the widths, including narrow; there is less disambiguating information for them, and they are more likely to be used in a format that requires parsing. 188 189Due to aliases in root, the forms inherit "sideways". (See _[Multiple Inheritance](tr35.md#Multiple_Inheritance)_.) For example, if the abbreviated format data for Gregorian does not exist in a language X (in the chain up to root), then it inherits from the wide format data in that same language X. 190 191```xml 192<monthContext type="format"> 193 <monthWidth type="abbreviated"> 194 <alias source="locale" path="../monthWidth[@type='wide']"/> 195 </monthWidth> 196 <monthWidth type="narrow"> 197 <alias source="locale" path="../../monthContext[@type='stand-alone']/monthWidth[@type='narrow']"/> 198 </monthWidth> 199 <monthWidth type="wide"> 200 <month type="1">1</month> 201 ... 202 <month type="12">12</month> 203 </monthWidth> 204</monthContext> 205<monthContext type="stand-alone"> 206 <monthWidth type="abbreviated"> 207 <alias source="locale" path="../../monthContext[@type='format']/monthWidth[@type='abbreviated']"/> 208 </monthWidth> 209 <monthWidth type="narrow"> 210 <month type="1">1</month> 211 ... 212 <month type="12">12</month> 213 </monthWidth> 214 <monthWidth type="wide"> 215 <alias source="locale" path="../../monthContext[@type='format']/monthWidth[@type='wide']"/> 216 </monthWidth> 217</monthContext> 218``` 219 220The `yeartype` attribute for months is used to distinguish alternate month names that would be displayed for certain calendars during leap years. The practical example of this usage occurs in the Hebrew calendar, where the 7th month "Adar" occurs in non-leap years, with the 6th month being skipped, but in leap years there are two months named "Adar I" and "Adar II". There are currently only two defined year types, standard (the implied default) and leap. 221 222For `era` elements, an additional `alt="variant"` form may be supplied. This is primarily intended for use in the "gregorian" calendar, with which two parallel sets of era designations are used in some locales: one set with a religious reference (e.g. English BC/AD), and one set without (e.g. English BCE/CE). The most commonly-used set for the locale should be provided as the default, and the other set may be provided as the `alt="variant"` forms. See the example below. 223 224Example: 225 226```xml 227<calendar type="gregorian"> 228 <months> 229 <monthContext type="format"> 230 <monthWidth type="wide"> 231 <month type="1">January</month> 232 <month type="2">February</month> 233 ... 234 <month type="11">November</month> 235 <month type="12">December</month> 236 </monthWidth> 237 <monthWidth type="abbreviated"> 238 <month type="1">Jan</month> 239 <month type="2">Feb</month> 240 ... 241 <month type="11">Nov</month> 242 <month type="12">Dec</month> 243 </monthWidth> 244 </monthContext> 245 <monthContext type="stand-alone"> 246 <default type="wide"/> 247 <monthWidth type="wide"> 248 <month type="1">Januaria</month> 249 <month type="2">Februaria</month> 250 ... 251 <month type="11">Novembria</month> 252 <month type="12">Decembria</month> 253 </monthWidth> 254 <monthWidth type="narrow"> 255 <month type="1">J</month> 256 <month type="2">F</month> 257 ... 258 <month type="11">N</month> 259 <month type="12">D</month> 260 </monthWidth> 261 </monthContext> 262 </months> 263 264 <days> 265 <dayContext type="format"> 266 <dayWidth type="wide"> 267 <day type="sun">Sunday</day> 268 <day type="mon">Monday</day> 269 ... 270 <day type="fri">Friday</day> 271 <day type="sat">Saturday</day> 272 </dayWidth> 273 <dayWidth type="abbreviated"> 274 <day type="sun">Sun</day> 275 <day type="mon">Mon</day> 276 ... 277 <day type="fri">Fri</day> 278 <day type="sat">Sat</day> 279 </dayWidth> 280 <dayWidth type="narrow"> 281 <day type="sun">Su</day> 282 <day type="mon">M</day> 283 ... 284 <day type="fri">F</day> 285 <day type="sat">Sa</day> 286 </dayWidth> 287 </dayContext> 288 <dayContext type="stand-alone"> 289 <dayWidth type="narrow"> 290 <day type="sun">S</day> 291 <day type="mon">M</day> 292 ... 293 <day type="fri">F</day> 294 <day type="sat">S</day> 295 </dayWidth> 296 </dayContext> 297 </days> 298 299 <quarters> 300 <quarterContext type="format"> 301 <quarterWidth type="abbreviated"> 302 <quarter type="1">Q1</quarter> 303 <quarter type="2">Q2</quarter> 304 <quarter type="3">Q3</quarter> 305 <quarter type="4">Q4</quarter> 306 </quarterWidth> 307 <quarterWidth type="wide"> 308 <quarter type="1">1st quarter</quarter> 309 <quarter type="2">2nd quarter</quarter> 310 <quarter type="3">3rd quarter</quarter> 311 <quarter type="4">4th quarter</quarter> 312 </quarterWidth> 313 </quarterContext> 314 </quarters> 315 316 <eras> 317 <eraAbbr> 318 <era type="0">BC</era> 319 <era type="0" alt="variant">BCE</era> 320 <era type="1">AD</era> 321 <era type="1" alt="variant">CE</era> 322 </eraAbbr> 323 <eraNames> 324 <era type="0">Before Christ</era> 325 <era type="0" alt="variant">Before Common Era</era> 326 <era type="1">Anno Domini</era> 327 <era type="1" alt="variant">Common Era</era> 328 </eraNames> 329 <eraNarrow> 330 <era type="0">B</era> 331 <era type="1">A</era> 332 </eraNarrow> 333 </eras> 334``` 335 336### <a name="monthPatterns_cyclicNameSets" href="#monthPatterns_cyclicNameSets">Elements monthPatterns, cyclicNameSets</a> 337 338```xml 339<!ELEMENT monthPatterns ( alias | (monthPatternContext*, special*)) > 340<!ELEMENT monthPatternContext ( alias | (monthPatternWidth*, special*)) > 341<!ATTLIST monthPatternContext type ( format | stand-alone | numeric ) #REQUIRED > 342<!ELEMENT monthPatternWidth ( alias | (monthPattern*, special*)) > 343<!ATTLIST monthPatternWidth type ( abbreviated| narrow | wide | all ) #REQUIRED > 344<!ELEMENT monthPattern ( #PCDATA ) > 345<!ATTLIST monthPattern type ( leap | standardAfterLeap | combined ) #REQUIRED > 346 347<!ELEMENT cyclicNameSets ( alias | (cyclicNameSet*, special*)) > 348<!ELEMENT cyclicNameSet ( alias | (cyclicNameContext*, special*)) > 349<!ATTLIST cyclicNameSet type ( years | months | days | dayParts | zodiacs | solarTerms ) #REQUIRED > 350<!ELEMENT cyclicNameContext ( alias | (cyclicNameWidth*, special*)) > 351<!ATTLIST cyclicNameContext type ( format | stand-alone ) #REQUIRED > 352<!ELEMENT cyclicNameWidth ( alias | (cyclicName*, special*)) > 353<!ATTLIST cyclicNameWidth type ( abbreviated | narrow | wide ) #REQUIRED > 354<!ELEMENT cyclicName ( #PCDATA ) > 355<!ATTLIST cyclicName type NMTOKEN #REQUIRED > 356``` 357 358The Chinese lunar calendar can insert a leap month after nearly any month of its year; when this happens, the month takes the name of the preceding month plus a special marker. The Hindu lunar calendars can insert a leap month before any one or two months of the year; when this happens, not only does the leap month take the name of the following month plus a special marker, the following month also takes a special marker. Moreover, in the Hindu calendar sometimes a month is skipped, in which case the preceding month takes a special marker plus the names of both months. The `<monthPatterns>` element structure supports these special kinds of month names. It parallels the `<months>` element structure, with various contexts and widths, but with some differences: 359 360* Since the month markers may be applied to numeric months as well, there is an additional `monthPatternContext` type `numeric` for this case. When the numeric context is used, there is no need for different widths, so the `monthPatternWidth` type is `all` for this case. 361* The `<monthPattern>` element itself is a pattern showing how to create the modified month name from the standard month name(s). The three types of possible pattern are for `leap`, `standardAfterLeap`, and `combined`. 362* The `<monthPatterns>` element is not present for calendars that do not need it. 363 364The Chinese and Hindu lunar calendars also use a 60-name cycle for designating years. The Chinese lunar calendars can also use that cycle for months and days, and can use 12-name cycles for designating day subdivisions or zodiac names associated with years; a 24-name cycle of solar terms (12 pairs of minor and major terms) is used to mark intervals in the solar cycle. The `<cyclicNameSets>` element structure supports these special kinds of name cycles; a `cyclicNameSet` can be provided for types `year`, `month`, `day`, `dayParts`, or `zodiacs`. For each `cyclicNameSet`, there is a context and width structure similar to that for day names. For a given context and width, a set of `cyclicName` elements provides the actual names. 365 366Example: 367 368```xml 369 <monthPatterns> 370 <monthPatternContext type="format"> 371 <monthPatternWidth type="wide"> 372 <monthPattern type="leap">闰{0}</monthPattern> 373 </monthPatternWidth> 374 </monthPatternContext> 375 <monthPatternContext type="stand-alone"> 376 <monthPatternWidth type="narrow"> 377 <monthPattern type="leap">闰{0}</monthPattern> 378 </monthPatternWidth> 379 </monthPatternContext> 380 <monthPatternContext type="numeric"> 381 <monthPatternWidth type="all"> 382 <monthPattern type="leap">闰{0}</monthPattern> 383 </monthPatternWidth> 384 </monthPatternContext> 385 </monthPatterns> 386 <cyclicNameSets> 387 <cyclicNameSet type="years"> 388 <cyclicNameContext type="format"> 389 <cyclicNameWidth type="abbreviated"> 390 <cyclicName type="1">甲子</cyclicName> 391 <cyclicName type="2">乙丑</cyclicName> 392 ... 393 <cyclicName type="59">壬戌</cyclicName> 394 <cyclicName type="60">癸亥</cyclicName> 395 </cyclicNameWidth> 396 </cyclicNameContext> 397 </cyclicNameSet> 398 <cyclicNameSet type="zodiacs"> 399 <cyclicNameContext type="format"> 400 <cyclicNameWidth type="abbreviated"> 401 <cyclicName type="1">鼠</cyclicName> 402 <cyclicName type="2">牛</cyclicName> 403 ... 404 <cyclicName type="11">狗</cyclicName> 405 <cyclicName type="12">猪</cyclicName> 406 </cyclicNameWidth> 407 </cyclicNameContext> 408 </cyclicNameSet> 409 <cyclicNameSet type="solarTerms"> 410 <cyclicNameContext type="format"> 411 <cyclicNameWidth type="abbreviated"> 412 <cyclicName type="1">立春</cyclicName> 413 <cyclicName type="2">雨水</cyclicName> 414 ... 415 <cyclicName type="23">小寒</cyclicName> 416 <cyclicName type="24">大寒</cyclicName> 417 </cyclicNameWidth> 418 </cyclicNameContext> 419 </cyclicNameSet> 420 </cyclicNameSets> 421``` 422 423### <a name="dayPeriods" href="#dayPeriods">Element dayPeriods</a> 424 425The former `am`/`pm` elements have been deprecated, and replaced by the more flexible `dayPeriods`. 426 427```xml 428<!ELEMENT dayPeriods ( alias | (dayPeriodContext*) ) > 429 430<!ELEMENT dayPeriodContext (alias | dayPeriodWidth*) > 431<!ATTLIST dayPeriodContext type NMTOKEN #REQUIRED > 432 433<!ELEMENT dayPeriodWidth (alias | dayPeriod*) > 434<!ATTLIST dayPeriodWidth type NMTOKEN #REQUIRED > 435 436<!ELEMENT dayPeriod ( #PCDATA ) > 437<!ATTLIST dayPeriod type NMTOKEN #REQUIRED > 438``` 439 440These behave like months, days, and so on in terms of having context and width. Each locale has an associated dayPeriodRuleSet in the supplemental data, rules that specify when the day periods start and end for that locale. Each type in the rules needs to have a translation in a dayPeriod (but if translation data is missing for a particular variable dayPeriod in the locale’s language and script, formatting should fall back to using the am/pm values). For more information, see _[Day Period Rules](#Day_Period_Rules)_. 441 442The dayPeriod names should be distinct within each of the context/width combinations, including narrow; as with era names, there is less disambiguating information for them, and they are more likely to be used in a format that requires parsing. In some unambiguous cases, it is acceptable for certain overlapping dayPeriods to be the same, such as the names for "am" and "morning", or the names for "pm" and "afternoon". 443 444Example: 445 446```xml 447 <dayPeriods> 448 <dayPeriodContext type="format"> 449 <dayPeriodWidth type="wide"> 450 <dayPeriod type="am">AM</dayPeriod> 451 <dayPeriod type="noon">noon</dayPeriod> 452 <dayPeriod type="pm">PM</dayPeriod> 453 </dayPeriodWidth> 454 </dayPeriodContext> 455 </dayPeriods> 456``` 457 458### <a name="dateFormats" href="#dateFormats">Element dateFormats</a> 459 460```xml 461<!ELEMENT dateFormats (alias | (default*, dateFormatLength*, special*)) > 462<!ELEMENT dateFormatLength (alias | (default*, dateFormat*, special*)) > 463<!ATTLIST dateFormatLength type ( full | long | medium | short ) #REQUIRED > 464<!ELEMENT dateFormat (alias | (pattern*, datetimeSkeleton*, displayName*, special*)) > 465<!ELEMENT pattern ( #PCDATA ) > 466<!ATTLIST pattern numbers CDATA #IMPLIED > 467<!ATTLIST pattern alt NMTOKENS #IMPLIED > 468<!ATTLIST pattern draft (approved | contributed | provisional | unconfirmed) #IMPLIED > 469<!ELEMENT datetimeSkeleton ( #PCDATA ) > 470<!ATTLIST datetimeSkeleton numbers CDATA #IMPLIED > 471<!ATTLIST datetimeSkeleton alt NMTOKENS #IMPLIED > 472<!ATTLIST datetimeSkeleton draft (approved | contributed | provisional | unconfirmed) #IMPLIED > 473``` 474 475Standard date formats have the following form: 476 477```xml 478 <dateFormats> 479 <dateFormatLength type="full"> 480 <dateFormat> 481 <pattern>EEEE, MMMM d, y</pattern> 482 <datetimeSkeleton>yMMMMEEEEd</datetimeSkeleton> 483 </dateFormat> 484 </dateFormatLength> 485 ... 486 <dateFormatLength type="medium"> 487 <dateFormat> 488 <pattern>MMM d, y</pattern> 489 <datetimeSkeleton>yMMMd</datetimeSkeleton> 490 </dateFormat> 491 </dateFormatLength> 492 ... 493 <dateFormats> 494 495 <dateFormats> 496 ... 497 <dateFormatLength type="medium"> 498 <dateFormat> 499 <pattern numbers="hebr">d בMMMM y</pattern> 500 <datetimeSkeleton numbers="hebr">yMMMMd</datetimeSkeleton> 501 </dateFormat> 502 </dateFormatLength> 503 ... 504 <dateFormats> 505 506 <dateFormats> 507 ... 508 <dateFormatLength type="long"> 509 <dateFormat> 510 <pattern numbers="d=hanidays">rU年MMMMd</pattern> 511 <datetimeSkeleton numbers="d=hanidays">rMMMMd</datetimeSkeleton> 512 </dateFormat> 513 </dateFormatLength> 514 ... 515``` 516 517The patterns for date formats and time formats are defined in _[Date Format Patterns](#Date_Format_Patterns)._ These patterns are intended primarily for display of isolated date and time strings in user-interface elements, rather than for date and time strings in the middle of running text, so capitalization and grammatical form should be chosen appropriately. 518 519Standard date and time patterns are each normally provided in four types: full (usually with weekday name), long (with wide month name), medium, and short (usually with numeric month). 520 521The `numbers` attribute can be used to explicitly specify a number system to be used for all of the numeric fields in the date format (as in `numbers="hebr"`), or for a specific field in the date format (as in `numbers="d=hanidays"`). This attribute overrides any default numbering system specified for the locale. 522 523The `datetimeSkeleton` element contains a _skeleton_ (see [availableFormats](#availableFormats_appendItems)) derived from the pattern. In the future the intent is to be able to generate the standard patterns from these `datetimeSkeleton` elements. However, in CLDR 40, the mechanisms associated with the `availableFormats` elements are not quite powerful enough to generate patterns that exactly match all of the ones provided in the `pattern` elements. 524 525### <a name="timeFormats" href="#timeFormats">Element timeFormats</a> 526 527```xml 528<!ELEMENT timeFormats (alias | (default*, timeFormatLength*, special*)) > 529<!ELEMENT timeFormatLength (alias | (default*, timeFormat*, special*)) > 530<!ATTLIST timeFormatLength type ( full | long | medium | short ) #REQUIRED > 531<!ELEMENT timeFormat (alias | (pattern*, datetimeSkeleton*, displayName*, special*)) > 532``` 533Standard time formats have the following form: 534 535```xml 536 <timeFormats> 537 <timeFormatLength type="full"> 538 <timeFormat> 539 <displayName>DIN 5008 (EN 28601)</displayName> 540 <pattern>h:mm:ss a z</pattern> 541 <datetimeSkeleton>ahmmssz</datetimeSkeleton> 542 </timeFormat> 543 </timeFormatLength> 544 <timeFormatLength type="medium"> 545 <timeFormat> 546 <pattern>h:mm:ss a</pattern> 547 <datetimeSkeleton>ahmmss</datetimeSkeleton> 548 </timeFormat> 549 </timeFormatLength> 550 </timeFormats> 551``` 552 553The preference of 12 hour versus 24 hour for the locale can be derived from the [Time Data](#Time_Data). If the preferred hour symbol is 'h' or 'K' then the format is 12 hour; otherwise it is 24 hour. Formats with 'h' or 'K' must also include a field with one of the day period pattern characters: 'a', 'b', or 'B'. 554 555To account for customary usage in some countries, APIs should allow for formatting times that go beyond 23:59:59. For example, in some countries it would be customary to indicate that opening hours extending from _Friday at 7pm_ to _Saturday at 2am_ in a format like the following: 556 557Friday: 19:00 – 26:00 558 559Time formats use the specific non-location format (z or zzzz) for the time zone name. This is the format that should be used when formatting a specific time for presentation. When formatting a time referring to a recurring time (such as a meeting in a calendar), applications should substitute the generic non-location format (v or vvvv) for the time zone in the time format pattern. See _[Using Time Zone Names](#Using_Time_Zone_Names)_ for a complete description of available time zone formats and their uses. 560 561### <a name="dateTimeFormats" href="#dateTimeFormats">Element dateTimeFormats</a> 562 563```xml 564<!ELEMENT dateTimeFormats (alias | (default*, dateTimeFormatLength*, availableFormats*, appendItems*, intervalFormats*, special*)) > 565``` 566 567Date/Time formats have the following form: 568```xml 569 <dateTimeFormats> 570 <dateTimeFormatLength type="full"> 571 <dateTimeFormat> 572 <pattern>{1}, {0}</pattern> 573 </dateTimeFormat> 574 <dateTimeFormat type="atTime"> 575 <pattern>{1} 'at' {0}</pattern> 576 </dateTimeFormat> 577 </dateTimeFormatLength> 578 <dateTimeFormatLength type="long"> 579 <dateTimeFormat> 580 <pattern>{1}, {0}</pattern> 581 </dateTimeFormat> 582 <dateTimeFormat type="atTime"> 583 <pattern>{1} 'at' {0}</pattern> 584 </dateTimeFormat> 585 </dateTimeFormatLength> 586 <dateTimeFormatLength type="medium"> 587 <dateTimeFormat> 588 <pattern>{1}, {0}</pattern> 589 </dateTimeFormat> 590 </dateTimeFormatLength> 591 <dateTimeFormatLength type="short"> 592 <dateTimeFormat> 593 <pattern>{1}, {0}</pattern> 594 </dateTimeFormat> 595 </dateTimeFormatLength> 596 <availableFormats> 597 <dateFormatItem id="Hm">HH:mm</dateFormatItem> 598 <dateFormatItem id="Hms">HH:mm:ss</dateFormatItem> 599 <dateFormatItem id="M">L</dateFormatItem> 600 <dateFormatItem id="MEd">E, M/d</dateFormatItem> 601 <dateFormatItem id="MMM">LLL</dateFormatItem> 602 <dateFormatItem id="MMMEd">E, MMM d</dateFormatItem> 603 <dateFormatItem id="MMMMEd">E, MMMM d</dateFormatItem> 604 <dateFormatItem id="MMMMd">MMMM d</dateFormatItem> 605 <dateFormatItem id="MMMd">MMM d</dateFormatItem> 606 <dateFormatItem id="Md">M/d</dateFormatItem> 607 <dateFormatItem id="d">d</dateFormatItem> 608 <dateFormatItem id="hm">h:mm a</dateFormatItem> 609 <dateFormatItem id="ms">mm:ss</dateFormatItem> 610 <dateFormatItem id="y">yyyy</dateFormatItem> 611 <dateFormatItem id="yM">M/yyyy</dateFormatItem> 612 <dateFormatItem id="yMEd">EEE, M/d/yyyy</dateFormatItem> 613 <dateFormatItem id="yMMM">MMM yyyy</dateFormatItem> 614 <dateFormatItem id="yMMMEd">EEE, MMM d, yyyy</dateFormatItem> 615 <dateFormatItem id="yMMMM">MMMM yyyy</dateFormatItem> 616 <dateFormatItem id="yQ">Q yyyy</dateFormatItem> 617 <dateFormatItem id="yQQQ">QQQ yyyy</dateFormatItem> 618 . . . 619 </availableFormats> 620 <appendItems> 621 <appendItem request="Day">{0} ({2}: {1})</appendItem> 622 <appendItem request="Day-Of-Week">{0} {1}</appendItem> 623 <appendItem request="Era">{0} {1}</appendItem> 624 <appendItem request="Hour">{0} ({2}: {1})</appendItem> 625 . . . 626 </appendItems> 627 </dateTimeFormats> 628 629</calendar> 630 631<calendar type="buddhist"> 632 <eras> 633 <eraAbbr> 634 <era type="0">BE</era> 635 </eraAbbr> 636 </eras> 637</calendar> 638``` 639 640These formats allow for date and time formats to be composed in various ways. 641 642#### <a name="dateTimeFormat" href="#dateTimeFormat">Element dateTimeFormat</a> 643 644```xml 645<!ELEMENT dateTimeFormatLength (alias | (default*, dateTimeFormat*, special*))> 646<!ATTLIST dateTimeFormatLength type ( full | long | medium | short ) #IMPLIED > 647<!ELEMENT dateTimeFormat (alias | (pattern*, displayName*, special*))> 648<!ATTLIST dateTimeFormat type NMTOKEN "standard" > 649 <!--@MATCH:literal/standard, atTime--> 650``` 651 652The `dateTimeFormat` element works like the dateFormats and timeFormats, except that the pattern is of the form "{1} {0}", where {0} is replaced by the time format, and {1} is replaced by the date format, with results such as "8/27/06 7:31 AM". Except for the substitution markers {0} and {1}, text in the dateTimeFormat is interpreted as part of a date/time pattern, and is subject to the same rules described in [Date Format Patterns](#Date_Format_Patterns). This includes the need to enclose ASCII letters in single quotes if they are intended to represent literal text. 653 654When combining a standard date pattern with a standard time pattern, start with the `dateTimeFormatLength` whose `type` matches the type of the *date* pattern, and then use one of the `dateTimeFormat`s for that `dateTimeFormatLength` (as described after the following table). For example: 655 656###### Table: <a name="Date_Time_Combination_Examples" href="#Date_Time_Combination_Examples">Date-Time Combination Examples</a> 657 658| Date-Time Combination | dateTimeFormat | Results | 659| ----------------------- | ------------------------- | ------- | 660| full date + short time | full, e.g. "{1} 'at' {0}" | Wednesday, September 18, 2013 at 4:30 PM | 661| medium date + long time | medium, e.g. "{1}, {0}" | Sep 18, 2013, 4:30:00 PM PDT | 662 663For each `dateTimeFormatLength`, there is a standard `dateTimeFormat`. In addition to the placeholders {0} and {1}, this should not have characters other than space and punctuation; it should impose no grammatical context that might require specific grammatical forms for the date and/or time. For English, this might be “{1}, {0}”. 664 665In addition, especially for the full and long `dateTimeFormatLength`s, there may be a `dateTimeFormat` with `type="atTime"`. This is used to indicate an event at a specific time, and may impose specific grammatical requirements on the formats for date and/or time. For English, this might be “{1} 'at' {0}”. 666 667The default guidelines for choosing which `dateTimeFormat` to use for a given `dateTimeFormatLength` are as follows: 668* If an interval is being formatted, use the standard combining pattern to produce e.g. “March 15, 3:00 – 5:00 PM” or “March 15, 9:00 AM – March 16, 5:00 PM”. 669* If a single date or relative date is being combined with a single time, by default use the atTime pattern (if available) to produce an event time: “March 15 at 3:00 PM” or “tomorrow at 3:00 PM”. However, at least in the case of combining a single date and time, APIs should also offer a “current time” option of using the standard combining pattern to produce a format more suitable for indicating the current time: “March 15, 3:00 PM”. 670* For all other uses of these patterns, use the standard pattern. 671 672#### <a name="availableFormats_appendItems" href="#availableFormats_appendItems">Elements availableFormats, appendItems</a> 673 674```xml 675<!ELEMENT availableFormats (alias | (dateFormatItem*, special*))> 676<!ELEMENT dateFormatItem ( #PCDATA ) > 677<!ATTLIST dateFormatItem id CDATA #REQUIRED > 678``` 679 680The `availableFormats` element and its subelements provide a more flexible formatting mechanism than the predefined list of patterns represented by dateFormatLength, timeFormatLength, and dateTimeFormatLength. Instead, there is an open-ended list of patterns (represented by `dateFormatItem` elements as well as the predefined patterns mentioned above) that can be matched against a requested set of calendar fields and field lengths. Software can look through the list and find the pattern that best matches the original request, based on the desired calendar fields and lengths. For example, the full month and year may be needed for a calendar application; the request is MMMMyyyy, but the best match may be "y MMMM" or even "G yy MMMM", depending on the locale and calendar. 681 682For some calendars, such as Japanese, a displayed year must have an associated era, so for these calendars dateFormatItem patterns with a year field should also include an era field. When matching availableFormats patterns: If a client requests a format string containing a year, and all the availableFormats patterns with a year also contain an era, then include the era as part of the result. 683 684The `id` attribute is a so-called "skeleton", containing only field information, and in a canonical order. Examples are "yMMMM" for year + full month, or "MMMd" for abbreviated month + day. In particular: 685 686* The fields are from the [Date Field Symbol Table](#Date_Field_Symbol_Table) in _[Date Format Patterns](#Date_Format_Patterns)_. 687* The canonical order is from top to bottom in that table; that is, "yM" not "My". 688* Only one field of each type is allowed; that is, "Hh" is not valid. 689 690In order to support user overrides of default locale behavior, data should be supplied for both 12-hour-cycle time formats (using h or K) and 24-hour-cycle time formats (using H or k), even if one of those styles is not commonly used; the locale's actual preference for 12-hour or 24-hour time cycle is determined from the [Time Data](#Time_Data) as described above in [timeFormats](#timeFormats). Thus skeletons using h or K should have patterns that only use h or K for hours, while skeletons using H or k should have patterns that only use H or k for hours. 691 692The rules governing use of day period pattern characters in patterns and skeletons are as follows: 693 694* Patterns and skeletons for 24-hour-cycle time formats (using H or k) currently _should not_ include fields with day period characters (a, b, or B); these pattern characters should be ignored if they appear in skeletons. However, in the future, CLDR may allow use of B (but not a or b) in 24-hour-cycle time formats. 695* Patterns for 12-hour-cycle time formats (using h or K) _must_ include a day period field using one of a, b, or B. 696* Skeletons for 12-hour-cycle time formats (using h or K) _may_ include a day period field using one of a, b, or B. If they do not, the skeleton will be treated as implicitly containing a. 697 698Locales should generally provide availableFormats data for a fairly complete set of time skeletons without B, typically the following: 699 700`H, h, Hm, hm, Hms, hms, Hmv, hmv, Hmsv, hmsv` 701 702Locales that use 12-hour-cycle time formats with B may provide availableFormats data for a smaller set of time skeletons with B, for example: 703 704`Bh, Bhm, Bhms` 705 706When matching a requested skeleton containing b or B to the skeletons actually available in the data, if there is no skeleton matching the specified day period field, then find a match in which the b or B matches an explicit or implicit 'a' in the skeleton, but replace the 'a' in the corresponding pattern with the requested day period b or B. The following table illustrates how requested skeletons map to patterns with different sets of `availableFormats` data: 707 708###### Table: <a name="Mapping_Requested_Time_Skeletons_To_Patterns" href="#Mapping_Requested_Time_Skeletons_To_Patterns">Mapping Requested Time Skeletons To Patterns</a> 709 710<!-- HTML: spanning columns, header cells on non-first row --> 711<table><tbody> 712<tr><th></th><th colspan="2">results for different availableFormats data sets</th></tr> 713<tr><th>requested skeleton</th> 714 <th>set 1:<br/> 715 ...id="H">H</date...<br/> 716 ...id="h">h a</date...</th> 717 <th>set 2:<br/> 718 ...id="H">H</date...<br/> 719 ...id="h">h a</date...<br/> 720 ...id="Bh">B h</date...</th></tr> 721<tr><td>"h" (or "ah")</td><td>"h a"</td><td>"h a"</td></tr><tr><td>"bh"</td><td>"h b"</td><td>"h b"</td></tr> 722<tr><td>"Bh"</td><td>"h B"</td><td>"B h"</td></tr><tr><td>"H" (or "aH", "bH", "BH")</td><td>"H"</td><td>"H"</td></tr> 723</tbody></table> 724 725The hour input skeleton symbols 'j', 'J', and 'C' can be used to select the best hour format (h, H, …) before processing, and the appropriate dayperiod format (a, b, B) after a successful match that contains an 'a' symbol. 726 727The dateFormatItems inherit from their parent locale, so the inherited items need to be considered when processing. 728 729##### <a name="Matching_Skeletons" href="#Matching_Skeletons">Matching Skeletons</a> 730 731It is not necessary to supply `dateFormatItem`s with skeletons for every field length; fields in the skeleton and pattern are expected to be adjusted in parallel to handle a request. 732 733Typically a “best match” from requested skeleton to the `id` portion of a `dateFormatItem` is found using a closest distance match, such as: 734 7351. Skeleton symbols requesting a best choice for the locale are replaced. 736 * j → one of {H, k, h, K}; C → one of {a, b, B} 737 7382. For skeleton and `id` fields with symbols representing the same type (year, month, day, etc): 739 1. Most symbols have a small distance from each other. 740 * M ≅ L; E ≅ c; a ≅ b ≅ B; H ≅ k ≅ h ≅ K; ... 741 2. Width differences among fields, other than those marking text vs numeric, are given small distance from each other. 742 * MMM ≅ MMMM 743 * MM ≅ M 744 3. Numeric and text fields are given a larger distance from each other. 745 * MMM ≈ MM 746 4. Symbols representing substantial differences (week of year vs week of month) are given a much larger distance from each other. 747 * d ≋ D; ... 748 7493. A requested skeleton that includes both seconds and fractional seconds (e.g. “mmssSSS”) is allowed to match a dateFormatItem skeleton that includes seconds but not fractional seconds (e.g. “ms”). In this case the requested sequence of ‘S’ characters (or its length) should be retained separately and used when adjusting the pattern, as described below. 750 7514. Otherwise, missing or extra fields between requested skeleton and `id` cause a match to fail. (But see **[Missing Skeleton Fields](#Missing_Skeleton_Fields)** below.) 752 753Once a best match is found between requested skeleton and `dateFormatItem` `id`, the corresponding `dateFormatItem` pattern is used, but with adjustments primarily to make the pattern field lengths match the skeleton field lengths. However, the pattern field lengths should not be matched in some cases: 754 7551. When the best-match `dateFormatItem` has an alphabetic field (such as MMM or MMMM) that corresponds to a numeric field in the pattern (such as M or MM), that numeric field in the pattern should _not_ be adjusted to match the skeleton length, and vice versa; i.e. adjustments should _never_ convert a numeric element in the pattern to an alphabetic element, or the opposite. See the second set of examples below. 756 7572. When the pattern field corresponds to an availableFormats skeleton with a field length that matches the field length in the requested skeleton, the pattern field length should _not_ be adjusted. This permits locale data to override a requested field length; see the third example below. 758 7593. Pattern field lengths for hour, minute, and second should by default not be adjusted to match the requested field length (i.e. locale data takes priority). However APIs that map skeletons to patterns should provide the option to override this behavior for cases when a client really does want to force a specific pattern field length. 760 761--- 762 763For an example of general behavior, consider the following `dateFormatItem`: 764 765```xml 766<dateFormatItem id="yMMMd">d MMM y</dateFormatItem> 767``` 768 769If this is the best match for yMMMMd, the pattern is automatically expanded to produce a pattern "d MMMM y" in response to the request. Of course, if the desired behavior is that a request for yMMMMd should produce something _other_ than "d MMMM y", a separate `dateFormatItem` must be present, for example: 770 771```xml 772<dateFormatItem id="yMMMMd">d 'de' MMMM 'de' y</dateFormatItem> 773``` 774 775--- 776 777For an example of not converting a pattern fields between numeric and alphabetic (point 1 above), consider the following `dateFormatItem`: 778 779```xml 780<dateFormatItem id="yMMM">y年M月</dateFormatItem> 781``` 782 783If this is the best match for a requested skeleton yMMMM, automatic expansion should not produce a corresponding pattern “y年MMMM月”; rather, since “y年M月” specifies a numeric month M, automatic expansion should not modify the pattern, and should produce “y年M月” as the match for requested skeleton yMMMM. 784 785--- 786 787For an example of not converting a pattern field length if the corresponding skeleton field matches the requested field length (point 2 above), consider the following `dateFormatItem`: 788 789```xml 790<dateFormatItem id="MMMEd">E, d בMMMM</dateFormatItem> 791``` 792 793For Hebrew calendar date formats in the Hebrew locale, only the full month names should be used, even if abbreviated months are requested. Hence the `dateFormatItem` maps a request for abbreviated months to a pattern with full months. The same `dateFormatItem` can be expanded to expanded to match a request for “MMMMEd” to the same pattern. 794 795--- 796 797Finally: If the requested skeleton included both seconds and fractional seconds and the dateFormatItem skeleton included seconds but not fractional seconds, then the seconds field of the corresponding pattern should be adjusted by appending the locale’s decimal separator, followed by the sequence of ‘S’ characters from the requested skeleton. 798 799##### <a name="Missing_Skeleton_Fields" href="#Missing_Skeleton_Fields">Missing Skeleton Fields</a> 800 801If a client-requested set of fields includes both date and time fields, and if the `availableFormats` data does not include a `dateFormatItem` whose skeleton matches the same set of fields, then the request should be handled as follows: 802 8031. Divide the request into a date fields part and a time fields part. 8042. For each part, find the matching `dateFormatItem`, and expand the pattern as above. 8053. Combine the patterns for the two `dateFormatItem`s using the appropriate dateTimeFormat pattern, determined as follows from the requested date fields: 806 * If the requested date fields include wide month (MMMM, LLLL) and weekday name of any length (e.g. E, EEEE, c, cccc), use `<dateTimeFormatLength type="full">` 807 * Otherwise, if the requested date fields include wide month, use `<dateTimeFormatLength type="long">` 808 * Otherwise, if the requested date fields include abbreviated month (MMM, LLL), use `<dateTimeFormatLength type="medium">` 809 * Otherwise use `<dateTimeFormatLength type="short">` 810 811```xml 812<!ELEMENT appendItems (alias | (appendItem*, special*))> 813<!ELEMENT appendItem ( #PCDATA ) > 814<!ATTLIST appendItem request CDATA > 815``` 816 817In case the best match does not include all the requested calendar fields, the `appendItems` element describes how to append needed fields to one of the existing formats. Each `appendItem` element covers a single calendar field. In the pattern, {0} represents the format string, {1} the data content of the field, and {2} the display name of the field (see [Calendar Fields](#Calendar_Fields)). 818 819#### <a name="intervalFormats" href="#intervalFormats">Element intervalFormats</a> 820 821```xml 822<!ELEMENT intervalFormats (alias | (intervalFormatFallback*, intervalFormatItem*, special*)) > 823 824<!ELEMENT intervalFormatFallback ( #PCDATA ) > 825 826<!ELEMENT intervalFormatItem (alias | (greatestDifference*, special*)) > 827<!ATTLIST intervalFormatItem id NMTOKEN #REQUIRED > 828 829<!ELEMENT greatestDifference ( #PCDATA ) > 830<!ATTLIST greatestDifference id NMTOKEN #REQUIRED > 831``` 832 833Interval formats allow for software to format intervals like "Jan 10-12, 2008" as a shorter and more natural format than "Jan 10, 2008 - Jan 12, 2008". They are designed to take a "skeleton" pattern (like the one used in availableFormats) plus start and end datetime, and use that information to produce a localized format. 834 835The data supplied in CLDR requires the software to determine the calendar field with the greatest difference before using the format pattern. For example, the greatest difference in "Jan 10-12, 2008" is the day field, while the greatest difference in "Jan 10 - Feb 12, 2008" is the month field. This is used to pick the exact pattern. 836 837The pattern is then designed to be broken up into two pieces by determining the first repeating field. For example, "MMM d-d, y" would be broken up into "MMM d-" and "d, y". The two parts are formatted with the first and second datetime, as described in more detail below. 838 839For the purposes of determining a repeating field, standalone fields and format fields are considered equivalent. For example, given the pattern "LLL d - MMM d, Y", the repeating field would be "M" since standalone month field "L" is considered equivalent to format field "M" when determining the repeating field. Therefore the pattern would be broken up into "LLL d - " and "MMM d, Y". 840 841In case there is no matching pattern, the intervalFormatFallback defines the fallback pattern. The fallback pattern is of the form "{0} - {1}" or "{1} - {0}", where {0} is replaced by the start datetime, and {1} is replaced by the end datetime. The fallback pattern determines the default order of the interval pattern. "{0} - {1}" means the first part of the interval patterns in current local are formatted with the start datetime, while "{1} - {0}" means the first part of the interval patterns in current locale are formatted with the end datetime. 842 843The `id` attribute of intervalFormatItem is the "skeleton" pattern (like the one used in availableFormats) on which the format pattern is based. The `id` attribute of `greatestDifference` is the calendar field letter, for example 'M', which is the greatest difference between start and end datetime. 844 845The greatest difference defines a specific interval pattern of start and end datetime on a "skeleton" and a greatestDifference. As stated above, the interval pattern is designed to be broken up into two pieces. Each piece is similar to the pattern defined in date format. Also, each interval pattern could override the default order defined in fallback pattern. If an interval pattern starts with "latestFirst:", the first part of this particular interval pattern is formatted with the end datetime. If an interval pattern starts with "earliestFirst:", the first part of this particular interval pattern is formatted with the start datetime. Otherwise, the order is the same as the order defined in `intervalFormatFallback`. 846 847For example, the English rules that produce "Jan 10–12, 2008", "Jan 10 – Feb 12, 2008", and "Jan 10, 2008 – Feb. 12, 2009" are as follows: 848 849```xml 850<intervalFormatItem id="yMMMd"> 851 <greatestDifference id="M">MMM d – MMM d, yyyy</greatestDifference> 852 <greatestDifference id="d">MMM d–d, yyyy</greatestDifference> 853 <greatestDifference id="y">MMM d, yyyy – MMM d, yyyy</greatestDifference> 854</intervalFormatItem> 855``` 856 857To format a start and end datetime, given a particular "skeleton": 858 8591. Look for the `intervalFormatItem` element that matches the "skeleton", starting in the current locale and then following the locale fallback chain up to, but not including root (better results are obtained by following steps 2-6 below with locale- or language-specific data than by using matching intervalFormats from root). 8602. If no match was found from the previous step, check what the closest match is in the fallback locale chain, as in `availableFormats`. That is, this allows for adjusting the string value field's width, including adjusting between "MMM" and "MMMM", and using different variants of the same field, such as 'v' and 'z'. 8613. If no match was found from the previous steps and the skeleton combines date fields such as y,M,d with time fields such as H,h,m,s, then an `intervalFormatItem` can be synthesized as follows: 862 1. For `greatestDifference` values corresponding to the date fields in the skeleton, use the mechanisms described under [availableFormats](#availableFormats_appendItems) to generate the complete date-time pattern corresponding to the skeleton, and then combine two such patterns using the `intervalFormatFallback` pattern (the result will be the same for each `greatestDifference` of a day or longer). For example: 863 MMMdHm/d → "MMM d 'at' H:mm – MMM d 'at' H:mm" → "Jan 3 at 9:00 – Jan 6 at 11:00" 864 2. For `greatestDifference` values corresponding to the time fields in the skeleton, separate the skeleton into a date fields part and a time fields part. Use the mechanisms described under availableFormats to generate a date pattern corresponding to the date fields part. Use the time fields part to look up an `intervalFormatItem`. For each `greatestDifference` in the `intervalFormatItem`, generate a pattern by using the [dateTimeFormat](#dateTimeFormat) to combine the date pattern with the `intervalFormatItem`’s `greatestDifference` element value. For example: 865 MMMdHm/H → "MMM d 'at' H:mm – H:mm" → "Jan 3 at 9:00 – 11:00" 8664. If a match is found from previous steps, compute the calendar field with the greatest difference between start and end datetime. If there is no difference among any of the fields in the pattern, format as a single date using `availableFormats`, and return. 8675. Otherwise, look for `greatestDifference` element that matches this particular greatest difference. 8686. If there is a match, use the pieces of the corresponding pattern to format the start and end datetime, as above. 8697. Otherwise, format the start and end datetime using the fallback pattern. 870 871## <a name="Calendar_Fields" href="#Calendar_Fields">Calendar Fields</a> 872 873```xml 874<!ELEMENT fields ( alias | (field*, special*)) > 875<!ELEMENT field ( alias | (displayName*, relative*, relativeTime*, relativePeriod*, special*)) > 876<!ATTLIST field type ( era | era-short | era-narrow | year | year-short | year-narrow | quarter | quarter-short | quarter-narrow | month | month-short | month-narrow | week | week-short | week-narrow | weekOfMonth | weekOfMonth-short | weekOfMonth-narrow | day | day-short | day-narrow | dayOfYear | dayOfYear-short | dayOfYear-narrow | weekday | weekday-short | weekday-narrow | weekdayOfMonth | weekdayOfMonth-short | weekdayOfMonth-narrow | sun | sun-short | sun-narrow | mon | mon-short | mon-narrow | tue | tue-short | tue-narrow | wed | wed-short | wed-narrow | thu | thu-short | thu-narrow | fri | fri-short | fri-narrow | sat | sat-short | sat-narrow | dayperiod | dayperiod-short | dayperiod-narrow | hour | hour-short | hour-narrow | minute | minute-short | minute-narrow | second | second-short | second-narrow | zone | zone-short | zone-narrow ) #IMPLIED > 877 878<!ELEMENT relative (#PCDATA) > 879<!ATTLIST relative type NMTOKEN #IMPLIED > 880 881<!ELEMENT relativeTime ( alias | (relativeTimePattern*, special*)) > 882<!ATTLIST relativeTime type NMTOKEN #REQUIRED > 883 884<!ELEMENT relativeTimePattern ( #PCDATA ) > 885<!ATTLIST relativeTimePattern count ( zero | one | two | few | many | other ) #REQUIRED > 886 887<!ELEMENT relativePeriod (#PCDATA) > 888``` 889 890Translations may be supplied for names of calendar fields (elements of a calendar, such as Day, Month, Year, Hour, and so on), and for relative values for those fields (for example, the day with relative value -1 is "Yesterday"). There are four types of translations; some are only relevant or useful for certain types of fields: 891 892* `<displayName>` General display name for the field type. This should be relevant for all elements, including those like era and zone that might not have useful forms for the other name types. These are typically presented in titlecase (eg “Day”) since they are intended as labels in a UI. 893* `<relative>` Display names for the current instance of the field, and one or two past and future instances. In English, data is provided for year, quarter, month, week, day, specific days of the week (sun, mon, tue, …), and—with offset 0 only—for hour, minute, and second. 894* `<relativeTime>` Display names for an instance of the field that is a counted number of units in the past or the future relative to the current instance; this needs plural forms. In English, data is provided for year, quarter, month, week, day, specific days of the week, hour, minute, and second. 895* `<relativePeriod>` Pattern for designating an instance of the specified field in relation to some other date reference. This is currently only used for weeks, and provides a pattern such as “the week of {0}” which can be used to generate designations such as “the week of April 11, 2016” or “the week of April 11–15”. 896 897Where there is not a convenient, customary word or phrase in a particular language for a particular type of relative value, it should be omitted. 898 899Examples, first for English: 900 901```xml 902<fields> 903 … 904 <field type="day"> 905 <displayName>Day</displayName> 906 <relative type="-1">yesterday</relative> 907 <relative type="0">today</relative> 908 <relative type="1">tomorrow</relative> 909 <relativeTime type="future"> 910 <relativeTimePattern count="one">in {0} day</relativeTimePattern> 911 <relativeTimePattern count="other">in {0} days</relativeTimePattern> 912 </relativeTime> 913 <relativeTime type="past"> 914 <relativeTimePattern count="one">{0} day ago</relativeTimePattern> 915 <relativeTimePattern count="other">{0} days ago</relativeTimePattern> 916 </relativeTime> 917 </field> 918 <field type="weekday"> 919 <displayName>Day of the Week</displayName> 920 </field> 921 <field type="sun"> 922 <relative type="-1">last Sunday</relative> 923 <relative type="0">this Sunday</relative> 924 <relative type="1">next Sunday</relative> 925 <relativeTime type="future"> 926 <relativeTimePattern count="one">in {0} Sunday</relativeTimePattern> 927 <relativeTimePattern count="other">in {0} Sundays</relativeTimePattern> 928 </relativeTime> 929 <relativeTime type="past"> 930 <relativeTimePattern count="one">{0} Sunday ago</relativeTimePattern> 931 <relativeTimePattern count="other">{0} Sundays ago</relativeTimePattern> 932 </relativeTime> 933 </field> 934 … 935 <field type="hour"> 936 <displayName>Hour</displayName> 937 <relative type="0">now</relative> 938 <relativeTime type="future"> 939 <relativeTimePattern count="one">in {0} hour</relativeTimePattern> 940 <relativeTimePattern count="other">in {0} hours</relativeTimePattern> 941 </relativeTime> 942 <relativeTime type="past"> 943 <relativeTimePattern count="one">{0} hour ago</relativeTimePattern> 944 <relativeTimePattern count="other">{0} hours ago</relativeTimePattern> 945 </relativeTime> 946 </field> 947 … 948</fields> 949 950``` 951 952Second, for German; includes relative type="-2"/"2", present in the English example: 953 954```xml 955<fields> 956 … 957 <field type="day"> 958 <displayName>Tag</displayName> 959 <relative type="-2">Vorgestern</relative> 960 <relative type="-1">Gestern</relative> 961 <relative type="0">Heute</relative> 962 <relative type="1">Morgen</relative> 963 <relative type="2">Übermorgen</relative> 964 <relativeTime type="future"> 965 <relativeTimePattern count="one">In {0} Tag</relativeTimePattern> 966 <relativeTimePattern count="other">In {0} Tagen</relativeTimePattern> 967 </relativeTime> 968 <relativeTime type="past"> 969 <relativeTimePattern count="one">Vor {0} Tag</relativeTimePattern> 970 <relativeTimePattern count="other">Vor {0} Tagen</relativeTimePattern> 971 </relativeTime> 972 </field> 973 … 974</fields> 975``` 976 977A special name for “now” is indicated using `<relative type="0">` for the "second" field. For example, in English: 978 979```xml 980<field type="second"> 981 <displayName>Second</displayName> 982 <relative type="0">now</relative> 983 … 984</field> 985``` 986 987Different widths can be supplied for certain fields, such as: 988 989```xml 990<field type="year-short"> 991 <displayName>yr.</displayName> 992 <relative type="-1">last yr.</relative> 993 <relative type="0">this yr.</relative> 994 <relative type="1">next yr.</relative> 995 <relativeTime type="future"> 996 <relativeTimePattern count="one">in {0} yr.</relativeTimePattern> 997 <relativeTimePattern count="other">in {0} yr.</relativeTimePattern> 998 </relativeTime> 999 <relativeTime type="past"> 1000 <relativeTimePattern count="one">{0} yr. ago</relativeTimePattern> 1001 <relativeTimePattern count="other">{0} yr. ago</relativeTimePattern> 1002 </relativeTime> 1003</field> 1004``` 1005 1006As in other cases, **narrow** may be ambiguous out of context. 1007 1008## <a name="Supplemental_Calendar_Data" href="#Supplemental_Calendar_Data">Supplemental Calendar Data</a> 1009 1010### <a name="Calendar_Data" href="#Calendar_Data">Calendar Data</a> 1011 1012```xml 1013<!ELEMENT calendarData ( calendar* )> 1014<!ELEMENT calendar ( calendarSystem?, inheritEras?, eras? )> 1015<!ATTLIST calendar type NMTOKENS #REQUIRED> 1016<!ATTLIST calendar territories NMTOKENS #IMPLIED > <!-- deprecated, replaced by calendarPreferenceData --> 1017 1018<!ELEMENT calendarSystem EMPTY> 1019<!ATTLIST calendarSystem type (solar | lunar | lunisolar | other) #REQUIRED> 1020 1021<!ELEMENT inheritEras EMPTY > 1022<!ATTLIST inheritEras calendar NMTOKEN #REQUIRED > 1023 1024<!ELEMENT eras ( era* )> 1025 1026<!ELEMENT era EMPTY> 1027<!ATTLIST era type NMTOKENS #REQUIRED> 1028<!ATTLIST era start CDATA #IMPLIED> 1029<!ATTLIST era end CDATA #IMPLIED> 1030<!ATTLIST era code NMTOKEN #IMPLIED > 1031<!ATTLIST era aliases NMTOKENS #IMPLIED > 1032``` 1033 1034The `<calendarData>` element now provides only locale-independent data about calendar behaviors via its `<calendar>` subelements, which for each calendar can specify the astronomical basis of the calendar (solar, lunar, etc.) and the date ranges for its eras. 1035 1036Era start or end dates are specified in terms of the equivalent proleptic Gregorian date (in "y-M-d" format). Eras may be open-ended, with unspecified start or end dates. For example, here are the eras for the Gregorian calendar: 1037 1038```xml 1039<era type="0" end="0-12-31" code="gregory-inverse" aliases="bc bce"/> 1040<era type="1" start="1-01-01" code="gregory" aliases="ad ce"/> 1041``` 1042 1043For a sequence of eras with specified start dates, the end of each era need not be explicitly specified (it is assumed to match the start of the subsequent era). For example, here are the first few eras for the Japanese calendar: 1044 1045```xml 1046<era type="0" start="645-6-19" /> 1047<era type="1" start="650-2-15" /> 1048<era type="2" start="672-1-1" /> 1049… 1050``` 1051 1052Some eras have additional `code` and `aliases` attributes that define invariant strings for identifying the eras. The `code` is a single globally unique identifier, and `aliases` are space-separated identifiers unique within the calendar. The code and aliases follow the following rules: 1053 10541. Every calendar has either an era with a `code` that is the same as the BCP-47 name of that calendar or an `inheritEras` element pointing to another calendar with such an era. This era should be used for anchoring the "extended year" in the calendar (`u` in the date format pattern). 10552. Eras that count backwards (larger numbers for older years) are suffixed with `-inverse`. 10563. If the same era code is used in multiple calendars, then the calculations for year, month, and day in that era must be the same in all calendars in which it is used. For example, the `ethioaa` era is used in two calendar systems. 1057 1058If a `<calendar>` contains an `<inheritEras/>` element, all eras from the specified calendar should be inserted in order into the sequence of eras for the current calendar and follow the same start and end date rules. For example: 1059 1060```xml 1061<calendar type="japanese"> 1062 <inheritEras calendar="gregorian" /> 1063 <eras> 1064 <era type="0" start="645-6-19"/> 1065 <era type="1" start="650-2-15"/> 1066 <!-- ... --> 1067 </eras> 1068</calendar> 1069``` 1070 1071This means that the two eras from calendar "gregorian" should be inserted into the era list for "japanese" for calculations and formatting. 1072 1073**Note:** The `territories` attribute in the `calendar` element is deprecated. It was formerly used to indicate calendar preference by territory, but this is now given by the _[Calendar Preference Data](#Calendar_Preference_Data)_ below. 1074 1075### <a name="Calendar_Preference_Data" href="#Calendar_Preference_Data">Calendar Preference Data</a> 1076 1077```xml 1078<!ELEMENT calendarPreferenceData ( calendarPreference* ) > 1079<!ELEMENT calendarPreference EMPTY > 1080<!ATTLIST calendarPreference territories NMTOKENS #REQUIRED > 1081<!ATTLIST calendarPreference ordering NMTOKENS #REQUIRED > 1082``` 1083 1084The `calendarPreference` element provides a list of commonly used calendar types in a territory. The `ordering` attribute indicates the list of calendar types in preferred order. The first calendar type in the list is the default calendar type for the territory. For example: 1085 1086```xml 1087<calendarPreference territories="001" ordering="gregorian"/> 1088<calendarPreference territories="JP" ordering="gregorian japanese"/> 1089<calendarPreference territories="TH" ordering="buddhist gregorian"/> 1090``` 1091 1092The `calendarPreference` elements above indicate: 1093 1094* The default (for territory "001") is that only the Gregorian calendar is commonly used. 1095* For Japan, the Gregorian and Japanese calendars are both used, with Gregorian preferred (the default). 1096* For Thailand, the Buddhist and Gregorian calendars are both used, and Buddhist is preferred (the default). 1097 1098The calendars in common use for a locale should typically be shown in UIs that provide a choice of calendars. (An 'Other...' button could give access to the other available calendars.) 1099 1100### <a name="Week_Data" href="#Week_Data">Week Data</a> 1101 1102```xml 1103<!ELEMENT weekData ( minDays*, firstDay*, weekendStart*, weekendEnd*, weekOfPreference* )> 1104 1105<!ELEMENT minDays EMPTY> 1106<!ATTLIST minDays count (1 | 2 | 3 | 4 | 5 | 6 | 7) #REQUIRED> 1107<!ATTLIST minDays territories NMTOKENS #REQUIRED> 1108 1109<!ELEMENT firstDay EMPTY > 1110<!ATTLIST firstDay day (sun | mon | tue | wed | thu | fri | sat) #REQUIRED> 1111<!ATTLIST firstDay territories NMTOKENS #REQUIRED> 1112 1113<!ELEMENT weekendStart EMPTY> 1114<!ATTLIST weekendStart day (sun | mon | tue | wed | thu | fri | sat) #REQUIRED> 1115<!ATTLIST weekendStart territories NMTOKENS #REQUIRED> 1116 1117<!ELEMENT weekendEnd EMPTY> 1118<!ATTLIST weekendEnd day (sun | mon | tue | wed | thu | fri | sat) #REQUIRED> 1119<!ATTLIST weekendEnd territories NMTOKENS #REQUIRED> 1120 1121<!ELEMENT weekOfPreference EMPTY> 1122<!ATTLIST weekOfPreference locales NMTOKENS #REQUIRED> 1123<!ATTLIST weekOfPreference ordering NMTOKENS #REQUIRED> 1124``` 1125 1126These values provide territory-specific information needed for week-of-year and week-of-month calculations, as well as information on conventions for first day of the week, for weekends, and for week designations. For most elements, the default is provided by the element with `territories="001"`; for `weekOfPreference` elements the default is provided by the element with `locales="und"`. 1127 1128```xml 1129<weekData> 1130 <minDays count="1" territories="001" /> 1131 <minDays count="4" territories="AD AN AT AX BE BG CH CZ DE DK EE ES FI FJ FO FR GB …" /> 1132 <firstDay day="mon" territories="001" /> 1133 <firstDay day="fri" territories="BD MV" /> 1134 <firstDay day="sat" territories="AE AF BH DJ DZ EG IQ IR JO …" /> 1135 … 1136 <weekendStart day="sat" territories="001" /> 1137 <weekendStart day="sun" territories="IN" /> 1138 <weekendStart day="thu" territories="AF DZ IR OM SA YE" /> 1139 <weekendStart day="fri" territories="AE BH EG IL IQ JO KW …" /> 1140 … 1141 <weekOfPreference ordering="weekOfYear" locales="und" /> 1142 <weekOfPreference ordering="weekOfYear weekOfMonth" locales="am az bs cs cy da el et hi ky lt mk sk ta th" /> 1143 <weekOfPreference ordering="weekOfYear weekOfMonth weekOfInterval" locales="is mn no sv vi" /> 1144 <weekOfPreference ordering="weekOfYear weekOfDate weekOfMonth" locales="fi zh-TW" /> 1145 … 1146``` 1147 1148In order for a week to count as the first week of a new year for week-of-year calculations, the week beginning with `firstDay` must include at least the number of days in the new year specified by the `minDays` value; otherwise the week will count as the last week of the previous year (and for week-of-month calculations, `minDays` also specifies the minimum number of days in the new month for a week to count as part of that month). 1149 1150> **Note:** For week-of-year calculations, Gregorian years may have 52 or 53 weeks. Changes in the value of `minDays` or `firstDay` can affect the year to which a date is assigned as well as the number of weeks in a given year; implementations that parse dates using week-of-year formats should be prepared to handle such cases. For example when parsing a date in week 53 of a year for which current values of `minDays` and `firstDay` no longer result in a 53-week year, that date should be treated as in the first week of the following year. 1151 1152The day indicated by `firstDay` is the one that should be shown as the first day of the week in a calendar view. This is not necessarily the same as the first day after the weekend (or the first work day of the week), which should be determined from the weekend information. Currently, day-of-week numbering is based on `firstDay` (that is, day 1 is the day specified by `firstDay`), but in the future we may add a way to specify this separately. The `firstDay` value determined from the region can be overridden by the locale keyword "fw", see [Unicode First Day Identifier](tr35.md#UnicodeFirstDayIdentifier). 1153 1154What is meant by the weekend varies from country to country. It is typically when most non-retail businesses are closed. The time should not be specified unless it is a well-recognized part of the day. The `weekendStart` day defaults to "sat", and `weekendEnd` day defaults to "sun". For more information, see _[Dates and Date Ranges](tr35.md#Date_Ranges)_. 1155 1156Each `weekOfPreference` element provides, for its specified locales, an ordered list of the preferred types of week designations for that set of locales. There are four types of week designations, each of which makes use of date patterns available in the locale, as follows: 1157 1158###### Table: <a name="Week_Designation_Types" href="#Week_Designation_Types">Week Designation Types</a> 1159 1160| Type | Examples | Date Pattern | Comments | 1161|----------------|-----------------------------------|-------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------| 1162| weekOfYear | week 15 of 2016 | \<dateFormatItem id='yw' count='one'\>'week' w 'of' Y\<… | The **week of** construction takes a count attribute, just in case the pattern changes depending on the numeric value of the **w** value. (In the future, we're likely to add an ordinal value, for constructions like “3rd week of March”.) In languages where the month name needs grammatical changes (aside from just the simple addition of a prefix or suffix), localizers will typically use a work-around construction. | 1163| weekOfMonth | week 2 of April 2nd week of April | \<dateFormatItem id='MMMMW'' count='one'\>'week' W 'of' MMM\<… | (same comment as above) | 1164| weekOfDate | the week of April 11, 2016 | \<field type="week"\>\<relativePeriod>the week of {0}\<… | The date pattern that replaces {0} is determined separately and may use the first day or workday of the week, the range of the full week or work week, etc. | 1165| weekOfInterval | the week of April 11–15 | \<field type="week"\>\<relativePeriod>the week of {0}\<… | (same comment as above) | 1166 1167#### First Day Overrides 1168 1169The calculation of the first day of the week depends on various fields in a locale_identifier, according to the following algorithm. The data in the `firstDay` elements is treated as a map from region to day, with any missing value using the value for 001. 1170 11711. If there is a valid `-u-fw-` day value, return that day. 11722. Else if there is a valid `-u-rg-` region value, return that region's firstDay map value. 11733. Else if there is a valid `-u-ca-` calendar value, where that calendar specifies the first day, then return that first day. (Most calendars do not specify the first day.) 11744. Else if there is an explicit region subtag, then return that region's firstDay map value. 11755. Else if there is a valid `-u-sd-` subdivision value, return that region's firstDay map value. 11766. Else if the [Add Likely Subtags](tr35.md#Likely_Subtags) algorithm produces a region, return that region's firstDay map value. 11777. Else return the firstDay map value for 001. 1178 1179*Example:* 1180 1181| Locale Identifier | "Winning" subtags | Region | 1182|----|----|----| 1183|en-AU-u-ca-iso8601-fw-tue-rg-afzzzz-sd-cabc | -fw-tue | n/a, uses Tuesday | 1184|en-AU-u-ca-iso8601-rg-afzzzz-sd-cabc | -rg-afzzzz | AF | 1185|en-AU-u-ca-iso8601-sd-cabc | -ca-iso8601 | n/a, uses Monday | 1186|en-AU-u-sd-cabc | -AU | AU | 1187|en-u-sd-cabc | -sd-cabc | CA | 1188|en | | US (from likely subtags) | 1189|zxx | 001 | (fallback) | 1190 1191### <a name="Time_Data" href="#Time_Data">Time Data</a> 1192 1193```xml 1194<!ELEMENT timeData ( hours* ) > 1195<!ELEMENT hours EMPTY > 1196<!ATTLIST hours preferred NMTOKEN #REQUIRED > 1197<!ATTLIST hours allowed NMTOKENS #REQUIRED > 1198<!ATTLIST hours regions NMTOKENS #REQUIRED > 1199``` 1200 1201This element is for data that indicates, for various regions, the preferred time cycle in the region, as well as all time cycles that are considered acceptable in the region. The defaults are those specified for region 001. 1202 1203There is a single `preferred` value, and multiple `allowed` values. The meanings of the values H, h, K, k, b and B are defined in [Date Field Symbol Table](#Date_Field_Symbol_Table). The `allowed` values are in preference order, and are used with the 'C' hour skeleton pattern symbol. 1204 1205For example, in the following, RU (Russia) is marked as using only 24 hour time, and in particular the 24 hour time that goes from 0..23 (H), rather than from 1..24 (k). 1206 1207Also note that the `regions` allows either region codes (`001`, `JP`) or 1208locale IDs (`gu_IN`). 1209 1210```xml 1211<timeData> 1212 <hours preferred="H" allowed="H h" regions="001 …" /> 1213 <hours preferred="H" allowed="H K h" regions="JP" /> 1214 <hours preferred="H" allowed="H" regions="IL RU" /> 1215 <hours preferred="h" allowed="H h" regions="AE AG AL … US … ZW" /> 1216 <hours preferred="h" allowed="hB h hb H" regions="ta_IN"/> 1217 <hours preferred="h" allowed="hB hb h H" regions="TW ET gu_IN mr_IN pa_IN"/> 1218 … 1219``` 1220 1221The B and b date symbols provide for formats like “3:00 at night”. When the ‘C’ option is used, the values in `allowed` are traversed from first to last, picking the first available format. For example, in the following a system that supports hB should choose that as the most preferred format for the C (not the `preferred` value H). 1222 1223```xml 1224<hours preferred="H" allowed="hB H" regions="CD" /> 1225<hours preferred="H" allowed="hB hb h H" regions="KE MM TZ UG" /> 1226``` 1227 1228Some systems may not want to use B and b, even if preferred for the locale, so for compatibility the `preferred` value is limited to {H, h, K, k}, and is the option selected by the ‘j’ date symbol. Thus the `preferred` value may not be the same as the first `allowed` value. 1229 1230The preferred value for the locale can be overridden by the locale keyword "hc", see [Unicode Hour Cycle Identifier ](tr35.md#UnicodeHourCycleIdentifier). 1231 1232### <a name="Day_Period_Rule_Sets" href="#Day_Period_Rule_Sets">Day Period Rule Sets</a> 1233 1234```xml 1235<!ELEMENT dayPeriodRuleSet ( dayPeriodRules* ) > 1236<!ATTLIST dayPeriodRuleSet type NMTOKEN #IMPLIED > 1237 1238<!ELEMENT dayPeriodRules (dayPeriodRule*) > 1239<!ATTLIST dayPeriodRules locales NMTOKENS #REQUIRED > 1240 1241<!ELEMENT dayPeriodRule EMPTY > 1242<!ATTLIST dayPeriodRule type NMTOKEN #REQUIRED > 1243<!ATTLIST dayPeriodRule at NMTOKEN #IMPLIED > 1244<!ATTLIST dayPeriodRule from NMTOKEN #IMPLIED > 1245<!ATTLIST dayPeriodRule before NMTOKEN #IMPLIED > 1246``` 1247 1248Each locale can have a set of day period rules, which determine the periods during a day for use in time formats like "10:00 at night", or to select statements like "Your email arrived last night." If locales do not have dayPeriodRules, the computation of dayPeriods falls back to AM/PM. 1249 1250There are two kinds of dayPeriodRuleSets, based on the type: 1251 1252The **_format_** type is used in conjunction with times, such as to express "3:00 in the afternoon", or "12:00 noon". Many languages do not normally use terms that match AM/PM for such times, instead breaking up the day into more periods. 1253 1254The **stand-alone** type is used for selecting a period of the day for a general time associated with an event. For example, it can be used to select a message like: 1255 1256``` 1257<msg ... > 1258{day_period, select, 1259MORNING1 {Your email arrived yesterday morning.} 1260AFTERNOON1 {Your email arrived yesterday afternoon.} 1261EVENING1 {Your email arrived yesterday evening.} 1262NIGHT1 {Your email arrived last night.} 1263other {Your email arrived yesterday.} 1264... 1265} 1266</msg> 1267``` 1268 1269The translated values for the selection (**stand-alone**) day periods are intended for use in designating a time of day, without an hour value. 1270 1271These are relative times within a single day. If the event can occur on multiple days, then that needs to be handled at a higher level. 1272 1273As with plurals, the exact set of periods used for any language may be different. It is the responsibility of any translation software to pick the relevant day periods for the locale for display to the translator (and end user). 1274 1275#### <a name="Day_Period_Rules" href="#Day_Period_Rules">Day Period Rules</a> 1276 1277Here are the requirements for a rule set. 1278 1279##### <a name="Fixed_periods" href="#Fixed_periods">Fixed periods</a> 1280 1281There are 4 dayPeriods that are fixed; am/pm are always defined, and always have the same meaning and definition for every locale. Midnight and noon are optional, however if they are defined, they have the same meaning and definition as in all other locales where they are defined. 1282 1283```xml 1284<dayPeriodRule type="midnight" at="00:00" /> 1285<dayPeriodRule type="am" from="00:00" before="12:00" /> 1286<dayPeriodRule type="noon" at="12:00" /> 1287<dayPeriodRule type="pm" from="12:00" before="24:00" /> 1288``` 1289 1290Note that midnight and am can overlap, as can noon and pm. 1291 1292All locales must support am/pm, but not all support **noon** or **midnight**; they are only supported if they meet the above definitions. For example, German has no unique term that means exactly 12:00 noon; the closest is Mittag, but that can extend before or after 12 noon. 1293 1294**Midnight** is also special, since it can refer to either 00:00 or 24:00 — either at the start or end of the day. That means that Tuesday 24:00 = Wednesday 00:00. “Midnight Tuesday" is thus ambiguous: it means 24:00 in “the party is Tuesday from 10pm to 12 midnight”, while it means 00:00 in “I was awake from 12 midnight to 3 in the morning”. 1295 1296It is strongly recommended that implementations provide for the ability to specify whether **midnight** is supported or not (and for either 00:00 or 24:00 or both), since only the caller knows enough of the context to determine what to use. In the absence of such information, 24:00 may be the best choice. 1297 1298##### <a name="Variable_periods" href="#Variable_periods">Variable periods</a> 1299 13001. If a locale has a set of dayPeriodRules for variable periods, it needs to completely cover the 24 hours in a day (from 0:00 before 24:00), with **no** overlaps between any dayPeriodRules. They may overlap with the **Fixed Periods**. 1301 If it does not have a rule set for variable periods, behavior should fall back to using the fixed periods (am, pm). 13022. "from" is a closed interval (inclusive). _(as is the deprecated "to")_ 13033. "before" is an open interval (exclusive). _(as is the deprecated "after")_ 13044. "at" means starting time and end time are the same. _("at" is deprecated except when used for the fixed periods)_ 13055. There must be exactly one of {at, from, after} and exactly one of {at, to, before} for each dayPeriodRule. 13066. Use of non-zero minutes or seconds is deprecated. 13077. The dayPeriodRules for format must allow that hh:mm [period name] and hh [period name] can be parsed uniquely to HH:mm [period name]. 1308 * For example, you can't have `<dayPeriod type = "morning1" from="00:00" to="13:00"/>` because "12:30 {morning}" would be ambiguous. 13098. There must not be two rules with the same type. A day period rule may, however, span 24:00 / 00:00. Example: 1310 * _Valid:_ 1311 * `<dayPeriod type = "night1" from="21:00" to="05:00"/>` 1312 * _Invalid:_ 1313 * `<dayPeriod type = "night1" from="00:00" to="05:00"/>` 1314 * `<dayPeriod type = "night1" from="21:00" to="24:00"/>` 13159. 24:00 is _only_ allowed in _before_="24:00". 1316 1317##### <a name="Parsing_Day_Periods" href="#Parsing_Day_Periods">Parsing Day Periods</a> 1318 1319When parsing, if the hour is present with a strict parse the dayperiod is checked for consistency with the hour. If there is no hour, the center of the first matching dayPeriodRule can be chosen (starting from 0:00). However, if there is other information available when parsing, a different point within the interval may be chosen. 1320 1321The dayPeriodRule may span two days, such as where **night1** is [21:00, 06:00). In that case, the midpoint is 01:30, so when parsing “Nov 12, at night”, the midpoint result would be Nov 12, 01:30. “Nov 12, am”, “Nov 12, pm”, “Nov 12, noon” can be parsed similarly, resulting in Nov 12, 06:00; Nov 12, 18:00; and Nov 12, 12:00; respectively. 1322 1323“Nov 12, midnight” is special, because midnight may mean either 00:00 or 24:00. Extra information may be needed to disambiguate which is meant, such as whether the time is at the start or end of an interval. In the absence of such information, 24:00 may be the best choice. See the discussion of **midnight** above. 1324 1325If rounding is done—including the rounding done by the time format—then it needs to be done before the dayperiod is computed, so that the correct format is shown. 1326 1327For examples, see [Day Periods Chart](https://unicode-org.github.io/cldr-staging/charts/38/supplemental/day_periods.html). 1328 1329## <a name="Time_Zone_Names" href="#Time_Zone_Names">Time Zone Names</a> 1330 1331```xml 1332<!ELEMENT timeZoneNames (alias | (hourFormat*, gmtFormat*, gmtZeroFormat*, regionFormat*, fallbackFormat*, zone*, metazone*, special*)) > 1333 1334<!ELEMENT hourFormat ( #PCDATA ) > 1335<!ELEMENT gmtFormat ( #PCDATA ) > 1336<!ELEMENT gmtZeroFormat ( #PCDATA ) > 1337 1338<!ELEMENT regionFormat ( #PCDATA ) > 1339<!ATTLIST regionFormat type ( standard | daylight ) #IMPLIED > 1340 1341<!ELEMENT fallbackFormat ( #PCDATA ) > 1342 1343<!ELEMENT zone (alias | ( long*, short*, exemplarCity*, special*)) > 1344<!ATTLIST zone type CDATA #REQUIRED > 1345 1346<!ELEMENT metazone (alias | ( long*, short*, special*)) > 1347<!ATTLIST metazone type CDATA #REQUIRED > 1348 1349<!ELEMENT long (alias | (generic*, standard*, daylight*, special*)) > 1350<!ELEMENT short (alias | (generic*, standard*, daylight*, special*)) > 1351 1352<!ELEMENT generic ( #PCDATA ) > 1353<!ELEMENT standard ( #PCDATA ) > 1354<!ELEMENT daylight ( #PCDATA ) > 1355 1356<!ELEMENT exemplarCity ( #PCDATA ) > 1357``` 1358 1359The time zone IDs (TZID) are language-independent, and follow the _TZ time zone database_ [[Olson](tr35.md#Olson)] and naming conventions. However, the display names for those IDs can vary by locale. The generic time is so-called _wall-time_; what clocks use when they are correctly switched from standard to daylight time at the mandated time of the year. 1360 1361Unfortunately, the canonical TZIDs (those in zone.tab) are not stable: they may change in each release of the _TZ_ Time Zone database. In CLDR, however, stability of identifiers is very important. So the canonical IDs in CLDR are kept stable as described in [Canonical Form](tr35.md#Canonical_Form). 1362 1363The _TZ time zone database_ can have multiple IDs that refer to the same entity. It does contain information on equivalence relationships between these IDs, such as "Asia/Calcutta" and "Asia/Kolkata". It does not remove IDs (with a few known exceptions), but it may change the "canonical" ID which is in the file zone.tab. 1364 1365For lookup purposes specifications such as CLDR need a stable canonical ID, one that does not change from release to release. The stable ID is maintained as the first alias item _type_ element in the file bcp47/timezone.xml, such as: 1366 1367 <type name="inccu" alias="Asia/Calcutta Asia/Kolkata"/> 1368 1369That file also contains the short ID used in keywords. In versions of CLDR previous to 1.8, the alias information (but not the short ID) was in Supplemental Data under the zoneItem, such as: 1370 1371 <zoneItem type="Asia/Calcutta" territory="IN" aliases="Asia/Kolkata"/> 1372 1373This element was deprecated after the introduction of bcp47/timezone.xml, because the information became redundant (or was contained in the _TZ time zone database_). 1374 1375The following is an example of time zone data. Although this is an example of possible data, in most cases only the exemplarCity needs translation. And that does not even need to be present, if a country only has a single time one. As always, the _type_ field for each zone is the identification of that zone. It is not to be translated. 1376 1377```xml 1378<zone type="America/Los_Angeles"> 1379 <long> 1380 <generic>Pacific Time</generic> 1381 <standard>Pacific Standard Time</standard> 1382 <daylight>Pacific Daylight Time</daylight> 1383 </long> 1384 <short> 1385 <generic>PT</generic> 1386 <standard>PST</standard> 1387 <daylight>PDT</daylight> 1388 </short> 1389 <exemplarCity>San Francisco</exemplarCity> 1390</zone> 1391 1392<zone type="Europe/London"> 1393 <long> 1394 <generic>British Time</generic> 1395 <standard>British Standard Time</standard> 1396 <daylight>British Daylight Time</daylight> 1397 </long> 1398 <exemplarCity>York</exemplarCity> 1399</zone> 1400``` 1401 1402In a few cases, some time zone IDs do not designate a city, as in: 1403 1404```xml 1405<zone type="America/Puerto_Rico"> 1406 ... 1407</zone> 1408 1409<zone type="America/Guyana"> 1410 ... 1411</zone> 1412 1413<zone type="America/Cayman"> 1414 ... 1415</zone> 1416 1417<zone type="America/St_Vincent"> 1418 ... 1419</zone> 1420``` 1421 1422They may designate countries or territories; their actual capital city may be a name that is too common, or too uncommon. CLDR time zone IDs follow the [Olson](tr35.md#Olson) naming conventions. 1423 1424> **Note:** CLDR does not allow "GMT", "UT", or "UTC" as translations (short or long) of time zones other than GMT itself. 1425 1426> **Note:** Transmitting "14:30" with no other context is incomplete unless it contains information about the time zone. Ideally one would transmit neutral-format date/time information, commonly in UTC (GMT), and localize as close to the user as possible. (For more about UTC, see [[UTCInfo](tr35.md#UTCInfo)].) 1427 1428The conversion from local time into UTC depends on the particular time zone rules, which will vary by location. The standard data used for converting local time (sometimes called _wall time_) to UTC and back is the _TZ Data_ [[Olson](tr35.md#Olson)], used by Linux, UNIX, Java, ICU, and others. The data includes rules for matching the laws for time changes in different countries. For example, for the US it is: 1429 1430> "During the period commencing at 2 o'clock antemeridian on the second Sunday of March of each year and ending at 2 o'clock antemeridian on the first Sunday of November of each year, the standard time of each zone established by sections 261 to 264 of this title, as modified by of this title, shall be advanced one hour..." (United States Law - 15 U.S.C. §6(IX)(260-7), as amended by Energy Policy Act of 2005). 1431 1432Each region that has a different time zone or daylight savings time rules, either now or at any time back to 1970, is given a unique internal ID, such as `Europe/Paris` . (Some IDs are also distinguished on the basis of differences before 1970.) As with currency codes, these are internal codes. A localized string associated with these is provided for users (such as in the Windows _Control Panels>Date/Time>Time Zone_). 1433 1434Unfortunately, laws change over time, and will continue to change in the future, both for the boundaries of time zone regions and the rules for daylight savings. Thus the _TZ_ data is continually being augmented. Any two implementations using the same version of the _TZ_ data will get the same results for the same IDs (assuming a correct implementation). However, if implementations use different versions of the data they may get different results. So if precise results are required then both the _TZ_ ID and the _TZ_ data version must be transmitted between the different implementations. 1435 1436For more information, see [[Data Formats](tr35.md#DataFormats)]. 1437 1438The following subelements of `<timeZoneNames>` are used to control the fallback process described in [Using Time Zone Names](#Using_Time_Zone_Names). 1439 1440###### Table: <a name="timeZoneNames_Elements_Used_for_Fallback" href="#timeZoneNames_Elements_Used_for_Fallback">timeZoneNames Elements Used for Fallback</a> 1441 1442<table><tbody> 1443<tr><th>Element Name</th><th>Data Examples</th><th>Results/Comment</th></tr> 1444<tr><td rowspan="2">hourFormat</td><td rowspan="2">"+HHmm;-HHmm"</td><td>"+1200"</td></tr> 1445 <tr><td>"-1200"</td></tr> 1446<tr><td rowspan="2">gmtFormat</td><td>"GMT{0}"</td><td>"GMT-0800"</td></tr> 1447 <tr><td>"{0}ВпГ"</td><td>"-0800ВпГ"</td></tr> 1448<tr><td>gmtZeroFormat</td><td>"GMT"</td><td>Specifies how GMT/UTC with no explicit offset (implied 0 offset) should be represented.</td></tr> 1449<tr><td rowspan="2">regionFormat</td><td>"{0} Time"</td><td>"Japan Time"</td></tr> 1450 <tr><td>"Hora de {0}"</td><td>"Hora de Japón"</td></tr> 1451<tr><td rowspan="2">regionFormat type="daylight"<br>(or "standard")</td><td>"{0} Daylight Time"</td><td>"France Daylight Time"</td></tr><tr><td>"horario de verano de {0}"</td><td>"horario de verano de Francia"</td></tr> 1452 <tr><td>fallbackFormat</td><td>"{1} ({0})"</td><td>"Pacific Time (Canada)"</td></tr> 1453</tbody></table> 1454 1455When referring to the abbreviated (short) form of the time zone name, there are often situations where the location-based (city or country) time zone designation for a particular language may not be in common usage in a particular territory. 1456 1457> **Note:** User interfaces for time zone selection can use the "generic location format" for time zone names to obtain the most useful ordering of names in a menu or list; see _[Using Time Zone Names](#Using_Time_Zone_Names)_ and the zone section of the _[Date Field Symbol Table](#Date_Field_Symbol_Table)._ 1458 1459### <a name="Metazone_Names" href="#Metazone_Names">Metazone Names</a> 1460 1461A metazone is a grouping of one or more internal TZIDs that share a common display name in current customary usage, or that have shared a common display name during some particular time period. For example, the zones _Europe/Paris, Europe/Andorra, Europe/Tirane, Europe/Vienna, Europe/Sarajevo, Europe/Brussels, Europe/Zurich, Europe/Prague, Europe/Berlin_, and so on are often simply designated _Central European Time_ (or translated equivalent). 1462 1463A metazone's display fields become a secondary fallback if an appropriate data field cannot be found in the explicit time zone data. The _usesMetazone_ field indicates that the target metazone is active for a particular time. This also provides a mechanism to effectively deal with situations where the time zone in use has changed for some reason. For example, consider the TZID "America/Indiana/Knox", which observed Central time (GMT-6:00) prior to October 27, 1991, and has currently observed Central time since April 2, 2006, but has observed Eastern time (GMT-5:00) between these two dates. This is denoted as follows 1464 1465```xml 1466<timezone type="America/Indiana/Knox"> 1467 <usesMetazone to="1991-10-27 07:00" mzone="America_Central" /> 1468 <usesMetazone to="2006-04-02 07:00" from="1991-10-27 07:00" mzone="America_Eastern" /> 1469 <usesMetazone from="2006-04-02 07:00" mzone="America_Central" /> 1470</timezone> 1471``` 1472 1473Note that the dates and times are specified in UTC, not local time. 1474 1475The metazones can then have translations in different locale files, such as the following. 1476 1477```xml 1478<metazone type="America_Central"> 1479 <long> 1480 <generic>Central Time</generic> 1481 <standard>Central Standard Time</standard> 1482 <daylight>Central Daylight Time</daylight> 1483 </long> 1484 <short> 1485 <generic>CT</generic> 1486 <standard>CST</standard> 1487 <daylight>CDT</daylight> 1488 </short> 1489 </metazone> 1490 <metazone type="America_Eastern"> 1491 <long> 1492 <generic>Eastern Time</generic> 1493 <standard>Eastern Standard Time</standard> 1494 <daylight>Eastern Daylight Time</daylight> 1495 </long> 1496 <short> 1497 <generic>ET</generic> 1498 <standard>EST</standard> 1499 <daylight>EDT</daylight> 1500 </short> 1501</metazone> 1502 1503<metazone type="America_Eastern"> 1504 <long> 1505 <generic>Heure de l’Est</generic> 1506 <standard>Heure normale de l’Est</standard> 1507 <daylight>Heure avancée de l’Est</daylight> 1508 </long> 1509 <short> 1510 <generic>HE</generic> 1511 <standard>HNE</standard> 1512 <daylight>HAE</daylight> 1513 </short> 1514</metazone> 1515``` 1516 1517When formatting a date and time value using this data, an application can properly be able to display "Eastern Time" for dates between 1991-10-27 and 2006-04-02, but display "Central Time" for current dates. (See also _[Dates and Date Ranges](tr35.md#Date_Ranges)_.) 1518 1519Metazones are used with the 'z', 'zzzz', 'v', and 'vvvv' date time pattern characters, and not with the 'Z', 'ZZZZ', 'VVVV' and other pattern characters for time zone formatting. For more information, see [Date Format Patterns](#Date_Format_Patterns). 1520 1521Note that several of the CLDR metazone IDs are the same as TZID aliases provided by the _TZ time zone database_ and also included in ICU data. For example: 1522* “Japan” is a CLDR metazone ID (which has short ID “japa”), but also an alias to the TZID “Asia/Tokyo” (which has BCP 47 ID “jptyo”). 1523* “GMT” is a CLDR metazone ID (which has short ID “mgmt”), but also an alias to the TZID “Etc/GMT” (which has BCP 47 ID “gmt”). 1524In practice this is not an issue, since metazone IDs and TZIDs are never used in the same way in any data structure, or in the same APIs in a library such as ICU. 1525 1526The `commonlyUsed` element is now deprecated. The CLDR committee has found it nearly impossible to obtain accurate and reliable data regarding which time zone abbreviations may be understood in a given territory, and therefore has changed to a simpler approach. Thus, if the short metazone form is available in a given locale, it is to be used for formatting regardless of the value of commonlyUsed. If a given short metazone form is known NOT to be understood in a given locale and the parent locale has this value such that it would normally be inherited, the inheritance of this value can be explicitly disabled by use of the 'no inheritance marker' as the value, which is 3 simultaneous empty set characters (U+2205). 1527 1528## <a name="Supplemental_Time_Zone_Data" href="#Supplemental_Time_Zone_Data">Supplemental Time Zone Data</a> 1529 1530### <a name="Metazones" href="#Metazones">Metazones</a> 1531 1532```xml 1533<!ELEMENT metaZones (metazoneInfo?, mapTimezones?) > 1534 1535<!ELEMENT metazoneInfo (timezone*) > 1536 1537<!ELEMENT timezone (usesMetazone*) > 1538<!ATTLIST timezone type CDATA #REQUIRED > 1539 1540<!ELEMENT usesMetazone EMPTY > 1541<!ATTLIST usesMetazone mzone NMTOKEN #REQUIRED > 1542<!ATTLIST usesMetazone from CDATA #IMPLIED > 1543<!ATTLIST usesMetazone to CDATA #IMPLIED > 1544 1545<!ELEMENT mapTimezones ( mapZone* ) > 1546<!ATTLIST mapTimezones type NMTOKEN #IMPLIED > 1547<!ATTLIST mapTimezones typeVersion CDATA #IMPLIED > 1548<!ATTLIST mapTimezones otherVersion CDATA #IMPLIED > 1549<!ATTLIST mapTimezones references CDATA #IMPLIED > 1550 1551<!ELEMENT mapZone EMPTY > 1552<!ATTLIST mapZone type CDATA #REQUIRED > 1553<!ATTLIST mapZone other CDATA #REQUIRED > 1554<!ATTLIST mapZone territory CDATA #IMPLIED > 1555<!ATTLIST mapZone references CDATA #IMPLIED > 1556``` 1557 1558The following subelement of `<metaZones>` provides a mapping from a single Unicode time zone id to metazones. For more information about metazones, see _[Time Zone Names](tr35-dates.md#Time_Zone_Names)_. 1559 1560```xml 1561<metazoneInfo> 1562 <timezone type="Europe/Andorra"> 1563 <usesMetazone mzone="Europe_Central" /> 1564 </timezone> 1565 .... 1566 <timezone type="Asia/Yerevan"> 1567 <usesMetazone to="1991-09-22 20:00" mzone="Yerevan" /> 1568 <usesMetazone from="1991-09-22 20:00" mzone="Armenia" /> 1569 </timezone> 1570 .... 1571``` 1572 1573The following subelement of `<metaZones>` specifies a mapping from a metazone to golden zones for each territory. For more information about golden zones, see _[Using Time Zone Names](tr35-dates.md#Using_Time_Zone_Names)_. 1574 1575```xml 1576<mapTimezones type="metazones"> 1577 <mapZone other="Acre" territory="001" type="America/Rio_Branco" /> 1578 <mapZone other="Afghanistan" territory="001" type="Asia/Kabul" /> 1579 <mapZone other="Africa_Central" territory="001" type="Africa/Maputo" /> 1580 <mapZone other="Africa_Central" territory="BI" type="Africa/Bujumbura" /> 1581 <mapZone other="Africa_Central" territory="BW" type="Africa/Gaborone" /> 1582 .... 1583``` 1584 1585### <a name="Windows_Zones" href="#Windows_Zones">Windows Zones</a> 1586 1587```xml 1588<!ELEMENT windowsZones (mapTimezones?) > 1589``` 1590 1591The `<mapTimezones>` element can be also used to provide mappings between Unicode time zone IDs and other time zone IDs. This example specifies a mapping from Windows TZIDs to Unicode time zone IDs. 1592 1593```xml 1594<mapTimezones otherVersion="07dc0000" typeVersion="2011n"> 1595 .... 1596 <!-- (UTC-08:00) Baja California --> 1597 <mapZone other="Pacific Standard Time (Mexico)" territory="001" type="America/Santa_Isabel"/> 1598 <mapZone other="Pacific Standard Time (Mexico)" territory="MX" type="America/Santa_Isabel"/> 1599 1600 <!-- (UTC-08:00) Pacific Time (US & Canada) --> 1601 <mapZone other="Pacific Standard Time" territory="001" type="America/Los_Angeles"/> 1602 <mapZone other="Pacific Standard Time" territory="CA" type="America/Vancouver America/Dawson America/Whitehorse"/> 1603 <mapZone other="Pacific Standard Time" territory="MX" type="America/Tijuana"/> 1604 <mapZone other="Pacific Standard Time" territory="US" type="America/Los_Angeles"/> 1605 <mapZone other="Pacific Standard Time" territory="ZZ" type="PST8PDT"/> 1606 .... 1607``` 1608 1609The attributes otherVersion and typeVersion in `<mapTimezones>` specify the versions of two systems. In the example above, otherVersion="07dc0000" specifies the version of Windows time zone and typeVersion="2011n" specifies the version of Unicode time zone IDs. The attribute `territory="001"` in `<mapZone>` element indicates the long canonical Unicode time zone ID specified by the `type` attribute is used as the default mapping for the Windows TZID. For each unique Windows TZID, there must be exactly one `<mapZone>` element with `territory="001"`. `<mapZone>` elements other than `territory="001"` specify territory specific mappings. When multiple Unicode time zone IDs are available for a single territory, the value of the `type` attribute will be a list of Unicode time zone IDs delimited by space. In this case, the first entry represents the default mapping for the territory. The territory "ZZ" is used when a Unicode time zone ID is not associated with a specific territory. 1610 1611**Note:** The long canonical Unicode time zone ID might be deprecated in the tz database [[Olson](tr35.md#Olson)]. For example, CLDR uses "Asia/Culcutta" as the long canonical time zone ID for Kolkata, India. The same ID was moved to 'backward' file and replaced with a new ID "Asia/Kolkata" in the tz database. Therefore, if you want to get an equivalent Windows TZID for a zone ID in the tz database, you have to resolve the long canonical Unicode time zone ID (e.g. "Asia/Culcutta") for the zone ID (e.g. "Asia/Kolkata"). For more details, see [Time Zone Identifiers](tr35.md#Time_Zone_Identifiers). 1612 1613**Note:** Not all Unicode time zones have equivalent Windows TZID mappings. Also, not all Windows TZIDs have equivalent Unicode time zones. For example, there is no equivalent Windows zone for Unicode time zone "Australia/Lord_Howe", and there is no equivalent Unicode time zone for Windows zone "E. Europe Standard Time" (as of CLDR 25 release). 1614 1615### <a name="Primary_Zones" href="#Primary_Zones">Primary Zones</a> 1616 1617```xml 1618<!ELEMENT primaryZones ( primaryZone* ) > 1619<!ELEMENT primaryZone ( #PCDATA ) > 1620<!ATTLIST primaryZone iso3166 NMTOKEN #REQUIRED > 1621``` 1622 1623This element is for data that is used to format a time zone’s generic location name. Each `<primaryZone>` element specifies the dominant zone for a region; this zone should use the region name for its generic location name even though there are other canonical zones available in the same region. For example, Asia/Shanghai is displayed as "China Time", instead of "Shanghai Time". Sample data: 1624 1625```xml 1626<primaryZones> 1627 <primaryZone iso3166="CL">America/Santiago</primaryZone> 1628 <primaryZone iso3166="CN">Asia/Shanghai</primaryZone> 1629 <primaryZone iso3166="DE">Europe/Berlin</primaryZone> 1630 … 1631``` 1632 1633This information was previously specified by the LDML `<singleCountries>` element under each locale’s `<timeZoneNames>` element. However, that approach had inheritance issues, and the data is not really locale-specific anyway. 1634 1635## <a name="Using_Time_Zone_Names" href="#Using_Time_Zone_Names">Using Time Zone Names</a> 1636 1637There are three main types of formats for zone identifiers: GMT, generic (wall time), and standard/daylight. Standard and daylight are equivalent to a particular offset from GMT, and can be represented by a GMT offset as a fallback. In general, this is not true for the generic format, which is used for picking timezones or for conveying a timezone for specifying a recurring time (such as a meeting in a calendar). For either purpose, a GMT offset would lose information. 1638 1639### <a name="Time_Zone_Format_Terminology" href="#Time_Zone_Format_Terminology">Time Zone Format Terminology</a> 1640 1641The following terminology defines more precisely the formats that are used. 1642 1643**Generic non-location format:** Reflects "wall time" (what is on a clock on the wall): used for recurring events, meetings, or anywhere people do not want to be overly specific. For example, "10 am Pacific Time" will be GMT-8 in the winter, and GMT-7 in the summer. 1644 1645* "Pacific Time" (long) 1646* "PT" (short) 1647 1648**Generic partial location format:** Reflects "wall time": used as a fallback format when the generic non-location format is not specific enough. 1649 1650* "Pacific Time (Canada)" (long) 1651* "PT (Whitehorse)" (short) 1652 1653**Generic location format:** Reflects "wall time": a primary function of this format type is to represent a time zone in a list or menu for user selection of time zone. It is also a fallback format when there is no translation for the generic non-location format. Times can also be organized hierarchically by country for easier lookup. 1654 1655+ France Time 1656+ Italy Time 1657+ Japan Time 1658+ United States 1659 + Chicago Time 1660 + Denver Time 1661 + Los Angeles Time 1662 + New York Time 1663+ United Kingdom Time 1664 1665Note: A generic location format is constructed by a part of time zone ID representing an exemplar city name or its country as the final fallback. However, there are Unicode time zones which are not associated with any locations, such as "Etc/GMT+5" and "PST8PDT". Although the date format pattern "VVVV" specifies the generic location format, but it displays localized GMT format for these. Some of these time zones observe daylight saving time, so the result (localized GMT format) may change depending on input date. For generating a list for user selection of time zone with format "VVVV", these non-location zones should be excluded. 1666 1667**Specific non-location format:** Reflects a specific standard or daylight time, which may or may not be the wall time. For example, "10 am Pacific Standard Time" will be GMT-8 in the winter and in the summer. 1668 1669* "Pacific Standard Time" (long) 1670* "PST" (short) 1671* "Pacific Daylight Time" (long) 1672* "PDT" (short) 1673 1674**Localized GMT format:** A constant, specific offset from GMT (or UTC), which may be in a translated form. There are two styles for this. The first is used when there is an explicit non-zero offset from GMT; this style is specified by the `<gmtFormat>` element and `<hourFormat>` element. The long format always uses 2-digit hours field and minutes field, with optional 2-digit seconds field. The short format is intended for the shortest representation and uses hour fields without leading zero, with optional 2-digit minutes and seconds fields. The digits used for hours, minutes and seconds fields in this format are the locale's default decimal digits: 1675 1676* "GMT+03:30" (long) 1677* "GMT+3:30" (short) 1678* "UTC-03.00" (long) 1679* "UTC-3" (short) 1680* "Гринуич+03:30" (long) 1681 1682Otherwise (when the offset from GMT is zero, referring to GMT itself) the style specified by the `<gmtZeroFormat>` element is used: 1683 1684* "GMT" 1685* "UTC" 1686* "Гринуич" 1687 1688**ISO 8601 time zone formats:** The formats based on the [[ISO 8601](tr35.md#ISO8601)] local time difference from UTC ("+" sign is used when local time offset is 0), or the UTC indicator ("Z" - only when the local time offset is 0 and the specifier X\* is used). The ISO 8601 basic format does not use a separator character between hours and minutes field, while the extended format uses colon (':') as the separator. The ISO 8601 basic format with hours and minutes fields is equivalent to RFC 822 zone format. 1689 1690* "-0800" (basic) 1691* "-08" (basic - short) 1692* "-08:00" (extended) 1693* "Z" (UTC) 1694 1695> Note: This specification extends the original ISO 8601 formats and some format specifiers append seconds field when necessary. 1696 1697**Raw Offset** - an offset from GMT that does not include any daylight savings behavior. For example, the raw offset for Pacific Time is -8, even though the _observed offset_ may be -8 or -7. 1698 1699**Metazone** - a collection of time zones that share the same behavior and same name during some period. They may differ in daylight behavior (whether they have it and when). 1700 1701For example, the TZID America/Cambridge_Bay is in the following metazones during various periods: 1702 1703```xml 1704<timezone type="America/Cambridge_Bay"> 1705 <usesMetazone to="1999-10-31 08:00" mzone="America_Mountain" /> 1706 <usesMetazone to="2000-10-29 07:00" from="1999-10-31 08:00" mzone="America_Central" /> 1707 <usesMetazone to="2000-11-05 05:00" from="2000-10-29 07:00" mzone="America_Eastern" /> 1708 <usesMetazone to="2001-04-01 09:00" from="2000-11-05 05:00" mzone="America_Central" /> 1709 <usesMetazone from="2001-04-01 09:00" mzone="America_Mountain" /> 1710</timezone> 1711``` 1712 1713Zones may join or leave a metazone over time. The data relating between zones and metazones is in the supplemental information; the locale data is restricted to translations of metazones and zones. 1714 1715> **Invariants:** 1716> 1717> * At any given point in time, each zone belongs to no more than one metazone. 1718> * At a given point in time, a zone may not belong to any metazones. 1719> * _Except for daylight savings_, at any given time, all zones in a metazone have the same offset at that time. 1720 1721**Golden Zone** - the TZDB zone that exemplifies a metazone. For example, America/New_York is the golden zone for the metazone America_Eastern: 1722 1723```xml 1724<mapZone other="America_Eastern" territory="001" type="America/New_York"/> 1725``` 1726 1727> **Invariants:** 1728> 1729> * The golden zones are those in mapZone supplemental data under the territory "001". 1730> * Every metazone has exactly one golden zone. 1731> * Each zone has at most one metazone for which it is golden. 1732> * The golden zone is in that metazone during the entire life of the metazone. (The raw offset of the golden zone may change over time.) 1733> * Each other zone must have the same raw offset as the golden zone, for the entire period that it is in the metazone. (It might not have the same offset when daylight savings is in effect.) 1734> * A golden zone in mapTimezones must have reverse mapping in metazoneInfo. 1735> * A single time zone can be a golden zone of multiple different metazones if any two of them are never active at a same time. 1736 1737**Preferred Zone** - for a given TZID, the "best" zone out of a metazone for a given country or language. 1738 1739> **Invariants:** 1740> 1741> * The preferred zone for a given country XX are those in mapZone supplemental data under the territory XX. 1742> * Every metazone has at most one preferred zone for a given territory XX. 1743> * Each zone has at most one metazone for which it is preferred for a territory XX. 1744> * The preferred zone for a given metazone and territory XX is in a metazone M during any time when any other zone in XX is also in M 1745> * A preferred zone in mapTimezones must have reverse mapping in metazoneInfo 1746 1747For example, for America_Pacific the preferred zone for Canada is America/Vancouver, and the preferred zone for Mexico is America/Tijuana. The golden zone is America/Los_Angeles, which is also the preferred zone for any other country. 1748 1749```xml 1750<mapZone other="America_Pacific" territory="001" type="America/Los_Angeles" /> 1751<mapZone other="America_Pacific" territory="CA" type="America/Vancouver" /> 1752<mapZone other="America_Pacific" territory="MX" type="America/Tijuana" /> 1753``` 1754 1755**<a name="fallbackFormat" href="#fallbackFormat">fallbackFormat:</a>** a formatting string such as "{1} ({0})", where {1} is the metazone, and {0} is the country or city. 1756 1757**regionFormat:** a formatting string such as "{0} Time", where {0} is the country or city. 1758 1759### <a name="Time_Zone_Goals" href="#Time_Zone_Goals">Goals</a> 1760 1761The timezones are designed so that: 1762 1763> For any given locale, every _time_ round trips with all patterns (but not necessarily every timezone). That is, given a time and a format pattern with a zone string, you can format, then parse, and get back the same time. 1764> 1765> Note that the round-tripping is not just important for parsing; it provides for formatting dates and times in an unambiguous way for users. It is also important for testing. 1766> 1767> There are exceptions to the above for transition times. 1768> 1769> * With generic format, time zone ID or exemplar city name, during the transition when the local time maps to two possible GMT times. 1770> * For example, Java works as follows, favoring standard time: 1771> * Source: Sun Nov 04 01:30:00 PDT 2007 1772> * => Formatted: "Sunday, November 4, 2007 1:30:00 AM" 1773> * => Parsed: Sun Nov 04 01:30:00 PST 2007 1774> * When the timezone changes offset, say from GMT+4 to GMT+5, there can also be a gap. 1775> 1776> The V/VV/VVV/VVVV format will roundtrip not only the time, but the canonical timezone. 1777 1778When the data for a given format is not available, a fallback format is used. The fallback order is given in the following by a list. 1779 17801. **Specifics** 1781 * z - [short form] specific non-location 1782 * falling back to short localized GMT 1783 * zzzz - [long form] specific non-location 1784 * falling back to long localized GMT 1785 * Z/ZZZZZ/X+/x+ - ISO 8601 formats (no fallback necessary) 1786 * ZZZZ/O+ - Localized GMT formats (no fallback necessary) 1787 17882. **Generics** 1789 * v - [short form] generic non-location 1790 _(however, the rules are more complicated, see #5 below)_ 1791 * falling back to generic location 1792 * falling back to short localized GMT 1793 * vvvv - [long form] generic non-location 1794 _(however, the rules are more complicated, see #5 below)_ 1795 * falling back to generic location 1796 * falling back to long localized GMT 1797 * V - short time zone ID 1798 * falling back to the special ID "unk" (Unknown) 1799 * VV - long time zone ID (no fallback necessary, because this is the input) 1800 * VVV - exemplar city 1801 * falling back to the localized exemplar city for the unknown zone (Etc/Unknown), for example "Unknown City" for English 1802 * VVVV - generic location 1803 * falling back to long localized GMT 1804 1805The following process is used for the particular formats, with the fallback rules as above. 1806 1807Some of the examples are drawn from real data, while others are for illustration. For illustration the region format is "Hora de {0}". The fallback format in the examples is "{1} ({0})", which is what is in root. 1808 18091. In **all** cases, first canonicalize the _TZ_ ID according to the Unicode Locale Extension _type_ mapping data (see [Time Zone Identifiers](tr35.md#Time_Zone_Identifiers) for more details). Use that canonical TZID in each of the following steps. 1810 * America/Atka → America/Adak 1811 * Australia/ACT → Australia/Sydney 1812 18132. For the localized GMT format, use the gmtFormat (such as "GMT{0}" or "HMG{0}") with the hourFormat (such as "+HH:mm;-HH:mm" or "+HH.mm;-HH.mm"). 1814 * America/Los_Angeles → "GMT-08:00" // standard time 1815 * America/Los_Angeles → "HMG-07:00" // daylight time 1816 * Etc/GMT+3 → "GMT-03.00" // note that _TZ_ TZIDs have inverse polarity! 1817 1818 **Note:** The digits should be whatever are appropriate for the locale used to format the time zone, not necessarily from the western digits, 0..9. For example, they might be from ०..९. 1819 18203. For ISO 8601 time zone format return the results according to the ISO 8601 specification. 1821 * America/Los_Angeles → 1822 * "-08" ("X","x") 1823 * "-0800" ("Z","XX","XXXX","xx","xxxx") 1824 * "-08:00" ("ZZZZZ","XXX","XXXXX","xxx","xxxxx") 1825 * Etc/GMT → 1826 * "Z" ("ZZZZZ", "X", "XX", "XXX", "XXXX", "XXXXX") 1827 * "+00" ("x") 1828 * "+0000" ("Z", "xx", "xxxx") 1829 * "+00:00" ("xxx", "xxxxx") 1830 1831 **Note:** The digits in this case are always from the western digits, 0..9. 1832 18334. For the non-location formats (generic or specific): 1834 1. if there is an explicit translation for the TZID in `<timeZoneNames>` according to type (generic, standard, or daylight) in the resolved locale, return it. 1835 1. If the requested type is not available, but another type is, and there is a **Type Fallback** then return that other type. 1836 * Examples: 1837 * America/Los_Angeles → // generic 1838 * America/Los_Angeles → "アメリカ太平洋標準時" // standard 1839 * America/Los_Angeles → "Yhdysvaltain Tyynenmeren kesäaika" // daylight 1840 * Europe/Dublin → "Am Samhraidh na hÉireann" // daylight 1841 * Note: This translation may not at all be literal: it would be what is most recognizable for people using the target language. 1842 2. Otherwise, get the requested metazone format according to type (generic, standard, daylight). 1843 1. If the requested type is not available, but another type is, get the format according to **Type Fallback**. 1844 2. If there is no format for the type, fall back. 1845 3. Otherwise do the following: 1846 1. Get the country for the current locale. If there is none, use the most likely country based on the likelySubtags data. If there is none, use “001”. 1847 2. Get the preferred zone for the metazone for the country; if there is none for the country, use the preferred zone for the metazone for “001”. 1848 3. If that preferred zone is the same as the requested zone, use the metazone format. For example, "Pacific Time" for Vancouver if the locale is en_CA, or for Los Angeles if locale is en_US. 1849 4. Otherwise, if the zone is the preferred zone for its country but not for the country of the locale, use the metazone format + country in the _fallbackFormat_. 1850 5. Otherwise, use the metazone format + city in the _fallbackFormat_. 1851 * Examples: 1852 * "Pacific Time (Canada)" // for the zone Vancouver in the locale en_MX. 1853 * "Mountain Time (Phoenix)" 1854 * "Pacific Time (Whitehorse)" 18555. For the generic location format: 1856 1. From the TZDB get the country code for the zone, and determine whether there is only one timezone in the country. If there is only one timezone or if the zone id is in the `<primaryZones>` list, format the country name with the _regionFormat_, and return it. 1857 * Examples: 1858 * Europe/Rome → IT → "Italy Time" // for English 1859 * Asia/Shanghai → CN → "China Time" // Asia/Shanghai is the _primaryZone_ for China 1860 * Africa/Monrovia → LR → "Hora de Liberja" 1861 * America/Havana → CU → "Hora de CU" // if CU is not localized 1862 2. Otherwise format the exemplar city with the _regionFormat_, and return it. 1863 1. America/Buenos_Aires → "Buenos Aires Time" 1864 1865> **Note:** If a language does require grammatical changes when composing strings, then the _regionFormat_ should either use a neutral format such as "Heure: {0}", or put all exceptional cases in explicitly translated strings. 1866 1867**Type Fallback** 1868 1869When a specified type (generic, standard, daylight) does not exist: 1870 18711. If the daylight type does not exist, then the metazone doesn’t require daylight support. For all three types: 1872 1. If the generic type exists, use it. 1873 2. Otherwise if the standard type exists, use it. 18742. Otherwise if the generic type is needed, but not available, and the offset and daylight offset do not change within 184 day +/- interval around the exact formatted time, use the standard type. 1875 1. Example: "Mountain Standard Time" for Phoenix 1876 2. Note: 184 is the smallest number that is at least 6 months AND the smallest number that is more than 1/2 year (Gregorian). 1877 1878**Composition** 1879 1880In composing the metazone + city or country: 1881 18821. Use the _fallbackFormat_ "{1} ({0})", where: 1883 * {1} will be the metazone 1884 * {0} will be a qualifier (city or country) 1885 * Example: 1886 * metazone = Pacific Time 1887 * city = Phoenix 1888 * → "Pacific Time (Phoenix)" 18892. If the localized country name is not available, use the code: 1890 * CU (country code) → "CU" _// no localized country name for Cuba_ 18913. If the localized exemplar city is not available, use as the exemplar city the last field of the raw TZID, stripping off the prefix and turning _ into space. 1892 * America/Los_Angeles → "Los Angeles" _// no localized exemplar city_ 1893 1894**Note:** As with the _regionFormat_, exceptional cases need to be explicitly translated. 1895 1896### <a name="Time_Zone_Parsing" href="#Time_Zone_Parsing">Parsing</a> 1897 1898In parsing, an implementation will be able to either determine the zone id, or a simple offset from GMT for anything formatting according to the above process. 1899 1900The following is a sample process for how this might be done. It is only a sample; implementations may use different methods for parsing. 1901 1902The sample describes the parsing of a zone as if it were an isolated string. In implementations, the zone may be mixed in with other data (like the time), so the parsing actually has to look for the longest match, and then allow the remaining text to be parsed for other content. That requires certain adaptions to the following process. 1903 19041. Start with a string S. 19052. If S matches ISO 8601 time zone format, return it. 1906 * For example, "-0800" (RFC 822), "-08:00" (ISO 8601) => Etc/GMT+8 19073. If S matches the English or localized GMT format, return the corresponding TZID 1908 * Matching should be lenient. Thus allow for the number formats like: 03, 3, 330, 3:30, 33045 or 3:30:45. Allow +, -, or nothing. Allow spaces after GMT, +/-, and before number. Allow non-Latin numbers. Allow UTC or UT (per RFC 788) as synonyms for GMT ("GMT", "UT", "UTC" are global formats, always allowed in parsing regardless of locale). 1909 * For example, "GMT+3" or "UT+3" or "HPG+3" => Etc/GMT-3 1910 * When parsing, the absence of a numeric offset should be interpreted as offset 0, whether in localized or global formats. For example, "GMT" or "UT" or "UTC+0" or "HPG" => Etc/GMT 19114. If S matches the fallback format, extract P = {0} [ie, the part in parens in the root format] and N = {1}. 1912 If S does not match, set P = "" and N = S. 1913 If N matches the region format, then M = {0} from that format, otherwise M = N. 1914 * For example, "United States (Los Angeles) Time" => N = "United States Time", M = "United States", P = "Los Angeles". 1915 * For example, "United States Time" => N = "United States Time", M = "United States", P = "". 1916 * For example, "United States" => N = M = "United States", P = "". 19175. If P, N, or M is a localized country, set C to that value. If C has only one zone, return it. 1918 * For example, "Italy Time (xxx)" or "xxx (Italy)" => Europe/Rome 1919 * For example, "xxx (Canada)" or "Canada Time (xxx)" => Sets C = CA and continues 19206. If P is a localized exemplar city name (and not metazone), return it. 1921 * For example, "xxxx (Phoenix)" or "Phoenix (xxx)" => America/Phoenix 19227. If N, or M is a localized time zone name (and not metazone), return it. 1923 * For example, "Pacific Standard Time (xxx)" => "America/Los_Angeles" // this is only if "Pacific Standard Time" is not a metazone localization. 19248. If N or M is a localized metazone 1925 * If it corresponds to only one TZID, return it. 1926 * If C is set, look up the Metazone + Country => TZID mapping, and return that value if it exists 1927 * Get the locale's language, and get the default country from that. Look up the Metazone + DefaultCountry => TZID mapping, and return that value if it exists. 1928 * Otherwise, look up Metazone + 001 => TZID and return it (that will always exist) 19299. If you get this far, return an error. 1930 1931> **Note:** This CLDR date parsing recommendation does not fully handle all RFC 788 date/time formats, nor is it intended to. 1932 1933Parsing can be more lenient than the above, allowing for different spacing, punctuation, or other variation. A stricter parse would check for consistency between the xxx portions above and the rest, so "Pacific Standard Time (India)" would give an error. 1934 1935Using this process, a correct parse will roundtrip the location format (VVVV) back to the canonical zoneid. 1936 1937 * Australia/ACT → Australia/Sydney → “Sydney (Australia)” → Australia/Sydney 1938 1939The GMT formats (Z and ZZZZ) will return back an offset, and thus lose the original canonical zone id. 1940 1941 * Australia/ACT → Australia/Sydney → "GMT+11:00" → GMT+11 1942 1943The daylight and standard time formats, and the non-location formats (z, zzzz, v, and vvvv) may either roundtrip back to the original canonical zone id, to a zone in the same metazone that time, or to just an offset, depending on the available translation data. Thus: 1944 1945 * Australia/ACT → Australia/Sydney → "GMT+11:00" → GMT+11 1946 * PST8PDT → America/Los_Angeles → “PST” → America/Los_Angeles 1947 * America/Vancouver → “Pacific Time (Canada)” → America/Vancouver 1948 1949## <a name="Date_Format_Patterns" href="#Date_Format_Patterns">Date Format Patterns</a> 1950 1951A date pattern is a character string consisting of two types of elements: 1952 1953* _Pattern fields_, which repeat a specific _pattern character_ one or more times. These fields are replaced with date and time data from a calendar when formatting, or used to generate data for a calendar when parsing. Currently, A..Z and a..z are reserved for use as pattern characters (unless they are quoted, see next item). The pattern characters currently defined, and the meaning of different fields lengths for then, are listed in the Date Field Symbol Table below. 1954* Literal text, which is output as-is when formatting, and must closely match when parsing. Literal text can include: 1955 * Any characters other than A..Z and a..z, including spaces and punctuation. 1956 * Any text between single vertical quotes ('xxxx'), which may include A..Z and a..z as literal text. 1957 * Two adjacent single vertical quotes (''), which represent a literal single quote, either inside or outside quoted text. 1958 1959The following are examples: 1960 1961###### Table: <a name="Date_Format_Pattern_Examples" href="#Date_Format_Pattern_Examples">Date Format Pattern Examples</a> 1962 1963| Pattern | Result (in a particular locale) | 1964| ------- | ------------------------------- | 1965| yyyy.MM.dd G 'at' HH:mm:ss zzz | 1996.07.10 AD at 15:08:56 PDT | 1966| EEE, MMM d, ''yy | Wed, July 10, '96 | 1967| h:mm a | 12:08 PM | 1968| hh 'o''clock' a, zzzz | 12 o'clock PM, Pacific Daylight Time | 1969| K:mm a, z | 0:00 PM, PST | 1970| yyyyy.MMMM.dd GGG hh:mm aaa | 01996.July.10 AD 12:08 PM | 1971 1972_When parsing using a pattern, a lenient parse should be used; see [Parsing Dates and Times](#Parsing_Dates_Times)._ 1973 1974```xml 1975<!ATTLIST pattern numbers CDATA #IMPLIED > 1976``` 1977 1978The `numbers` attribute is used to indicate that numeric quantities in the pattern are to be rendered using a numbering system other than the default numbering system defined for the given locale. The attribute can be in one of two forms. If the alternate numbering system is intended to apply to ALL numeric quantities in the pattern, then simply use the numbering system ID as found in [Numbering Systems](tr35-numbers.md#Numbering_Systems). To apply the alternate numbering system only to a single field, the syntax `<letter>=<numberingSystem>` can be used one or more times, separated by semicolons. 1979 1980Examples: 1981 1982```xml 1983<pattern numbers="hebr">dd/mm/yyyy</pattern> 1984<!-- Use Hebrew numerals to represent numbers in the Hebrew calendar, where "latn" numbering system is the default --> 1985 1986<pattern numbers="y=hebr">dd/mm/yyyy</pattern> 1987<!-- Same as above, except that ONLY the year value would be rendered in Hebrew --> 1988 1989<pattern numbers="d=thai;m=hans;y=deva">dd/mm/yyyy</pattern> 1990<!-- Illustrates use of multiple numbering systems for a single pattern. --> 1991``` 1992 1993**Pattern fields and the Date Field Symbol Table** 1994 1995The Date Field Symbol Table below shows the pattern characters (Sym.) and associated fields used in date patterns. The length of the pattern field is related to the length and style used to format the data item. For numeric-only fields, the field length typically indicates the minimum number of digits that should be used to display the value (zero-padding as necessary). As an example using pattern character ‘H’ for hour (24-hour cycle) and values 5 and 11, a field “H” should produce formatted results “5” and “11” while a field “HH” should produce formatted results “05” and “11”. For alphanumeric fields (such as months) and alphabetic-only fields (such as era names), the relationship between field length and formatted result may be more complex. Typically this is as follows: 1996 1997<!-- HTML: spanned rows, spanned columns --> 1998 <table> 1999 <tr><th>Pattern field length</th><th>Typical style, alphanumeric item</th><th>Typical style, alpha-only item</th></tr> 2000 <tr><td>1</td><td>Numeric, 1-2 digits (e.g. M)</td><td rowspan="3">Abbreviated (e.g. E, EE, EEE)</td></tr> 2001 <tr><td>2</td><td>Numeric, 2 digits (e.g. MM)</td></tr> 2002 <tr><td>3</td><td>Abbreviated (e.g. MMM)</td></tr> 2003 <tr><td>4</td><td colspan="2">Wide / Long / Full (e.g. MMMM, EEEE)</td></tr> 2004 <tr><td>5</td><td colspan="2">Narrow (e.g. MMMMM, EEEEE)<br/>(The counter-intuitive use of 5 letters for this is forced by backwards compatibility)</td></tr> 2005 <tr><td>>16</td><td colspan="2">Private Use<br/>(Reserved for use by implementations using CLDR; will never be otherwise used by CLDR.)</td></tr> 2006</table> 2007 2008Notes for the table below: 2009 2010* Any sequence of pattern characters other than those listed below is invalid. Invalid pattern fields should be handled for formatting and parsing as described in [Handling Invalid Patterns](tr35.md#Invalid_Patterns). 2011* The examples in the table below are merely illustrative and may not reflect current actual data. 2012 2013###### Table: <a name="Date_Field_Symbol_Table" href="#Date_Field_Symbol_Table">Date Field Symbol Table</a> 2014 2015<!-- HTML: spanned rows, spanned columns, vertical header cells --> 2016<table><tbody> 2017<tr><th>Field<br/>Type</th><th>Sym.</th><th>Field<br/>Patterns</th><th>Examples</th><th colspan="2">Description</th></tr> 2018 2019<!-- == == == ERA == == == --> 2020<tr><th rowspan="3"><a name="dfst-era" href="#dfst-era">era</a></th><td rowspan="3">G</td><td>G..GGG</td><td>AD<br/>[variant: CE]</td><td>Abbreviated</td><td rowspan="3">Era name. Era string for the current date.</td></tr> 2021 <tr><td>GGGG</td><td>Anno Domini<br/>[variant: Common Era]</td><td>Wide</td></tr> 2022 <tr><td>GGGGG</td><td>A</td><td>Narrow</td></tr> 2023 2024<!-- == == == YEAR == == == --> 2025<tr><th rowspan="15"><a name="dfst-year" href="#dfst-year">year</a><a name="Year_Length_Examples"></a></th><td rowspan="5">y</td><td>y</td><td>2, 20, 201, 2017, 20173</td> 2026 <td rowspan="5" colspan="2">Calendar year (numeric). In most cases the length of the y field specifies the minimum number of digits to display, zero-padded as necessary; more digits will be displayed if needed to show the full year. 2027 However, “yy” requests just the two low-order digits of the year, zero-padded as necessary. For most use cases, “y” or “yy” should be adequate.</td></tr> 2028 <tr><td>yy</td><td>02, 20, 01, 17, 73</td></tr> 2029 <tr><td>yyy</td><td>002, 020, 201, 2017, 20173</td></tr> 2030 <tr><td>yyyy</td><td>0002, 0020, 0201, 2017, 20173</td></tr> 2031 <tr><td>yyyyy+</td><td>...</td></tr> 2032 <!-- Y --> 2033 <tr><td rowspan="5">Y</td><td>Y</td><td>2, 20, 201, 2017, 20173</td> 2034 <td rowspan="5" colspan="2">Year in “Week of Year” based calendars in which the year transition occurs on a week boundary; may differ from calendar year ‘y’ near a year transition. 2035 This numeric year designation is used in conjunction with pattern character ‘w’ in the ISO year-week calendar as defined by ISO 8601, but can be used in non-Gregorian based calendar systems where week date processing is desired. 2036 The field length is interpreted in the same was as for ‘y’; that is, “yy” specifies use of the two low-order year digits, while any other field length specifies a minimum number of digits to display.</td></tr> 2037 <tr><td>YY</td><td>02, 20, 01, 17, 73</td></tr> 2038 <tr><td>YYY</td><td>002, 020, 201, 2017, 20173</td></tr> 2039 <tr><td>YYYY</td><td>0002, 0020, 0201, 2017, 20173</td></tr> 2040 <tr><td>YYYYY+</td><td>...</td></tr> 2041 <!-- u --> 2042 <tr><td>u</td><td>u+</td><td>4601</td> 2043 <td colspan="2">Extended year (numeric). This is a single number designating the year of this calendar system, encompassing all supra-year fields. 2044 For example, for the Julian calendar system, year numbers are positive, with an era of BCE or CE. An extended year value for the Julian calendar system assigns positive values to CE years and negative values to BCE years, with 1 BCE being year 0. 2045 For ‘u’, all field lengths specify a minimum number of digits; there is no special interpretation for “uu”.</td></tr> 2046 <!-- U --> 2047 <tr><td rowspan="3">U</td><td>U..UUU</td><td>甲子</td><td>Abbreviated</td> 2048 <td rowspan="3">Cyclic year name. Calendars such as the Chinese lunar calendar (and related calendars) and the Hindu calendars use 60-year cycles of year names. 2049 If the calendar does not provide cyclic year name data, or if the year value to be formatted is out of the range of years for which cyclic name data is provided, then numeric formatting is used (behaves like 'y').<br/> 2050 Currently the data only provides abbreviated names, which will be used for all requested name widths.</td></tr> 2051 <tr><td>UUUU</td><td>甲子 [for now]</td><td>Wide</td></tr> 2052 <tr><td>UUUUU</td><td>甲子 [for now]</td><td>Narrow</td></tr> 2053 <!-- r --> 2054 <tr><td>r</td><td>r+</td><td>2017</td> 2055 <td colspan="2">Related Gregorian year (numeric). 2056 For non-Gregorian calendars, this corresponds to the extended Gregorian year in which the calendar’s year begins. 2057 Related Gregorian years are often displayed, for example, when formatting dates in the Japanese calendar — e.g. “2012(平成24)年1月15日” — or in the Chinese calendar — e.g. “2012壬辰年腊月初四”. 2058 The related Gregorian year is usually displayed using the "latn" numbering system, regardless of what numbering systems may be used for other parts of the formatted date. 2059 If the calendar’s year is linked to the solar year (perhaps using leap months), then for that calendar the ‘r’ year will always be at a fixed offset from the ‘u’ year. 2060 For the Gregorian calendar, the ‘r’ year is the same as the ‘u’ year. For ‘r’, all field lengths specify a minimum number of digits; there is no special interpretation for “rr”.</td></tr> 2061 2062<!-- == == == QUARTER == == == --> 2063<tr><th rowspan="10"><a name="dfst-quarter" id="dfst-quarter" href="#dfst-quarter">quarter</a></th><td rowspan="5">Q</td><td>Q</td><td>2</td><td>Numeric: 1 digit</td><td rowspan="5">Quarter number/name.</td></tr> 2064 <tr><td>QQ</td><td>02</td><td>Numeric: 2 digits + zero pad</td></tr> 2065 <tr><td>QQQ</td><td>Q2</td><td>Abbreviated</td></tr> 2066 <tr><td>QQQQ</td><td>2nd quarter</td><td>Wide</td></tr> 2067 <tr><td>QQQQQ</td><td>2</td><td>Narrow</td></tr> 2068 <!-- q --> 2069 <tr><td rowspan="5">q</td><td>q</td><td>2</td><td>Numeric: 1 digit</td><td rowspan="5"><b>Stand-Alone</b> Quarter number/name.</td></tr> 2070 <tr><td>qq</td><td>02</td><td>Numeric: 2 digits + zero pad</td></tr> 2071 <tr><td>qqq</td><td>Q2</td><td>Abbreviated</td></tr> 2072 <tr><td>qqqq</td><td>2nd quarter</td><td>Wide</td></tr> 2073 <tr><td>qqqqq</td><td>2</td><td>Narrow</td></tr> 2074 2075<!-- == == == MONTH == == == --> 2076<tr><th rowspan="11"><a name="dfst-month" id="dfst-month" href="#dfst-month">month</a></th><td rowspan="5">M</td><td>M</td><td>9, 12</td><td>Numeric: minimum digits</td><td rowspan="5"><b>Format</b> style month number/name: The format style name is an additional form of the month name (besides the stand-alone style) that can be used in contexts where it is different than the stand-alone form. For example, depending on the language, patterns that combine month with day-of month (e.g. "d MMMM") may require the month to be in genitive form. See discussion of <a href="#months_days_quarters_eras">month element</a>. If a separate form is not needed, the format and stand-alone forms can be the same.</td></tr> 2077 <tr><td>MM</td><td>09, 12</td><td>Numeric: 2 digits, zero pad if needed</td></tr> 2078 <tr><td>MMM</td><td>Sep</td><td>Abbreviated</td></tr> 2079 <tr><td>MMMM</td><td>September</td><td>Wide</td></tr> 2080 <tr><td>MMMMM</td><td>S</td><td>Narrow</td></tr> 2081 <!-- L --> 2082 <tr><td rowspan="5">L</td><td>L</td><td>9, 12</td><td>Numeric: minimum digits</td><td rowspan="5"><b>Stand-Alone</b> month number/name: For use when the month is displayed by itself, and in any other date pattern (e.g. just month and year, e.g. "LLLL y") that shares the same form of the month name. For month names, this is typically the nominative form. See discussion of <a href="#months_days_quarters_eras">month element</a>.</td></tr> 2083 <tr><td>LL</td><td>09, 12</td><td>Numeric: 2 digits, zero pad if needed</td></tr> 2084 <tr><td>LLL</td><td>Sep</td><td>Abbreviated</td></tr> 2085 <tr><td>LLLL</td><td>September</td><td>Wide</td></tr> 2086 <tr><td>LLLLL</td><td>S</td><td>Narrow</td></tr> 2087 <!-- l --> 2088 <tr><td>l</td><td>l</td><td>[nothing]</td> 2089 <td colspan="2">This pattern character is deprecated, and should be ignored in patterns. 2090 It was originally intended to be used in combination with M to indicate placement of the symbol for leap month in the Chinese calendar. 2091 Placement of that marker is now specified using locale-specific <monthPatterns> data, and formatting and parsing of that marker should be handled as part of supporting the regular M and L pattern characters.</td></tr> 2092 2093<!-- == == == WEEK == == == --> 2094<tr><th rowspan="3"><a name="dfst-week" id="dfst-week" href="#dfst-week">week</a></th><td rowspan="2">w</td><td>w</td><td>8, 27</td><td>Numeric: minimum digits</td><td rowspan="2">Week of Year (numeric). When used in a pattern with year, use ‘Y’ for the year field instead of ‘y’.</td></tr> 2095 <tr><td>ww</td><td>08, 27</td><td>Numeric: 2 digits, zero pad if needed</td></tr> 2096 <!-- W --> 2097 <tr><td>W</td><td>W</td><td>3</td><td>Numeric: 1 digit</td><td>Week of Month (numeric)</td></tr> 2098 2099<!-- == == == DAY == == == --> 2100<tr><th rowspan="5"><a name="dfst-day" id="dfst-day" href="#dfst-day">day</a></th><td rowspan="2">d</td><td>d</td><td>1</td><td>Numeric: minimum digits</td><td rowspan="2">Day of month (numeric).</td></tr> 2101 <tr><td>dd</td><td>01</td><td>Numeric: 2 digits, zero pad if needed</td></tr> 2102 <tr><td>D</td><td>D...DDD</td><td>345</td><td colspan="2">Day of year (numeric). The field length specifies the minimum number of digits, with zero-padding as necessary.</td></tr> 2103 <tr><td>F</td><td>F</td><td>2</td><td colspan="2">Day of Week in Month (numeric). The example is for the 2nd Wed in July</td></tr> 2104 <tr><td>g</td><td>g+</td><td>2451334</td> 2105 <td colspan="2">Modified Julian day (numeric). 2106 This is different from the conventional Julian day number in two regards. 2107 First, it demarcates days at local zone midnight, rather than noon GMT. 2108 Second, it is a local number; that is, it depends on the local time zone. 2109 It can be thought of as a single number that encompasses all the date-related fields. 2110 The field length specifies the minimum number of digits, with zero-padding as necessary.</td></tr> 2111 2112<!-- == == == WEEKDAY == == == --> 2113<tr><th rowspan="15"><a name="dfst-weekday" id="dfst-weekday" href="#dfst-weekday">week<br/>day</a></th><td rowspan="4">E</td><td>E..EEE</td><td>Tue</td><td>Abbreviated</td><td rowspan="4">Day of week name, format style.</td></tr> 2114 <tr><td>EEEE</td><td>Tuesday</td><td>Wide</td></tr> 2115 <tr><td>EEEEE</td><td>T</td><td>Narrow</td></tr> 2116 <tr><td>EEEEEE</td><td>Tu</td><td>Short</td></tr> 2117 <!-- e --> 2118 <tr><td rowspan="6">e</td><td>e</td><td>2</td><td>Numeric: 1 digit</td> 2119 <td rowspan="6">Local day of week number/name, format style. 2120 Same as E except adds a numeric value that will depend on the local starting day of the week. 2121 For this example, Monday is the first day of the week.</td></tr> 2122 <tr><td>ee</td><td>02</td><td>Numeric: 2 digits + zero pad</td></tr> 2123 <tr><td>eee</td><td>Tue</td><td>Abbreviated</td></tr> 2124 <tr><td>eeee</td><td>Tuesday</td><td>Wide</td></tr> 2125 <tr><td>eeeee</td><td>T</td><td>Narrow</td></tr> 2126 <tr><td>eeeeee</td><td>Tu</td><td>Short</td></tr> 2127 <!-- c --> 2128 <tr><td rowspan="5">c</td><td>c..cc</td><td>2</td><td>Numeric: 1 digit</td><td rowspan="5"><b>Stand-Alone</b> local day of week number/name.</td></tr> 2129 <tr><td>ccc</td><td>Tue</td><td>Abbreviated</td></tr> 2130 <tr><td>cccc</td><td>Tuesday</td><td>Wide</td></tr> 2131 <tr><td>ccccc</td><td>T</td><td>Narrow</td></tr> 2132 <tr><td>cccccc</td><td>Tu</td><td>Short</td></tr> 2133 2134<!-- == == == PERIOD == == == --> 2135<tr><th rowspan="9"><a name="dfst-period" id="dfst-period" href="#dfst-period">period</a></th><td rowspan="3">a</td><td>a..aaa</td><td>am. [e.g. 12 am.]</td><td>Abbreviated</td> 2136 <td rowspan="3"><strong>AM, PM<br/></strong>May be upper or lowercase depending on the locale and other options. 2137 The wide form may be the same as the short form if the “real” long form (eg <em>ante meridiem</em>) is not customarily used. 2138 The narrow form must be unique, unlike some other fields. 2139 See also <a href="#Parsing_Dates_Times">Parsing Dates and Times</a>.</td></tr> 2140 <tr><td>aaaa</td><td>am. [e.g. 12 am.]</td><td>Wide</td></tr> 2141 <tr><td>aaaaa</td><td>a [e.g. 12a]</td><td>Narrow</td></tr> 2142 <!-- b --> 2143 <tr><td rowspan="3">b</td><td>b..bbb</td><td>mid. [e.g. 12 mid.]</td><td>Abbreviated</td> 2144 <td rowspan="3"><strong>am, pm, noon, midnight</strong><br/>May be upper or lowercase depending on the locale and other options. 2145 If the locale doesn't have the notion of a unique "noon" = 12:00, then the PM form may be substituted. 2146 Similarly for "midnight" = 00:00 and the AM form. 2147 The narrow form must be unique, unlike some other fields.</td></tr> 2148 <tr><td>bbbb</td><td>midnight<br/>[e.g. 12 midnight]</td><td>Wide</td></tr> 2149 <tr><td>bbbbb</td><td>md [e.g. 12 md]</td><td>Narrow</td></tr> 2150 <!-- B --> 2151 <tr><td rowspan="3">B</td><td>B..BBB</td><td>at night<br/>[e.g. 3:00 at night]</td><td>Abbreviated</td> 2152 <td rowspan="3"><strong>flexible day periods</strong><br/> 2153 May be upper or lowercase depending on the locale and other options. 2154 Often there is only one width that is customarily used.</td></tr> 2155 <tr><td>BBBB</td><td>at night<br/>[e.g. 3:00 at night]</td><td>Wide</td></tr> 2156 <tr><td>BBBBB</td><td>at night<br/>[e.g. 3:00 at night]</td><td>Narrow</td></tr> 2157 2158<!-- == == == HOUR == == == --> 2159<tr><th rowspan="22"><a name="dfst-hour" id="dfst-hour" href="#dfst-hour">hour</a></th><td rowspan="2">h</td><td>h</td><td>1, 12</td><td>Numeric: minimum digits</td> 2160 <td rowspan="2">Hour [1-12]. When used in skeleton data or in a skeleton passed in an API for flexible date pattern generation, it should match the 12-hour-cycle format preferred by the locale (h or K); it should not match a 24-hour-cycle format (H or k).</td></tr> 2161<tr><td>hh</td><td>01, 12</td><td>Numeric: 2 digits, zero pad if needed</td></tr> 2162 <!-- H --> 2163 <tr><td rowspan="2">H</td><td>H</td><td>0, 23</td><td>Numeric: minimum digits</td> 2164 <td rowspan="2">Hour [0-23]. When used in skeleton data or in a skeleton passed in an API for flexible date pattern generation, it should match the 24-hour-cycle format preferred by the locale (H or k); it should not match a 12-hour-cycle format (h or K).</td></tr> 2165 <tr><td>HH</td><td>00, 23</td><td>Numeric: 2 digits, zero pad if needed</td></tr> 2166 <!-- K --> 2167 <tr><td rowspan="2">K</td><td>K</td><td>0, 11</td><td>Numeric: minimum digits</td> 2168 <td rowspan="2">Hour [0-11]. When used in a skeleton, only matches K or h, see above.</td></tr> 2169 <tr><td>KK</td><td>00, 11</td><td>Numeric: 2 digits, zero pad if needed</td></tr> 2170 <!-- k --> 2171 <tr><td rowspan="2">k</td><td>k</td><td>1, 24</td><td>Numeric: minimum digits</td> 2172 <td rowspan="2">Hour [1-24]. When used in a skeleton, only matches k or H, see above.</td></tr> 2173 <tr><td>kk</td><td>01, 24</td><td>Numeric: 2 digits, zero pad if needed</td></tr> 2174 <!-- j --> 2175 <tr><td rowspan="6">j</td><td>j</td><td>8<br/>8 AM<br/>13<br/>1 PM</td><td>Numeric hour (minimum digits), abbreviated dayPeriod if used</td> 2176 <td rowspan="6"><em><strong>Input skeleton symbol</strong></em><br/> 2177 It must not occur in pattern or skeleton data. 2178 Instead, it is reserved for use in skeletons passed to APIs doing flexible date pattern generation. 2179 In such a context, it requests the preferred hour format for the locale (h, H, K, or k), as determined by the <strong>preferred</strong> attribute of the <strong>hours</strong> element in supplemental data. 2180 In the implementation of such an API, 'j' must be replaced by h, H, K, or k before beginning a match against availableFormats data.<br/> 2181 Note that use of 'j' in a skeleton passed to an API is the only way to have a skeleton request a locale's preferred time cycle type (12-hour or 24-hour).</td></tr> 2182 <tr><td>jj</td><td>08<br/>08 AM<br/>13<br/>01 PM</td><td>Numeric hour (2 digits, zero pad if needed), abbreviated dayPeriod if used</td></tr> 2183 <tr><td>jjj</td><td>8<br/>8 A.M.<br/>13<br/>1 P.M.</td><td>Numeric hour (minimum digits), wide dayPeriod if used</td></tr> 2184 <tr><td>jjjj</td><td>08<br/>08 A.M.<br/>13<br/>01 P.M.</td><td>Numeric hour (2 digits, zero pad if needed), wide dayPeriod if used</td></tr> 2185 <tr><td>jjjjj</td><td>8<br/>8a<br/>13<br/>1p</td><td>Numeric hour (minimum digits), narrow dayPeriod if used</td></tr> 2186 <tr><td>jjjjjj</td><td>08<br/>08a<br/>13<br/>01p</td><td>Numeric hour (2 digits, zero pad if needed), narrow dayPeriod if used</td></tr> 2187 <!-- J --> 2188 <tr><td rowspan="2">J</td><td>J</td><td>8<br/>8</td><td>Numeric hour (minimum digits)</td> 2189 <td rowspan="2"><em><strong>Input skeleton symbol</strong></em><br/>It must not occur in pattern or skeleton data. 2190 Instead, it is reserved for use in skeletons passed to APIs doing flexible date pattern generation. 2191 In such a context, like 'j', it requests the preferred hour format for the locale (h, H, K, or k), as determined by the <strong>preferred</strong> attribute of the <strong>hours</strong> element in supplemental data. 2192 However, unlike 'j', it requests no dayPeriod marker such as “am/pm” (it is typically used where there is enough context that that is not necessary). 2193 For example, with "jmm", 18:00 could appear as “6:00 PM”, while with "Jmm", it would appear as “6:00” (no PM).</td></tr> 2194 <tr><td>JJ</td><td>08<br/>08</td><td>Numeric hour (2 digits, zero pad if needed)</td></tr> 2195 <!-- C --> 2196 <tr><td rowspan="6">C</td><td>C</td><td>8<br/>8 (morning)</td><td>Numeric hour (minimum digits), abbreviated dayPeriod if used</td> 2197 <td rowspan="6"><em><strong>Input skeleton symbol</strong></em><br/>It must not occur in pattern or skeleton data. 2198 Instead, it is reserved for use in skeletons passed to APIs doing flexible date pattern generation. 2199 In such a context, like 'j', it requests the preferred hour format for the locale. 2200 However, unlike 'j', it can also select formats such as hb or hB, since it is based not on the <strong>preferred</strong> attribute of the <strong>hours</strong> element in supplemental data, but instead on the first element of the <strong>allowed</strong> attribute (which is an ordered preferrence list). 2201 For example, with "Cmm", 18:00 could appear as “6:00 in the afternoon”.</td></tr> 2202 <tr><td>CC</td><td>08<br/>08 (morning)</td><td>Numeric hour (2 digits, zero pad if needed), abbreviated dayPeriod if used</td></tr> 2203 <tr><td>CCC</td><td>8<br/>8 in the morning</td><td>Numeric hour (minimum digits), wide dayPeriod if used</td></tr> 2204 <tr><td>CCCC</td><td>08<br/>08 in the morning</td><td>Numeric hour (2 digits, zero pad if needed), wide dayPeriod if used</td></tr> 2205 <tr><td>CCCCC</td><td>8<br/>8 (morn.)</td><td>Numeric hour (minimum digits), narrow dayPeriod if used</td></tr> 2206 <tr><td>CCCCCC</td><td>08<br/>08 (morn.)</td><td>Numeric hour (2 digits, zero pad if needed), narrow dayPeriod if used</td></tr> 2207 2208<!-- == == == MINUTE == == == --> 2209<tr><th rowspan="2"><a name="dfst-minute" id="dfst-minute" href="#dfst-minute">minute</a></th><td rowspan="2">m</td><td>m</td><td>8, 59</td><td>Numeric: minimum digits</td> 2210 <td rowspan="2">Minute (numeric). Truncated, not rounded.<br/></td></tr> 2211 <tr><td>mm</td><td>08, 59</td><td>Numeric: 2 digits, zero pad if needed</td></tr> 2212 2213<!-- == == == SECOND == == == --> 2214<tr><th rowspan="4"><a name="dfst-second" id="dfst-second" href="#dfst-second">second</a></th><td rowspan="2">s</td><td>s</td><td>8, 12</td><td>Numeric: minimum digits</td> 2215 <td rowspan="2">Second (numeric). Truncated, not rounded.<br/></td></tr> 2216 <tr><td>ss</td><td>08, 12</td><td>Numeric: 2 digits, zero pad if needed</td></tr> 2217 <tr><td>S</td><td>S+</td><td>3456</td> 2218 <td colspan="2">Fractional Second (numeric). 2219 Truncates, like other numeric time fields, but in this case to the number of digits specified by the field length. 2220 (Example shows display using pattern SSSS for seconds value 12.34567)</td></tr> 2221 <tr><td>A</td><td>A+</td><td>69540000</td> 2222 <td colspan="2">Milliseconds in day (numeric). 2223 This field behaves <i>exactly</i> like a composite of all time-related fields, not including the zone fields. 2224 As such, it also reflects discontinuities of those fields on DST transition days. On a day of DST onset, it will jump forward. 2225 On a day of DST cessation, it will jump backward. 2226 This reflects the fact that it must be combined with the offset field to obtain a unique local time value. 2227 The field length specifies the minimum number of digits, with zero-padding as necessary.</td></tr> 2228 2229<!-- == == == SEPARATOR == == == --> 2230<tr><th><a name="dfst-sep" id="dfst-sep" href="#dfst-sep">sep.</a></th><td>(none def., see note)</td><td></td><td></td> 2231 <td colspan="2">Time separator.<br/><br/><span class="note"><b>Note:</b> 2232 In CLDR 26 the time separator pattern character was specified to be COLON. 2233 This was withdrawn in CLDR 28 due to backward compatibility issues, and no time separator pattern character is currently defined.</span><br/><br/> 2234 Like the use of "," in number formats, this character in a date pattern is replaced with the corresponding number symbol which may depend on the numbering system. 2235 For more information, see <em><strong>Part 3: <a href="tr35-numbers.md#Contents">Numbers</a></strong>, <a href="tr35-numbers.md#Number_Symbols">Number Symbols</a></em>.</td></tr> 2236 2237<!-- == == == ZONE == == == --> 2238<tr><th rowspan="23"><a name="dfst-zone" id="dfst-zone" href="#dfst-zone">zone</a></th><td rowspan="2">z</td><td>z..zzz</td><td>PDT</td> 2239 <td colspan="2">The <i>short specific non-location format</i>. Where that is unavailable, falls back to the <i>short localized GMT format</i> ("O").</td></tr> 2240 <tr><td>zzzz</td><td>Pacific Daylight Time</td> 2241 <td colspan="2">The <i>long specific non-location format</i>. 2242 Where that is unavailable, falls back to the <i>long localized GMT format</i> ("OOOO").</td></tr> 2243 <!-- Z --> 2244 <tr><td rowspan="3">Z</td><td>Z..ZZZ</td><td>-0800</td> 2245 <td colspan="2">The <i>ISO8601 basic format</i> with hours, minutes and optional seconds fields. 2246 The format is equivalent to RFC 822 zone format (when optional seconds field is absent). 2247 This is equivalent to the "xxxx" specifier.</td></tr> 2248 <tr><td>ZZZZ</td><td>GMT-8:00</td> 2249 <td colspan="2">The <i>long localized GMT format</i>. 2250 This is equivalent to the "OOOO" specifier.</td></tr> 2251 <tr><td>ZZZZZ</td><td>-08:00<br/>-07:52:58</td> 2252 <td colspan="2">The <i>ISO8601 extended format</i> with hours, minutes and optional seconds fields. 2253 The ISO8601 UTC indicator "Z" is used when local time offset is 0. 2254 This is equivalent to the "XXXXX" specifier.</td></tr> 2255 <!-- O --> 2256 <tr><td rowspan="2">O</td><td>O</td><td>GMT-8</td><td colspan="2">The <i>short localized GMT format</i>.</td></tr> 2257 <tr><td>OOOO</td><td>GMT-08:00</td><td colspan="2">The <i>long localized GMT format</i>.</td></tr> 2258 <!-- v --> 2259 <tr><td rowspan="2">v</td><td>v</td><td>PT</td> 2260 <td colspan="2">The <i>short generic non-location format</i> 2261 Where that is unavailable, falls back to the <i>generic location format</i> ("VVVV"), then the <i>short localized GMT format</i> as the final fallback.</td></tr> 2262 <tr><td>vvvv</td><td>Pacific Time</td> 2263 <td colspan="2">The <i>long generic non-location format</i>. 2264 Where that is unavailable, falls back to <i>generic location format</i> ("VVVV").</td></tr> 2265 <!-- V --> 2266 <tr><td rowspan="4">V</td><td>V</td><td>uslax</td> 2267 <td colspan="2">The short time zone ID. Where that is unavailable, the special short time zone ID <i>unk</i> (Unknown Zone) is used.<br/> 2268 <i><b>Note</b>: This specifier was originally used for a variant of the short specific non-location format, but it was deprecated in the later version of this specification. 2269 In CLDR 23, the definition of the specifier was changed to designate a short time zone ID.</i></td></tr> 2270 <tr><td>VV</td><td>America/Los_Angeles</td><td colspan="2">The long time zone ID.</td></tr> 2271 <tr><td>VVV</td><td>Los Angeles</td> 2272 <td colspan="2">The exemplar city (location) for the time zone. 2273 Where that is unavailable, the localized exemplar city name for the special zone <i>Etc/Unknown</i> is used as the fallback (for example, "Unknown City").</td></tr> 2274 <tr><td>VVVV</td><td>Los Angeles Time</td> 2275 <td colspan="2">The <i>generic location format</i>. 2276 Where that is unavailable, falls back to the <i>long localized GMT format</i> ("OOOO"; Note: Fallback is only necessary with a GMT-style Time Zone ID, like Etc/GMT-830.)<br/> 2277 This is especially useful when presenting possible timezone choices for user selection, since the naming is more uniform than the "v" format.</td></tr> 2278 <!-- X --> 2279 <tr><td rowspan="5">X</td><td>X</td><td>-08<br/>+0530<br/>Z</td> 2280 <td colspan="2">The <i>ISO8601 basic format</i> with hours field and optional minutes field. 2281 The ISO8601 UTC indicator "Z" is used when local time offset is 0. (The same as x, plus "Z".)</td></tr> 2282 <tr><td>XX</td><td>-0800<br/>Z</td> 2283 <td colspan="2">The <i>ISO8601 basic format</i> with hours and minutes fields. 2284 The ISO8601 UTC indicator "Z" is used when local time offset is 0. (The same as xx, plus "Z".)</td></tr> 2285 <tr><td>XXX</td><td>-08:00<br/>Z</td> 2286 <td colspan="2">The <i>ISO8601 extended format</i> with hours and minutes fields. 2287 The ISO8601 UTC indicator "Z" is used when local time offset is 0. (The same as xxx, plus "Z".)</td></tr> 2288 <tr><td>XXXX</td><td>-0800<br/>-075258<br/>Z</td> 2289 <td colspan="2">The <i>ISO8601 basic format</i> with hours, minutes and optional seconds fields. 2290 The ISO8601 UTC indicator "Z" is used when local time offset is 0. (The same as xxxx, plus "Z".)<br/> 2291 <i><b>Note</b>: The seconds field is not supported by the ISO8601 specification.</i></td></tr> 2292 <tr><td>XXXXX</td><td>-08:00<br/>-07:52:58<br/>Z</td> 2293 <td colspan="2">The <i>ISO8601 extended format</i> with hours, minutes and optional seconds fields. 2294 The ISO8601 UTC indicator "Z" is used when local time offset is 0. (The same as xxxxx, plus "Z".)<br/> 2295 <i><b>Note</b>: The seconds field is not supported by the ISO8601 specification.</i></td></tr> 2296 <!-- x --> 2297 <tr><td rowspan="5">x</td><td>x</td><td>-08<br/>+0530<br/>+00</td> 2298 <td colspan="2">The <i>ISO8601 basic format</i> with hours field and optional minutes field. (The same as X, minus "Z".)</td></tr> 2299 <tr><td>xx</td><td>-0800<br/>+0000</td> 2300 <td colspan="2">The <i>ISO8601 basic format</i> with hours and minutes fields. (The same as XX, minus "Z".)</td></tr> 2301 <tr><td>xxx</td><td>-08:00<br/>+00:00</td> 2302 <td colspan="2">The <i>ISO8601 extended format</i> with hours and minutes fields. (The same as XXX, minus "Z".)</td></tr> 2303 <tr><td>xxxx</td><td>-0800<br/>-075258<br/>+0000</td> 2304 <td colspan="2">The <i>ISO8601 basic format</i> with hours, minutes and optional seconds fields. (The same as XXXX, minus "Z".)<br/> 2305 <i><b>Note</b>: The seconds field is not supported by the ISO8601 specification.</i></td></tr> 2306 <tr><td>xxxxx</td><td>-08:00<br/>-07:52:58<br/>+00:00</td> 2307 <td colspan="2">The <i>ISO8601 extended format</i> with hours, minutes and optional seconds fields. (The same as XXXXX, minus "Z".)<br/> 2308 <i><b>Note</b>: The seconds field is not supported by the ISO8601 specification.</i></td></tr> 2309</tbody></table> 2310 2311### <a name="Localized_Pattern_Characters" href="#Localized_Pattern_Characters">Localized Pattern Characters (deprecated)</a> 2312 2313These are characters that can be used when displaying a date pattern to an end user. This can occur, for example, when a spreadsheet allows users to specify date patterns. Whatever is in the string is substituted one-for-one with the characters "GyMdkHmsSEDFwWahKzYeugAZvcLQqVUOXxr", with the above meanings. Thus, for example, if 'J' is to be used instead of 'Y' to mean Year (for Week of Year), then the string would be: "GyMdkHmsSEDFwWahKzJeugAZvcLQqVUOXxr". 2314 2315This element is deprecated. It is recommended instead that a more sophisticated UI be used for localization, such as using icons to represent the different formats (and lengths) in the [Date Field Symbol Table](#Date_Field_Symbol_Table). 2316 2317### <a name="Date_Patterns_AM_PM" href="#Date_Patterns_AM_PM">AM / PM</a> 2318 2319Even for countries where the customary date format only has a 24 hour format, both the am and pm localized strings must be present and must be distinct from one another. Note that as long as the 24 hour format is used, these strings will normally never be used, but for testing and unusual circumstances they must be present. 2320 2321### <a name="Date_Patterns_Eras" href="#Date_Patterns_Eras">Eras</a> 2322 2323There are only two values for era in the Gregorian calendar, with two common naming conventions (here in abbreviated form for English): "BC" and "AD", or "BCE" and "CE". These values can be translated into other languages, like "a.C." and "d.C." for Spanish, but there are no other eras in the Gregorian calendar. Other calendars have different numbers of eras. Care should be taken when translating the era names for a specific calendar. 2324 2325### <a name="Date_Patterns_Week_Of_Year" href="#Date_Patterns_Week_Of_Year">Week of Year</a> 2326 2327Values calculated for the Week of Year field range from 1 to 53 for the Gregorian calendar (they may have different ranges for other calendars). Week 1 for a year is the first week that contains at least the specified minimum number of days from that year. Weeks between week 1 of one year and week 1 of the following year are numbered sequentially from 2 to 52 or 53 (if needed). For example, January 1, 1998 was a Thursday. If the first day of the week is MONDAY and the minimum days in a week is 4 (these are the values reflecting ISO 8601 and many national standards), then week 1 of 1998 starts on December 29, 1997, and ends on January 4, 1998. However, if the first day of the week is SUNDAY, then week 1 of 1998 starts on January 4, 1998, and ends on January 10, 1998. The first three days of 1998 are then part of week 53 of 1997. 2328 2329Values are similarly calculated for the Week of Month. 2330 2331### <a name="Date_Patterns_Week_Elements" href="#Date_Patterns_Week_Elements">Week Elements</a> 2332 2333**firstDay** 2334 2335A number indicating which day of the week is considered the 'first' day, for calendar purposes. Because the ordering of days may vary between calendar, keywords are used for this value, such as sun, mon, …. These values will be replaced by the localized name when they are actually used. 2336 2337**minDays (Minimal Days in First Week)** 2338 2339Minimal days required in the first week of a month or year. For example, if the first week is defined as one that contains at least one day, this value will be 1. If it must contain a full seven days before it counts as the first week, then the value would be 7. 2340 2341**weekendStart, weekendEnd** 2342 2343Indicates the day and time that the weekend starts or ends. As with firstDay, keywords are used instead of numbers. 2344 2345## <a name="Parsing_Dates_Times" href="#Parsing_Dates_Times">Parsing Dates and Times</a> 2346 2347For general information on lenient parsing, see [Lenient Parsing](tr35.md#Lenient_Parsing) in the core specification. This section provides additional information specific to parsing of dates and times. 2348 2349Lenient parsing of date and time strings is especially complicated, due to the large number of possible fields and formats. The fields fall into two categories: numeric fields (hour, day of month, year, numeric month, and so on) and symbolic fields (era, quarter, month, weekday, AM/PM, time zone). In addition, the user may type in a date or time in a form that is significantly different from the normal format for the locale, and the application must use the locale information to figure out what the user meant. Input may well consist of nothing but a string of numbers with separators, for example, "09/05/02 09:57:33". 2350 2351The input can be separated into tokens: numbers, symbols, and literal strings. Some care must be taken due to ambiguity, for example, in the Japanese locale the symbol for March is "3 月", which looks like a number followed by a literal. To avoid these problems, symbols should be checked first, and spaces should be ignored (except to delimit the tokens of the input string). 2352 2353The meaning of symbol fields should be easy to determine; the problem is determining the meaning of the numeric fields. Disambiguation will likely be most successful if it is based on heuristics. Here are some rules that can help: 2354 2355* Always try the format string expected for the input text first. This is the only way to disambiguate 03/07 (March 2007, a credit card expiration date) from 03/07 (March 7, a birthday). 2356* Attempt to match fields and literals against those in the format string, using loose matching of the tokens. In particular, Unicode normalization and case variants should be accepted. Alternate symbols can also be accepted where unambiguous: for example, “11.30 am”. 2357* When matching symbols, try the narrow, abbreviated, and full-width forms, including standalone forms if they are unique. You may want to allow prefix matches too, or diacritic-insensitive, again, as long as they are unique. For example, for a month, accept 9, 09, S, Se, Sep, Sept, Sept., and so on. For abbreviated symbols (e.g. names of eras, months, weekdays), allow matches both with and without an abbreviation marker such as period (or whatever else may be customary in the locale); abbreviated forms in the CLDR data may or may not have such a marker. 2358 * Note: While parsing of narrow date values (e.g. month or day names) may be required in order to obtain minimum information from a formatted date (for instance, the only month information may be in a narrow form), the results are not guaranteed; parsing of an ambiguous formatted date string may produce a result that differs from the date originally used to create the formatted string. 2359 * For day periods, ASCII variants for AM/PM such as “am”, “a.m.”, “am.” (and their case variants) should be accepted, since they are widely used as alternates to native formats. 2360* When a field or literal is encountered that is not compatible with the pattern: 2361 * Synchronization is not necessary for symbolic fields, since they are self-identifying. Wait until a numeric field or literal is encountered before attempting to resynchronize. 2362 * Ignore whether the input token is symbolic or numeric, if it is compatible with the current field in the pattern. 2363 * Look forward or backward in the current format string for a literal that matches the one most recently encountered. See if you can resynchronize from that point. Use the value of the numeric field to resynchronize as well, if possible (for example, a number larger than the largest month cannot be a month). 2364 * If that fails, use other format strings from the locale (including those in `<availableFormats>`) to try to match the previous or next symbol or literal (again, using a loose match). 2365 2366* * * 2367 2368Copyright © 2001–2024 Unicode, Inc. All Rights Reserved. The Unicode Consortium makes no expressed or implied warranty of any kind, and assumes no liability for errors or omissions. No liability is assumed for incidental and consequential damages in connection with or arising out of the use of the information or programs contained or accompanying this technical report. The Unicode [Terms of Use](https://www.unicode.org/copyright.html) apply. 2369 2370Unicode and the Unicode logo are trademarks of Unicode, Inc., and are registered in some jurisdictions. 2371