Date/Time | Foundations

Overview

1. General notes

Our source language is EN-US (US English)
Remember to hand off designs to the Localization team
- Confluence Localization Operations Team / Slack #prj-translations

2. Engineering notes

Use the Intl browser API for localization. This will automatically localize dates and times into the correct format
Where manually-created content needs to be formatted correctly in the code, use the relevant guidelines shown in this documentation
Below is an example of using the Intl API, with more examples embedded in the previews on this page

{
  new Intl.DateTimeFormat('en-us', {
    month: 'short',
    day: 'numeric',
  }).format(new Date(2024, 3, 6))
}

{
  new Intl.DateTimeFormat('en-us', {
    month: 'short',
    day: 'numeric',
  }).format(new Date(2024, 3, 6))
}

Dates, months and years

<ul>
  <li>
    See website for details. Exceptions apply. Offer expires{' '}
    {new Intl.DateTimeFormat('en-us', {
      month: 'long',
      day: 'numeric',
      year: 'numeric',
    }).format(new Date(2024, 3, 6))}
  </li>
  <li>
    See website for details. Exceptions apply. Offer expires{' '}
    {new Intl.DateTimeFormat('en-us', {
      month: 'short',
      day: 'numeric',
      year: 'numeric',
    }).format(new Date(2024, 3, 6))}
  </li>
</ul>

<ul>
  <li>
    See website for details. Exceptions apply. Offer expires{' '}
    {new Intl.DateTimeFormat('en-us', {
      month: 'long',
      day: 'numeric',
      year: 'numeric',
    }).format(new Date(2024, 3, 6))}
  </li>
  <li>
    See website for details. Exceptions apply. Offer expires{' '}
    {new Intl.DateTimeFormat('en-us', {
      month: 'short',
      day: 'numeric',
      year: 'numeric',
    }).format(new Date(2024, 3, 6))}
  </li>
</ul>

Sequence and formatting

Always include month and date
Write the month in full wherever possible; only abbreviate when space is limited. Consider revisiting the design before abbreviating
Write the date as a number, not a full word or an ordinal (e.g. 8th, 3rd)
Display the year if there is a high likelihood the date will be referenced outside of the current calendar year
- For example, invoice billing dates that occur outside current calendar year
Don’t use the format mm/dd/yyyy or dd/mm/yyyy
Optional: If it's likely the customer will see the information within the same day or the next calendar day, you can use “today” or “tomorrow” instead of the date

When you only include month and day: use uppercase Month followed by a space, then the date
- [Month][space][date]
- For example: April 1
When you include month, date and year: use uppercase Month followed by a space, then the date, then a comma followed by a space, then the year
- [Month][space][date][comma][space][year]
- For example: April 1, 2024

March 8
March 8, 2024
Mar 8, 2024

DON'T

March eight
March eighth 2024
March 8th 2024
5/8/2024

Abbreviations (days and months)

Spell out full words for days and months when space allows. Why? Full words are clearer
Only abbreviate when space is limited
Be consistent when using abbreviations
Don’t include a period/full stop after an abbreviated month

If you have to abbreviate, always use a 3-letter abbreviation

Days of the week abbreviations

Mon | Tue | Wed | Thu | Fri | Sat | Sun

Months of the year abbreviations

Jan | Feb | Mar | Apr | n/a (May) | Jun | Jul | Aug | Sep | Oct | Nov | Dec

Date ranges

<ul>
  <li>
    {new Intl.DateTimeFormat('en-us', {
      month: 'long',
      day: 'numeric',
    }).formatRange(new Date(2024, 9, 2), new Date(2024, 10, 23))}
  </li>
  <li>
    {new Intl.DateTimeFormat('en-us', {
      month: 'long',
      day: 'numeric',
    }).formatRange(new Date(2024, 10, 2), new Date(2024, 10, 23))}
  </li>
  <li>
    The order was placed on{' '}
    {new Intl.DateTimeFormat('en-us', {
      month: 'short',
      day: 'numeric',
      year: 'numeric',
    }).format(new Date(2019, 0, 3))}
  </li>
  <li>
    The sale runs in the next calendar year from
    {new Intl.DateTimeFormat('en-us', {
      month: 'short',
      day: 'numeric',
      year: 'numeric',
    }).formatRange(
      new Date(new Date().getFullYear() + 1, 0, 3),
      new Date(new Date().getFullYear() + 1, 1, 23),
    )}
  </li>
</ul>

<ul>
  <li>
    {new Intl.DateTimeFormat('en-us', {
      month: 'long',
      day: 'numeric',
    }).formatRange(new Date(2024, 9, 2), new Date(2024, 10, 23))}
  </li>
  <li>
    {new Intl.DateTimeFormat('en-us', {
      month: 'long',
      day: 'numeric',
    }).formatRange(new Date(2024, 10, 2), new Date(2024, 10, 23))}
  </li>
  <li>
    The order was placed on{' '}
    {new Intl.DateTimeFormat('en-us', {
      month: 'short',
      day: 'numeric',
      year: 'numeric',
    }).format(new Date(2019, 0, 3))}
  </li>
  <li>
    The sale runs in the next calendar year from
    {new Intl.DateTimeFormat('en-us', {
      month: 'short',
      day: 'numeric',
      year: 'numeric',
    }).formatRange(
      new Date(new Date().getFullYear() + 1, 0, 3),
      new Date(new Date().getFullYear() + 1, 1, 23),
    )}
  </li>
