intldate

Date formatting for gleam_time powered by JavaScript’s Intl.DateTimeFormat().

This module provides a type-safe wrapper around the Intl.DateTimeFormat API, allowing you to format dates and times according to locale-specific conventions.

Only works for JavaScript runtime

Types

DateTimeFormatConfig

</>

Configuration for date/time formatting.

This type allows you to specify which date and time components to include in the formatted output and how they should be represented.

Create a new configuration with new() and customize it with the various with_* functions.

pub type DateTimeFormatConfig {
  DateTimeFormatConfig(
    locale_matcher: option.Option(LocaleMatcher),
    weekday: option.Option(Weekday),
    era: option.Option(Era),
    year: option.Option(Year),
    month: option.Option(Month),
    day: option.Option(Day),
    hour: option.Option(Hour),
    minute: option.Option(Minute),
    second: option.Option(Second),
    time_zone_name: option.Option(TimeZoneName),
    format_matcher: option.Option(FormatMatcher),
    hour12: option.Option(Bool),
  )
}

Constructors

DateTimeFormatConfig(
  locale_matcher: option.Option(LocaleMatcher),
  weekday: option.Option(Weekday),
  era: option.Option(Era),
  year: option.Option(Year),
  month: option.Option(Month),
  day: option.Option(Day),
  hour: option.Option(Hour),
  minute: option.Option(Minute),
  second: option.Option(Second),
  time_zone_name: option.Option(TimeZoneName),
  format_matcher: option.Option(FormatMatcher),
  hour12: option.Option(Bool),
)

Era

</>

The representation of the era.

EraLong: Full era name (e.g., “Anno Domini”, “après Jésus-Christ”)
EraShort: Abbreviated era name (e.g., “AD”, “ap. J.-C.”)
EraNarrow: Narrow era name (e.g., “A”, “ap. J.-C.”)

pub type Era {
  EraLong
  EraShort
  EraNarrow
}

Constructors

```
EraLong
```
```
EraShort
```
```
EraNarrow
```

FormatMatcher

</>

The format matching algorithm to use.

FormatMatcherBestFit: The runtime is allowed to choose the best format based on the requested components and the locale.
FormatMatcherBasic: Use a basic algorithm that prioritizes matching the requested components in order.

pub type FormatMatcher {
  FormatMatcherBestFit
  FormatMatcherBasic
}

Constructors

```
FormatMatcherBestFit
```
```
FormatMatcherBasic
```

LocaleMatcher

</>

The locale matching algorithm to use.

LocaleMatcherBestFit: The runtime is allowed to choose the best matching locale, potentially considering extension keys and other options.
LocaleMatcherLookup: Use the BCP 47 lookup algorithm to find the best matching locale.

pub type LocaleMatcher {
  LocaleMatcherBestFit
  LocaleMatcherLookup
}

Constructors

```
LocaleMatcherBestFit
```
```
LocaleMatcherLookup
```

Minute

</>

The representation of the minute.

MinuteNumeric: Numeric representation (e.g., “8”)
Minute2Digit: Two-digit numeric representation (e.g., “08”)

pub type Minute {
  MinuteNumeric
  Minute2Digit
}

Constructors

```
MinuteNumeric
```
```
Minute2Digit
```

Month

</>

The representation of the month.

MonthNumeric: Numeric representation (e.g., “2”)
Month2Digit: Two-digit numeric representation (e.g., “02”)
MonthLong: Full month name (e.g., “February”, “février”)
MonthShort: Abbreviated month name (e.g., “Feb”, “févr.”)
MonthNarrow: Narrow month name (e.g., “F”, “F”)

pub type Month {
  MonthNumeric
  Month2Digit
  MonthLong
  MonthShort
  MonthNarrow
}

Constructors

```
MonthNumeric
```
```
Month2Digit
```
```
MonthLong
```
```
MonthShort
```
```
MonthNarrow
```

Second

</>

The representation of the second.

SecondNumeric: Numeric representation (e.g., “3”)
Second2Digit: Two-digit numeric representation (e.g., “03”)

pub type Second {
  SecondNumeric
  Second2Digit
}

Constructors

```
SecondNumeric
```
```
Second2Digit
```

TimeZoneName

</>

The localized representation of the time zone name.

TimeZoneNameShort: Short time zone name (e.g., “EST”, “PST”)
TimeZoneNameLong: Long time zone name (e.g., “Eastern Standard Time”)
TimeZoneNameShortOffset: Short GMT offset (e.g., “GMT+9”)
TimeZoneNameLongOffset: Long GMT offset (e.g., “GMT+09:00”)
TimeZoneNameShortGeneric: Short generic non-location format (e.g., “ET”, “PT”)
TimeZoneNameLongGeneric: Long generic non-location format (e.g., “Eastern Time”)

pub type TimeZoneName {
  TimeZoneNameShort
  TimeZoneNameLong
  TimeZoneNameShortOffset
  TimeZoneNameLongOffset
  TimeZoneNameShortGeneric
  TimeZoneNameLongGeneric
}

Constructors

```
TimeZoneNameShort
```
```
TimeZoneNameLong
```
```
TimeZoneNameShortOffset
```
```
TimeZoneNameLongOffset
```
```
TimeZoneNameShortGeneric
```
```
TimeZoneNameLongGeneric
```

