Date/Time Patterns

Last updated: 2018-May-14

Introduction

A date-time pattern is a string of characters in which certain substrings are placeholders that represent particular calendar fields, and the other text is “literal” text that is used as is.
  • Substrings consisting of one or more instances of the letters a-z A-Z represent particular calendar fields.
    • The particular letter indicates the type of calendar field (e.g. month or weekday), and the number of letters indicates that form in which that field is presented (e.g. numeric, abbreviated or full name, etc.). For example, substrings using ‘M’ represent a format month (intended to be used in conjunction with a day number); the lengths MM and M represent the numeric month (with and without leading zero-padding to two digits), while the lengths MMM, MMMM, and MMMMM represent the abbreviated, full, and narrow month name respectively.
    • When formatting a particular date, the values from the calendar are substituted into the appropriate pattern substrings, using the Date Format Symbols from the locale’s calendar data for non-numeric values. For example, the substring M might be replaced by “3”, while the substring MMMM might be replaced by “March”. When parsing a date string, the pattern substrings will be converted into the appropriate numeric calendar data.
    • See Date/Time Symbols for a brief summary of letters for different calendar fields, or Date Field Symbol Table for a more complete and detailed list.
  • Other text in the date-time pattern with be used as-is when formatting, and will be expected when parsing a date string. To include text consisting of a-z A-Z as literal text in a date-term pattern, enclose it in single straight quotes, such as 'as'. To include a single straight quote in literal text, use two of them together: '' (either inside or outside a section of literal text enclosed in single straight quotes).
 Some examples (from Date Format Pattern Examples):

Pattern Result (in a particular locale)
yyyy.MM.dd G 'at' HH:mm:ss zzz 1996.07.10 AD at 15:08:56 PDT
EEE, MMM d, ''yy Wed, July 10, '96
h:mm a 12:08 PM
hh 'o''clock' a, zzzz 12 o'clock PM, Pacific Daylight Time
K:mm a, z 0:00 PM, PST
yyyyy.MMMM.dd GGG hh:mm aaa 01996.July.10 AD 12:08 PM

The following date-time patterns need to be supplied. In order to get the right formats for your language, you may need to change the ordering of the Date/Time Symbols, and change the text around them.

Synchronizing Date/Time Names and Patterns

There is a tight coupling between the date/time patterns and the names that are used for date/time elements, described in Date/Time Names.

For one thing, the different lengths of names—wide or full, abbreviated and/or short, narrow— should match how the different lengths are used in patterns. For example, if the pattern “h:mm a” (using the pattern substring “a” for abbreviated AM/PM marker) is intended to produce results like “2:37 PM”, then the abbreviated AM/PM names should contain “AM” and “PM”, and not (for example) “Ante Meridiem” and “Post Meridiem” (which might be used for for the wide AM/PM names).

However, there is another area where close coordination is necessary. Some types of names, such as month names and weekday names, have two styles: a format style and a stand-alone style. In particular, the format-style month names (represented by pattern strings using ‘M’ such as MMMM) are intended to be used when the month is displayed in conjunction with a day-of-the-month number (e.g. in a pattern like “d MMMM y”), and the stand-alone-style month names (represented by pattern strings using ‘L’ such as “LLLL”) are intended to be used when the month is displayed without a day-of-the-month number (e.g. in a pattern like “LLLL y”). This can have different implications for different languages.

  1. Some languages (e.g. Finnish and many Slavic languages) use a month name in nominative case when it is displayed without a day number, and use a different case (genitive, partitive, etc.) when the month is displayed with a day number. For these languages, the stand-alone month names should be in nominative case, and the format month names should be in genitive or a related case.
  wide format months
MMMM
wide stand-alone
months
LLLL
pattern for full date, e.g.in e-mail log:
“d. MMMM y”
examples below:
pattern for month + year, e.g. in calendar:
“LLLL y”
examples below:
pattern for month name by itself, e.g. in menu:
“LLLL”
examples below:
 7
 heinäkuuta  heinäkuu  5. heinäkuuta 2018  heinäkuu 2018  heinäkuu
 8  elokuuta  elokuu  10. elokuuta 2018  elokuu 2018  elokuu
 9  syyskuuta  syyskuu  15. syyskuuta 2018  syyskuu 2018  syyskuu
 10  lokakuuta  lokakuu  20. lokakuuta 2018  lokakuu 2018  lokakuu
  1. Other language (e.g. Catalan) use a preposition to combine the month and day number, e.g. “11 de setembre” (11 of September). If the month name begins with a vowel, the preposition is contracted, e.g. “12 d’octubre”. In this case, the format month names should include the preposition in its correct form (contracted or not), and the stand-alone month names should not include the preposition; the patterns should not include the preposition for month:
  wide format months
