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:

[!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.

Add to your dependencies:

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

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

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

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

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

Anything marked with a 🧪 means that the feature is experimental: it could be changed or dropped at any time. An opt-in annotation is required to use such features.

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

These should be used when you want to localize 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.

These should be used whenever you always want to localize a date/time object in a relative way. Avoid concatenating values from these localizers, always use the output of a localizer in full.

All these functions return a TickingValue, class that holds the localized value and a "next tick" duration, which indicates for how long the value is valid for. When the "next tick" expires, it means that the localized value now needs recomputation.

Most of these classes implement PolyglotReferenceValueLocalizer, which allows to pass in a reference point (usually the current time) to use for relative localization. As a convenience, the localizeAsFlow extension function will return a Flow that automatically emits a new relative value when it is due.