Dates and timezones

Date formatting and timezone adjustment is achieved in a similar fashion to translation.

Each date to be localized is held in a single element, such as a span. A data-l10n-date attribute holds the following, separated by commas:

  • The underlying system date or timestamp that the element represents. This should be in ISO 8601 format, i.e. yyyy-mm-dd or yyyy-mm-ddThh:mm:ss (seconds must be given even if they are not then shown). This should be the local date of the system, not necessarily UTC.
  • A generic style - short, medium, long or full. If a timestamp is being converted, can be given as dateStyle/timeStyle. If not given, medium/short is assumed, which is the most readable (it tends to give month names, and times to the nearest minute).
  • Whether the date should be converted to a local timezone, indicated by the word "local".

The date formatting follows the same language codes used for languages. The timezone adjustment uses the Time zone name property for the user.

If the input date is a date, only date formatting is performed. If it is a timestamp, full date and time formatting is performed. The local option has no effect unless a time portion is given.


<span data-l10n-date="2016-05-07,short">7 May 2016</span>

In en-US, this would become.

<span data-l10n-date="2016-05-07,short">05/07/16</span>

If the date cannot be formatted (e.g. because there is no formatting information for that language), then the element is unchanged.