</ul>

Sequence and formatting

If the date range is in the same month, do not repeat the month
If the date range is in the same year, do not repeat the year

In a full sentence, write out “to” between a range of times
If space is tight, “to” can be replaced with an en dash “–”
Don’t insert a space before or after the en dash
Tip: On a Mac, keyboard shortcut “option + dash (-)” creates an en dash

The sale runs March 29 to April 2, 2024
March 29 to April 3
The sale runs March 29-April 2, 2024

DON'T

The sale runs March 29 -- April 2, 2024
March 29 until April 3

Time

<ul>
  <li>
    {new Intl.DateTimeFormat('en-us', {
      timeZone: 'America/New_York',
      hour: 'numeric',
      minute: '2-digit',
    }).format(new Date())}{' '}
    (EN-US, America/New_York)
  </li>
  <li>
    {new Intl.DateTimeFormat('en-us', {
      timeZone: 'America/New_York',
      hour: 'numeric',
      minute: '2-digit',
      timeZoneName: 'short',
    }).format(new Date())}{' '}
    (EN-US, America/New_York)
  </li>
  <li>
    {new Intl.DateTimeFormat('en-ie', {
      timeZone: 'Europe/Dublin',
      hour: 'numeric',
      minute: '2-digit',
    }).format(new Date())}{' '}
    (EN-IE, Europe/Dublin)
  </li>
  <li>
    {new Intl.DateTimeFormat('en-ie', {
      timeZone: 'Europe/Dublin',
      hour: 'numeric',
      minute: '2-digit',
      timeZoneName: 'short',
    }).format(new Date())}{' '}
    (EN-UE, Europe/Dublin)
  </li>
  <li>
    {new Intl.DateTimeFormat('en-us', {
      timeZone: 'America/New_York',
      month: 'long',
      day: 'numeric',
      year: 'numeric',
      hour: 'numeric',
      minute: '2-digit',
    }).format(new Date())}
  </li>
  <li>
    {new Intl.DateTimeFormat('en-us', {
      timeZone: 'America/New_York',
      month: 'short',
      day: 'numeric',
      year: 'numeric',
      hour: 'numeric',
      minute: '2-digit',
    }).format(new Date())}
  </li>
  <li>
    {new Intl.DateTimeFormat('fr-fr', {
      timeZone: 'Europe/Paris',
      month: 'long',
      day: 'numeric',
      year: 'numeric',
      hour: 'numeric',
      minute: '2-digit',
    }).format(new Date())}{' '}
    (fr-fr, Europe/Paris)
  </li>
  <li>
    {new Intl.DateTimeFormat('fr-fr', {
      timeZone: 'Europe/Paris',
      month: 'short',
      day: 'numeric',
      year: 'numeric',
      hour: 'numeric',
      minute: '2-digit',
    }).format(new Date())}{' '}
    (fr-fr, Europe/Paris)
  </li>
</ul>

<ul>
  <li>
    {new Intl.DateTimeFormat('en-us', {
      timeZone: 'America/New_York',
      hour: 'numeric',
      minute: '2-digit',
    }).format(new Date())}{' '}
    (EN-US, America/New_York)
  </li>
  <li>
    {new Intl.DateTimeFormat('en-us', {
      timeZone: 'America/New_York',
      hour: 'numeric',
      minute: '2-digit',
      timeZoneName: 'short',
    }).format(new Date())}{' '}
    (EN-US, America/New_York)
  </li>
  <li>
    {new Intl.DateTimeFormat('en-ie', {
      timeZone: 'Europe/Dublin',
      hour: 'numeric',
      minute: '2-digit',
    }).format(new Date())}{' '}
    (EN-IE, Europe/Dublin)
  </li>
  <li>
    {new Intl.DateTimeFormat('en-ie', {
      timeZone: 'Europe/Dublin',
      hour: 'numeric',
      minute: '2-digit',
      timeZoneName: 'short',
    }).format(new Date())}{' '}
    (EN-UE, Europe/Dublin)
  </li>
  <li>
    {new Intl.DateTimeFormat('en-us', {
      timeZone: 'America/New_York',
      month: 'long',
      day: 'numeric',
      year: 'numeric',
      hour: 'numeric',
      minute: '2-digit',
    }).format(new Date())}
  </li>
  <li>
    {new Intl.DateTimeFormat('en-us', {
      timeZone: 'America/New_York',
      month: 'short',
      day: 'numeric',
      year: 'numeric',
      hour: 'numeric',
      minute: '2-digit',
    }).format(new Date())}
  </li>
  <li>
    {new Intl.DateTimeFormat('fr-fr', {
      timeZone: 'Europe/Paris',
      month: 'long',
      day: 'numeric',
      year: 'numeric',
      hour: 'numeric',
      minute: '2-digit',
    }).format(new Date())}{' '}
    (fr-fr, Europe/Paris)
  </li>
  <li>
    {new Intl.DateTimeFormat('fr-fr', {
      timeZone: 'Europe/Paris',
      month: 'short',
      day: 'numeric',
      year: 'numeric',
      hour: 'numeric',
      minute: '2-digit',
    }).format(new Date())}{' '}
    (fr-fr, Europe/Paris)
  </li>