Weekday

</>

The representation of the weekday.

WeekdayLong: Full weekday name (e.g., “Monday”, “lundi”)
WeekdayShort: Abbreviated weekday name (e.g., “Mon”, “lun”)
WeekdayNarrow: Narrow weekday name (e.g., “M”, “L”)

pub type Weekday {
  WeekdayLong
  WeekdayShort
  WeekdayNarrow
}

Constructors

```
WeekdayLong
```
```
WeekdayShort
```
```
WeekdayNarrow
```

Values

format

</>

pub fn format(
  date date: timestamp.Timestamp,
  time_zone time_zone: option.Option(String),
  locale locale: option.Option(String),
  config config: DateTimeFormatConfig,
) -> String

Format a timestamp according to the specified locale and configuration.

Parameters

date: The timestamp to format
time_zone: The time zone to use (IANA time zone name like “America/New_York”). If None, uses the system’s local time zone.
locale: The locale to use for formatting (BCP 47 language tag like “en-US”, “fr-FR”). If None, uses the system’s default locale.
config: The configuration object specifying which date/time components to include

Why Timestamp Instead of Calendar?

This function depends directly on the timestamp module and not calendar from gleam_time because Calendar represents a day and time separately without any timezone information, and the built-in timestamp to calendar conversion in gleam_time does not have complete support for time zones as described by IANA. Therefore, it can only represent time zones as offsets and does not take countries with daylight saving time into account. Since Intl.DateTimeFormat works directly with a date in UTC and uses the browser internals to resolve the time zone display, it is more logical to use a timestamp for this purpose.

Example

import gleam/option
import gleam/time/timestamp
import intldate

let assert Ok(date) = timestamp.parse_rfc3339("2026-02-24T17:48:22+04:00")

intldate.format(
  date:,
  time_zone: option.Some("Indian/Reunion"),
  locale: option.Some("fr-FR"),
  config: intldate.new()
    |> intldate.with_weekday(intldate.WeekdayLong)
    |> intldate.with_year(intldate.YearNumeric)
    |> intldate.with_month(intldate.MonthLong)
    |> intldate.with_day(intldate.DayNumeric)
    |> intldate.with_hour(intldate.HourNumeric)
    |> intldate.with_minute(intldate.MinuteNumeric),
)
// -> "mardi 24 février 2026 à 17:48"

new

</>

pub fn new() -> DateTimeFormatConfig

Create a new date/time format configuration with all options unset.

Use the various with_* functions to customize the configuration.

Example

intldate.new()
  |> intldate.with_year(intldate.YearNumeric)
  |> intldate.with_month(intldate.MonthLong)
  |> intldate.with_day(intldate.DayNumeric)

with_day

</>

pub fn with_day(
  config: DateTimeFormatConfig,
  day: Day,
) -> DateTimeFormatConfig

Set the representation of the day.

with_era

</>

pub fn with_era(
  config: DateTimeFormatConfig,
  era: Era,
) -> DateTimeFormatConfig

Set the representation of the era.

with_format_matcher

</>

pub fn with_format_matcher(
  config: DateTimeFormatConfig,
  format_matcher: FormatMatcher,
) -> DateTimeFormatConfig

Set the format matching algorithm.

The format matcher determines how the runtime selects the best format pattern based on the requested components and the locale.

with_hour

</>

pub fn with_hour(
  config: DateTimeFormatConfig,
  hour: Hour,
) -> DateTimeFormatConfig

Set the representation of the hour.

with_hour12

</>

pub fn with_hour12(
  config: DateTimeFormatConfig,
  hour12: Bool,
) -> DateTimeFormatConfig

Set whether to use 12-hour time format.

True: Use 12-hour format with AM/PM (e.g., “5:48 PM”)
False: Use 24-hour format (e.g., “17:48”)

If not set, the hour format is determined by the locale.

with_locale_matcher

</>

pub fn with_locale_matcher(
  config: DateTimeFormatConfig,
  locale_matcher: LocaleMatcher,
) -> DateTimeFormatConfig

Set the locale matching algorithm.

The locale matcher determines how the runtime selects the best matching locale when the exact locale you requested isn’t available.

with_minute

</>

pub fn with_minute(
  config: DateTimeFormatConfig,
  minute: Minute,
) -> DateTimeFormatConfig

Set the representation of the minute.

with_month

</>

pub fn with_month(
  config: DateTimeFormatConfig,
  month: Month,
) -> DateTimeFormatConfig

Set the representation of the month.

with_second

</>

pub fn with_second(
  config: DateTimeFormatConfig,
  second: Second,
) -> DateTimeFormatConfig

Set the representation of the second.

with_time_zone_name

</>

pub fn with_time_zone_name(
  config: DateTimeFormatConfig,
  time_zone_name: TimeZoneName,
) -> DateTimeFormatConfig

Set the localized representation of the time zone name.

with_weekday

</>

pub fn with_weekday(
  config: DateTimeFormatConfig,
  weekday: Weekday,
) -> DateTimeFormatConfig

Set the representation of the weekday.

with_year

</>

pub fn with_year(
  config: DateTimeFormatConfig,
  year: Year,
) -> DateTimeFormatConfig

Set the representation of the year.