Date/Time Patterns

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

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

There are 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"
  2. For 24-hour time, use a pattern like "HH:mm".
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

There are 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"
    • In some non-Gregorian calendars, it will also contain era (G).
    • 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.
  • medium should contain year, abbreviated-month (MMM), day
    • For some languages, abbreviated months are not used; in that case, the medium format should contain the numeric month (MM/M).
  • short should contain year, numeric-month (MM/M), day
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:

In some languages the month may need be in nominative case if the format does not include a day, and in genitive or a related case if the format does include a day. In such cases the normal approach is to use the stand-alone forms (e.g. LLLL) for nominative month names and the format forms (e.g. MMMM) for genitive month names, then a skeleton such a yMMMM might map to a pattern "LLLL y" while a skeleton such as yMMMMd might map to a pattern "d MMMM y". See notes on Stand-Alone vs Format Styles.

Date-Time Pattern

The date-time pattern is used to make a date plus time out of separate date and time patterns. It usually doesn't need to be changed, except for removing a space for languages that don't use it, or possibly adding a comma or other punctuation.

For example:
  • English uses "{1} 'at' {0}" or "{1}, {0}" (depending on date style), while Japanese uses "{1}{0}". 
  • With the long placeholder format, those are e.g. "{DATE}, {TIME}" for English and "{DATE}{TIME}" for Japanese.
  • An English formatted date-time could be "Dec 10, 2010, 3:59:49 PM".
There are four formats (full, long, medium, short), but usually these are all the same. The only time they would be different for your language is if there was some special placeholder in the long form, such as "{DATE} 'at' {TIME}" for the long form, so that a formatted date would read like "Friday, December 10, 2010 at 3:59:49 PM Pacific Standard Time".

Flexible - Append 

The flexible append format for Timezone is used to compose a 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, and with some fields in the second part omitted. The way this pattern is used is that the part up to the first repeated field is formatted with the first date, and the remainder is formatted with the second date. The first repeated field is marked with red in the examples below.

Interval Formatting

Format PatternDate 1Date 2Result
MMM d–d2008-09-132008-09-15Sept 13–15
MMMM–MMMM, yyyy2008-09-012008-11-31September-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.

Warning: each type of difference might need a different pattern.

For example:

Date 1Date 2Greatest DifferenceFormat PatternShares
2008-09-132009-09-15year (yMd)MMM d, yyyy – MMM d, yyyynothing
2008-09-012008-11-31month (Md)MMM d – MMM d, yyyyyear
2008-09-012008-09-05day (d)MMM d–d, yyyyyear and month