Date/Time Patterns

Last updated: 2017-May-31

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.

Important: the characters a-z and A-Z are special placeholders; they stand for date or time fields, NOT real characters. For example, y stands for a numeric year and will be replaced by a value like '1998'.  See Date/Time Symbols for a brief summary, or Date Field Symbol Table for a more complete and detailed list.

Any "real" characters need to be quoted, as in the following where a real character 'g' needs to be in the pattern.

EEE, yyyy. 'g'. dd. MMM

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).
  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.

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.

  • 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".
  • 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]

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