datetime-polyglot

Multiplatform localization library for Kotlin date/time objects, either from stdlib or kotlinx-datetime.

The library uses a different localization backend depending on the platform:

Platform	Localization backend
JVM	ICU4J
Android	android.icu
JS (Browser + Node)	Intl
WASM (Browser)	Intl

Note

While the library strives to provide a uniform API that mostly returns consistent values, subtle differences between various localization backends exist. You should not rely on localized strings being identical between platforms.

Setup

Add to your dependencies:

dependencies {
    implementation("dev.mmauro:datetime-polyglot:<version>")
}

See latest version in badge above or look directly at Maven Central page.

Using the SNAPSHOT build

Snapshot builds are published on every commit in mainline.

To use, add in your settings.gradle.kts:

dependencyResolutionManagement {
    repositories {
        maven("https://central.sonatype.com/repository/maven-snapshots")
    }
}

Then add to your dependencies:

dependencies {
    implementation("dev.mmauro:datetime-polyglot:<version>")
}

See latest version in badge above or look at maven-metadata.xml.

Features

In general, each type of data that can be localized will have:

1. An options class that defines the settings for localization
2. A localizer class that accepts the options and a locale as constructor parameters
3. A utility localize() extension function on the data type that hides the construction of the localizer class

Standalone date/time attributes

These should be used when the component to format is standalone (e.g. calendar header), and should not be mixed with other date components.

Data type	Localizer class / Extension function	Examples
Month	MonthLocalizer Month.localize()	January Jan J 1
DayOfWeek	DayOfWeekLocalizer DayOfWeek.localize()	Monday Mon Mo M
TimeZone	TimeZoneLocalizer TimeZone.localize()	America/Los_Angeles PT Pacific Time Los Angeles Time

Absolute date/time

This should be used when you want to format an absolute date/time object to show the user. Avoid concatenating values from these localizers, always use the output of a localizer in full.

If you need only partial information, convert first to the appropriate type and then localize that. For instance, if you have an Instant but are only interested in the time component, you should first convert to LocalDateTime, then get the LocalTime part, and finally localize it.

Data type	Localizer class / Extension function	Examples
Zoned<Instant>	ZonedInstantLocalizer ZonedInstantLocalizer.localize()	1/8/26 9:05 PM PST Jan 8, 2026, 9 at night Pacific Daylight Time January 8, 2026 at 9:31:45 PM GMT-07:00 Thursday, January 8, 2026 at 21:05 Los Angeles Time
LocalDateTime	LocalDateTimeLocalizer LocalDateTime.localize()	1/8/26 9:05 PM Jan 8, 2026, 9 at night January 8, 2026 at 9:31:45 PM Thursday, January 8, 2026 at 21:05
LocalDate	LocalDateLocalizer LocalDate.localize()	1/8/26 Jan 8, 2026 January 8, 2026 Thursday, January 8, 2026
LocalTime	LocalTimeLocalizer LocalTime.localize()	9:05 PM 9:05:08 PM 21:05 21:05:08.123 9 at night
YearMonth	YearMonthLocalizer YearMonth.localize()	January 2026 Jan 26 01/2026
Year (Int)	YearLocalizer No extension function	2026 26 2026 AD 2026 Anno Domini