Date Formatting in ICU Messages

Locale-Aware Date and Time Formatting

The date and time argument types in ICU MessageFormat format date and time values according to the conventions of the target locale -- including month names, date order (MM/DD vs DD/MM), and time format (12h vs 24h).

Date Styles

ICU provides four built-in date styles:

{today, date, short}    -> 1/15/24 (en-US) / 15.01.24 (de-DE)
{today, date, medium}   -> Jan 15, 2024 (en-US) / 15.01.2024 (de-DE)
{today, date, long}     -> January 15, 2024 (en-US) / 15. Januar 2024 (de-DE)
{today, date, full}     -> Monday, January 15, 2024 (en-US) / Montag, 15. Januar 2024 (de-DE)

Time Styles

{now, time, short}      -> 3:30 PM (en-US) / 15:30 (de-DE)
{now, time, medium}     -> 3:30:00 PM (en-US) / 15:30:00 (de-DE)
{now, time, long}       -> 3:30:00 PM EST (en-US) / 15:30:00 MEZ (de-DE)
{now, time, full}       -> 3:30:00 PM Eastern Standard Time (en-US)

Japanese Date Formatting

Japanese dates follow year-month-day order and can include era names:

{today, date, short}    -> 2024/01/15
{today, date, medium}   -> 2024/01/15
{today, date, long}     -> 2024年1月15日
{today, date, full}     -> 2024年1月15日月曜日

Combining Date and Time

To display both date and time, use separate arguments:

Meeting on {meetingDate, date, long} at {meetingDate, time, short}.

Output (en-US): "Meeting on January 15, 2024 at 3:30 PM." Output (de-DE): "Meeting on 15. Januar 2024 at 15:30."

Note that the same variable can be used for both date and time formatting.

Relative Dates

Standard ICU MessageFormat does not include relative date formatting ("3 days ago", "in 2 hours"). For relative dates, use the Intl.RelativeTimeFormat API in JavaScript or library-specific extensions.

In Context

{userName} last logged in on {lastLogin, date, medium} at {lastLogin, time, short}.

With userName="Alice" and lastLogin=2024-01-15T15:30:00:

• en-US: "Alice last logged in on Jan 15, 2024 at 3:30 PM."
• ja-JP: "Alice last logged in on 2024/01/15 at 15:30."

Why Let ICU Handle Dates?

Date formats vary dramatically across locales:

• US: Month/Day/Year (01/15/2024)
• UK/Europe: Day/Month/Year (15/01/2024)
• Japan: Year/Month/Day (2024/01/15)
• ISO: Year-Month-Day (2024-01-15)

Hard-coding a date format guarantees confusion for international users. ICU date formatting ensures dates are always presented in the locally expected format.