icu-datetime

This library is a wrapper around ICU4X' datetime formatting for Typst which provides internationalized formatting for dates, times, and timezones.

As the WASM bundle includes all localization data, it's quite large (about 8 MiB).

See nerixyz.github.io/icu-typ for a full API reference with more examples as well as a migration guide.

Example

#import "@preview/icu-datetime:0.2.2" as icu

#let day = datetime(
  year: 2024,
  month: 5,
  day: 31,
)
#let time = datetime(
  hour: 18,
  minute: 2,
  second: 23,
)
#let dt = datetime(
  year: 2024,
  month: 5,
  day: 31,
  hour: 18,
  minute: 2,
  second: 23,
)
#let tz = (offset: "-07", iana: "America/Los_Angeles")

= Date
#icu.fmt(day, locale: "km", date-fields: "YMDE") \
#icu.fmt(day, locale: "af", date-fields: "YMDE") \
#icu.fmt(day, locale: "za", date-fields: "YMDE") \

= Time
#icu.fmt(time, locale: "id", time-precision: "second") \
#icu.fmt(time, locale: "en", time-precision: "second") \
#icu.fmt(time, locale: "ga", time-precision: "second") \

= Date and Time
#icu.fmt(dt, locale: "ru", length: "long") \
#icu.fmt(dt, locale: "en-US", length: "long") \
#icu.fmt(dt, locale: "zh-Hans-CN", length: "long") \
#icu.fmt(dt, locale: "ar", length: "long") \
#icu.fmt(dt, locale: "fi", length: "long")

= Zone
#icu.fmt(
  datetime.today(), // to resolve the zone variant
  zone: tz,
  zone-style: "specific-long",
) \
#icu.fmt(
  datetime.today(),
  zone: tz,
  zone-style: "generic-short",
)

= Zoned Datetime
#let opts = (
  zone: tz,
  date-fields: "YMDE",
  time-precision: "second",
  length: "long",
)

#icu.fmt(dt, ..opts, zone-style: "generic-short") \
#icu.fmt(dt, ..opts, zone-style: "localized-offset-short", locale: "lv") \
#icu.fmt(dt, ..opts, zone-style: "exemplar-city", locale: "en-CA-u-hc-h23-ca-buddhist")

Locales must be Unicode Locale Identifiers.
Use locale-info(locale) to get information on how a locale is parsed.
Unicode extensions are supported, so you can, for example, set the hour cycle with hc-h12 or set the calendar with ca-buddhist (e.g. en-CA-u-hc-h24-ca-buddhist).

Documentation

Documentation can be found on nerixyz.github.io/icu-typ.

Using Locally

Download the latest release, unzip it to your local Typst packages, and use #import "@local/icu-datetime:0.2.0".

Building

To build the library, you need to have Rust, just, and wasm-opt installed.

just build
# to deploy the package locally, use `just deploy`

just example will build the example and symlink the release artifact to typst/icu-datetime.wasm.