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:

All other platforms are unsupported at the moment.

¹ As not all features are supported by all localization platforms, some small amount of locale data is bundled with the library itself to backfill the missing APIs.

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

This library uses semantic versioning. At the current 0.y stage, expect minor breaking changes at every increment of y. Full API stability guarantees will come with the 1.0 milestone.

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.

Absolute localizers can be split into two sub-categories: zoned and local. Local localizers handle just local values such as LocalDate, where no time zone information is present. Zoned localizers handle an instance of Zoned, which holds the data in conjunction with a TimeZone.

Note: all zoned localizers always have the timezone name in their output. If you do not wish to show it to the user, you should convert your date to the appropriate local value and use a local localizer instead.

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.

Dynamic localizers provide a convenient way to dynamically choose between a relative and absolute localization depending on the distance from the reference of the value.

They all re-use the above absolute and relative localizers, and they all implement PolyglotReferenceValueLocalizer.