MMMM
wide stand-alone
months
LLLL
pattern for full date,
e.g.in e-mail log:
“d MMMM 'de' y”
examples below:
pattern for month + year, e.g. in calendar:
“LLLL 'de' y”
examples below:
pattern for month name by itself, e.g. in menu:
“LLLL”
examples below:
 7
 de juliol  juliol  5 de juliol de 2018  juliol de 2018  juliol
 8  d’agost  agost  10 d’agost de 2018  agost de 2018  agost
 9  de setembre  setembre  15 de setembre de 2018  setembre de 2018  setembre
 10  d’octubre  octubre  20 d’octubre de 2018  octubre de 2018  octubre
    Even for language that do not require such different forms it is a good idea, for consistency, to use ‘L’ for months in patterns without ‘d’, and ‘M’ for months in patterns with ‘d’.

    In some languages, the weekday name format forms (e.g. EEEE) and stand-alone forms (e.g. cccc) forms may also differ, and may require similar coordination between names and patterns.

    Basic Time Formats

    The standard formats include four basic time formats.

    • full should contain hour (h/H), minute (mm), second (ss), and zone (zzzz).
    • long should contain hour, minute, second, and zone (z)
    • medium should contain hour, minute, second.
    • short should contain hour, minute.
    Note: The patterns depend on whether the main country using your language uses 12-hour time or not.
    1. For 12-hour time, use a pattern like "hh:mm a" using h to mean a 12-hour clock cycle running 1 through 12 (midnight plus 1 minute is 12:01), or using K to mean a 12-hour clock cycle running 0 through 11 (midnight plus 1 minute is 0:01). Use a to get the equivalent of AM/PM, b to add special representation of noon/midnight, and B to use day periods like “in the afternoon” instead of AM/PM.
    2. For 24-hour time, use a pattern like "HH:mm" using H to mean a 24-hour clock cycle running 0 through 23 (midnight plus 1 minute is 0:01), or using k to mean a 24-hour clock cycle running 1 through 24 (midnight plus 1 minute is 24:01).
    If some other countries use a different time format, then patterns should be added there. For example, if fr (=fr-FR, French as used in France) uses 24-hour time formats, but fr-CA (French as used in Canada) uses 12 hour time formats, then fr should have formats like #2, and fr-CA should have formats like #1.

    Languages should always have translations for AM/PM/noon even if every country they are used in has 24 hour time. Many computing systems allow users to override the locale defaults, so that a particular user may specify 12-hour time even if the locale normally uses 24-hour time.

    Basic Date Formats

    The standard formats include four basic date formats.

    • full should contain long-weekday (EEEE), year (y), long-month (MMMM), day (d).
      • For example, English uses "EEEE, MMMM d, y", corresponding to a date like "Tuesday, September 14, 1999".
      • In some non-Gregorian calendars, it will also contain G representing the era name, such as "AH" or "Heisei" (i.e. "平成").
      • For some languages, long months are not used; for example, in Japanese the numeric month is used in patterns, in front of the character 月.
    • long should contain year, long-month, day.
      • For example, "MMMM d, y", corresponding to a date like "September 14, 1999".
    • medium should contain year, abbreviated-month (MMM), day.
      • For example, "MMM d, y", corresponding to a date like "Sep 14, 1999".
      • For languages that do not use abbreviated months, use the numeric month (MM/M). For example, "y/MM/dd", corresponding to a date like "1999/09/14".
    • short should contain year, numeric-month (MM/M), and day.
      • For example, "M/d/yy", corresponding to a date like "9/14/99".
    The Month symbol especially may vary (M vs MM, or MMM vs LLL). For more information, see Date/Time Symbols.

    Additional Date-Time Formats

    The basic formats provide a small subset of the combinations that people need. For the others, a skeleton format is provided that uses the Date/Time Symbols (without order or punctuation) to indicate what fields are desired. You need to provide the ordering and punctuation that would be used in your locale.

    For example, where a program needs just the month and day, here's what that would look like:

    The skeletons are listed in the Code column in Survey Tool.

    In some languages, flexible formats may need to differentiate between nominative forms and genitive (or related) forms of month and day names. To understand which pattern characters are used for standalone forms (nominative) versus format forms (genitive or related, such as partitive), see Stand-Alone vs Format Styles, see also the discussion above in Synchronizing Date/Time Names and Patterns.

    • The month names may need to be in nominative form if the format does not include a day, as for a skeleton such as yMMMM. To handle this, put the nominative forms in the standalone month names, which are designated using a pattern field such as "LLL" or "LLLL". The skeleton yMMMM would then map to a pattern such as  "LLLL y". See discussion
    • Similarly, the month names may need to be in genitive form (or a related form such as partitive) if the format does include a day, as for a skeleton such as MMMMd. To handle this, put the genitive or similar forms in the format month names, which are designated using a pattern field such as "MMM" or "MMMM". The skeleton MMMMd would then map to a pattern such as  "d MMMM".
    • Day names may also need to be in nominative or genitive form, depending on other elements of the date pattern. The nominative forms should be in the standalone day names, which are designated using a pattern field such as "ccc" or "cccc"; the genitive forms should be in the format day names, which are designated using a pattern field such as "E" or "EEEE". Skeletons can then map to patterns that use the appropriate day name form.
    Patterns may be automatically extended from the abbreviated form to an inferred full form. For example:

       Skeleton  Hypothetical English case   For ja@calendar=chinese
     Pattern  Example    
     supplied  MMMEd      E MMM d  Tue Apr 18  MMMd日(E)  四月18日(火)
     inferred  MMMMEd  E MMMM d  Tue April 18  MMMMd日(E)  四月18日(火)
     inferred  MMMEEEEd  EEEE MMM d  Tuesday Apr 18  [incorrect]  MMMd日(EEEE)  四月18日(火曜日)  [incorrect]
     inferred   MMMMEEEEd  EEEE MMMM d  Tuesday April 18 [incorrect]  MMMMd日(EEEE)  四月18日(火曜日)  [incorrect]

    If that results in correct behavior, there may be no need to supply the longer forms, except where they are needed to override an inherited pattern. But if the inferred form is incorrect for some cases, as above, then an explicit longer form may be supplied. In the above example, when the full weekday name EEEE is used, it should have a comma in the English example, and should not be enclosed in parentheses in the Japanese example. So in this case an additional form for MMMEEEEd would be supplied:

     supplied  MMMEEEEd  EEEE, MMM d  Tuesday, Apr 18  [correct]  MMMd日EEEE  四月18日火曜日  [correct]
     inferred   MMMMEEEEd  EEEE, MMMM d  Tuesday, April 18 [correct]  MMMMd日EEEE  四月18日火曜日  [correct]

    Patterns without abbreviated months

    For languages that do not use abbreviated months, a skeleton containing abbreviated month MMM is typically mapped to a pattern that uses numeric month M or MM. In this case it is necessary to also supply a skeleton and pattern that use the full month MMMM, since relying on the automatic extension of entries with skeletonMMM would produce the wrong result. For example:

       Skeleton Finnish
     Pattern  Example
     supplied  yMMMd     d.M.y 18.4.2015
     supplied  yMMMMd d. MMMM y 18. huhtikuuta 2015
    without the second entry, would have: inferred  yMMMMd d.M.y 18.4.2015

    Always verify your intent using the examples in the right pane.

    Reminder: If your language has different grammatical forms for date symbols such as month and day names, the nominative forms of the names should be in the Survey Tool section marked "Standalone", and the genitive or related forms should be in the Survey Tool section marked "Formatting".

    Day period patterns

    There are three pattern characters that can you can use to indicate the day period marker in 12-hour-cycle time formats:
    • ‘a‘ to indicate the equivalent of just AM and PM, e.g.: 12:00 AM, 10:00 AM, 12:00 PM, 7:00 PM
    • 'b' to indicate the equivalent of AM, PM, noon and midnight, e.g.: 12:00 midnight, 10:00 AM, 12:00 noon, 7:00 PM.
      If a locale does not have data for noon and midnight, this is equivalent to (falls back to) 'a'.
    • 'B' to indicate day periods with locale-specific ranges, e.g.: 12:00 at night, 10:00 in the morning, 12:00 in the afternoon, 7:00 in the evening.
      If a locale does not have data for such day period ranges, this is equivalent to (falls back to) 'b'.
    Each of these comes in three widths: a/b/B for abbreviated, aaaa/bbbb/BBBB for full, and aaaaa/bbbbb/BBBBB for narrow.

    With skeletons (listed in the Code column in Survey Tool) that specify 'h' but no day period, the corresponding patterns are specified with a day period, normally 'a' or 'b'. The patterns can be used to infer how to handle a request for a different day period. For example:

       Code  English pattern (example)
     supplied  hm  h:mm a
     inferred   ahm  h:mm a
     inferred   aaaahm  h:mm aaaa
     inferred  bhm  h:mm b
     inferred  bbbbhm  h:mm bbbb
     inferred*  Bhm  h:mm B [*see notes below]
     inferred*  BBBBhm  h:mm BBBB [*see notes below]

    Beginning in CLDR 32, there are 5 additional time patterns that indicate how times should be formatted using day period ranges 'B'. This allows locales to have formats for day period ranges that can display the range symbol in a different position than might be used for symbols for AM, PM, noon, or midnight:

       Code  English pattern (example)
     supplied  Bh  B h
     supplied  Bhm  B h:mm
     supplied  Bhms  B h:mm:ss
     supplied  EBhm  B h:mm, E
     supplied  EBhms  B h:mm:ss, E
     inferred  BBBBhm  BBBB h:mm
     inferred  ...  ...

    These new patterns are available in Gregorian and Generic calendars, and the examples show some day periods for the locale as shown in this screenshot below. In these new fields, provide locale data by:

    1. Placing the pattern character ('B' in the example below) in the correct position. 
      1. If it is equally good in two different positions, favor the position used for the 'a' pattern character.
      2. If the position needs to be different depending on the width of B, please file a ticket.
    2. For more information on the day periods used in your language:
      1. First see Day Periods (AM, PM, etc.) for a general discussion of how day periods work.
      2. See the Day Periods chart for your language.

    Date-Time Pattern

    The date-time pattern shows how to combine separate patterns for date (represented by {1}) and time (represented by {0}) into a single pattern. It usually doesn't need to be changed. What you want to pay attention to are:
    • possibly removing a space for languages that don't use it, such as many East Asian languages
    • possibly adding a comma, other punctuation, or a combining word

    For example:
    • English uses "{1} 'at' {0}" or "{1}, {0}" (depending on date style), while Japanese uses "{1}{0}". 
    • An English formatted date-time using the combining pattern "{1}, {0}" could be "Dec 10, 2010, 3:59:49 PM". Notice the comma and space between the date portion and the time portion.
    There are four formats: full, long, medium, and short.
    The determination of which to use is normally based on the date style, for example:
    • If the date has a full month and weekday name, the full combining pattern will be used to combine that with a time.
    • If the date has numeric month, the short version of the combining pattern will be used to combine that with a time.
    English uses "{1} 'at' {0}" for full and long styles, and "{1}, {0}" for medium and short styles.

    Here are some examples of the resulting behavior when combining a date and time:
     date pattern  time pattern  date-time combining pattern used  formatted example
     MMMM d, y  h:mm a  [long]  {1} 'at' {0}   September 14, 1999 at 1:25 PM
     M/d/yy  h:mm a  [short] {1}, {0}  9/14/99, 1:25 PM

    Week-Of Patterns

    The week-of date patterns were introduced in CLDR 30 for enumerating week count in larger periods, e.g. “week 15 of 2016” or “week 4 of April”. The Survey Tool fields and corresponding English entries are shown below:
     Survey Tool field  English pattern Pattern characters
     yw-one  'week' w 'of' Y w designates the number of the week within a year calculated for week-of year purposes and indicated using the pattern character Y (instead of the normal year designator y).
    The year indicated by Y typically begins on the locale’s first day of the week and ends on the last day of the week, so its transitions may differ by a few days from the standard year indicated by y.
     yw-other  'week' w 'of' Y
     MMMMW-one  'week' W 'of' MMMM W designates the number of the week within the month
     MMMMW-other  'week' W 'of' MMMM

    The pattern can be selected based on the plural form associated with the week number, in case the form depends on the number.  Currently these patterns only support cardinal numbers; in the future they may be extended to support ordinal numbers for usages such as “2nd week of April” in which case the distinction by plural form associated with week number may become more relevant. In languages where the month name needs grammatical changes (aside from just the simple addition of a prefix or suffix), localizers will need to use a work-around construction (file a ticket if this is the case for your language).

    As described under Date/Time Names, CLDR also provides a relative week period pattern which is used for constructions such as “the week of April 11, 2016”. The English pattern that produces this is “the week of {0}”; the date format that replaces {0} is determined separately. Because the week-of patterns described here may appear in user interfaces that also show dates produced using the relative week period patterns, all of these patterns should be designed with consistent wording and structure.

    Flexible - Append 

    The flexible append format for Timezone is used to compose a time and a timezone, to get a result like "11:30 Pacific Time". For almost all locales it is just "{0} {1}" (where the {0} will be replaced by the localized time format, and {1} will be replaced by the localized timezone), but some locales change the order, add punctuation, or remove the space.

    Date/Time Intervals

    Interval patterns contain a start pattern and an end pattern (using the Date/Time Symbols). They are used for a range of dates or times, such as "Sept 10–12" (meaning the 10th of September through the 12th of September). The interval format is used where it is necessary to make the pattern as short as possible, and elide information that does not have to be repeated. For example, the pattern used to get "Sept 10–12" in English is "MMM d–d".

    Unlike simple Date/Time Patterns, these consist of two parts, typically separated by with some kind of punctuation mark (e.g. English uses en-dash " – "). Also, some fields in the second part are omitted (e.g. "d – d MMM" omits repeat of MMM for the second part). The first field that comes from the second date is marked with red in the examples below.

    Interval Formatting

    Format Pattern Date 1 Date 2 Result
    MMM d–d 2008-09-13 2008-09-15 Sept 13–15
    MMMM–MMMM, yyyy 2008-09-01 2008-11-31 September–November, 2008

    Greatest Difference

    Each combination of fields can be used with dates that differ by different amounts. For example, a format for the fields "yMMMd" (year, abbreviated month, and day) could be used with two dates that differ by year, month, or day.

    As the examples below indicate, for a given skeleton, each type of difference might need a different pattern.
    For example,

    • when the greatest difference is a year, no part of the second pattern is omitted;
    • when the greatest difference is a month, then the year is not repeated, since it would be the same for each pattern.
    Date 1 Date 2 Greatest Difference Format Pattern Shares
    2008-09-13 2009-09-15 year (yMd) MMM d, yyyy – MMM d, yyyy nothing
    2008-09-01 2008-11-31 month (Md) MMM d – MMM d, yyyy year
    2008-09-01 2008-09-05 day (d) MMM d–d, yyyy year and month

    Patterns for Different Calendars 

    You can supply patterns for different calendars besides the Gregorian calendar, such as the Buddhist, Islamic, Hebrew, or Japanese calendars. However, in many cases, CLDR provides data inheritance that may make it unnecessary to supply formats for most calendars.

    • Basic time formats for all calendars are inherited from the Gregorian time formats. In most locales there is no need for a particular calendar to use different time formats than the Gregorian calendar, and hence no need to supply standard time formats for non-Gregorian calendars.
    • In many locales, the main difference between date formats for Gregorian calendars and non-Gregorian calendars is that the latter always show the year with a calendar era. To avoid having to do this separately for each non-Gregorian calendar, CLDR has a special “Generic” calendar to specify standard date formats for non-Gregorian calendars. If you specify the date formats for the “Generic” calendar, using year with a calendar era, then those data formats will be used for most non-Gregorian calendars unless those calendars explicitly specify their own date formats. However, because the Generic calendar does not have real names for months, weekdays and eras, the Survey Tool examples generated for this calendar may be confusing.
    • Calendars that do not inherit date formats from the Generic calendar are the East Asian lunar calendars, currently Chinese (lunar) and Dangi (Korean lunar). These have special formats involving cyclic names. The Dangu calendar inherits formats from the Chinese calendar data in the same locale, while the Chinese calendar inherits formats directly from the parent locale; that parent locale may be the root locale or inherit these formats directly from the root locale. For the lunar calendars, the root locale has formats that should be reasonable for use in most locales where the lunar calendars are not one of the primary calendars.

    Comments