</ul>

Sequence and formatting

Engineering notes

Follow the local convention for style, punctuation, and sequence.
- For the US, that means 12-hour time with AM/PM
- For most European locales, use 24-hour time
Always display time in the local timezone
Use the Intl browser API

Use the 12-hour clock. Include AM or PM
Write AM and PM uppercase
Don’t include periods/full stops
Insert a space between the numeral and "AM" or "PM"
Don't use the 24-hour clock (also known as military time; 19:30, 22:15)
Use a colon to separate hours from minutes (for example 2:30 AM)
Times are written without a starting “0”
Always include hours and minutes (for example, “7:00 PM”, not “7 PM”).
When date and time are used together, follow local conventions for separating the two. Follow the date guidelines to determine whether or not to abbreviate the month

7:30 AM
1:30 PM
11:30 PM
9:00 AM
7:10 AM

DON'T

7:30a.m.
13:30
11:30 p.m. or 11:30PM
9PM
07:10 AM

Time ranges

<ul>
  <li>
    {new Intl.DateTimeFormat('en-us', {
      timeZone: 'America/New_York',
      hour: 'numeric',
      minute: '2-digit',
    }).formatRange(
      new Date(2024, 11, 2, 8, 0, 0),
      new Date(2024, 11, 2, 13, 0, 0),
    )}
  </li>
  <li>
    {new Intl.DateTimeFormat('en-us', {
      timeZone: 'America/New_York',
      hour: 'numeric',
      minute: '2-digit',
      month: 'long',
      day: 'numeric',
    }).formatRange(
      new Date(2024, 11, 2, 8, 0, 0),
      new Date(2024, 11, 2, 9, 0, 0),
    )}
  </li>
  <li>
    {new Intl.DateTimeFormat('en-us', {
      timeZone: 'America/New_York',
      hour: 'numeric',
      minute: '2-digit',
      month: 'long',
      day: 'numeric',
    }).formatRange(
      new Date(2024, 11, 2, 8, 0, 0),
      new Date(2024, 11, 3, 13, 0, 0),
    )}
  </li>
</ul>

<ul>
  <li>
    {new Intl.DateTimeFormat('en-us', {
      timeZone: 'America/New_York',
      hour: 'numeric',
      minute: '2-digit',
    }).formatRange(
      new Date(2024, 11, 2, 8, 0, 0),
      new Date(2024, 11, 2, 13, 0, 0),
    )}
  </li>
  <li>
    {new Intl.DateTimeFormat('en-us', {
      timeZone: 'America/New_York',
      hour: 'numeric',
      minute: '2-digit',
      month: 'long',
      day: 'numeric',
    }).formatRange(
      new Date(2024, 11, 2, 8, 0, 0),
      new Date(2024, 11, 2, 9, 0, 0),
    )}
  </li>
  <li>
    {new Intl.DateTimeFormat('en-us', {
      timeZone: 'America/New_York',
      hour: 'numeric',
      minute: '2-digit',
      month: 'long',
      day: 'numeric',
    }).formatRange(
      new Date(2024, 11, 2, 8, 0, 0),
      new Date(2024, 11, 3, 13, 0, 0),
    )}
  </li>
</ul>

Sequence and formatting

Use a single AM or PM at the end of the range, if both times have the same AM or PM
- For example: 8:30–10:00 PM
Show an en dash “–” between a range of times
Don’t insert a space before or after the en dash
Tip: On a Mac, keyboard shortcut “option + dash (-)” creates an en dash

7:30–10:00 AM
9:30 AM–3:00 PM

DON'T

9:30 AM – 10:00 AM
6:30 PM – 10:30 PM

Date and time used together

When to use date, time, or both

It's nuanced and depends on the use case.

Include time and date wherever possible so it's explicitly clear which date we're referring to
If the date is not relevant in a specific context, it's OK to only include the time

Examples of using only date, only time, or both

CARE contact hours: Not date-specific, but would be something like "8AM-8PM, Monday to Friday"
Delivery window: In general people need to know the date, but if the delivery date is listed in a different content block on the same page, there’s no need to repeat date
Shipping date: If we know the projected shipping date but the time is unknown or not relevant, we'd only include the date
Sale ends time: In general this would need to include date, but there may be some use cases when the sale ends that same day, so that may be a use case for something like this: “Sale ends today at 11:59 PM”

Sequence and formatting

Date should come first followed by time
If date and time are used together, use a comma to separate the date from the time

March 8, 2024, 7:30 AM
March 8, 7:30 AM

DON'T

March 8 : 7:30 A.M.
March 8 • 7:30 a.m.
March 8, 2024. 7:30 a.m.