Data formatting utilities for converting relative time, duration, file sizes, and numbers into human-readable formats. Supports localization with multiple languages and auto-switching to larger units for precision.
A small set of data formatting utilities for Kotlin Multiplatform (KMP).
The library depends on kotlinx-datetime.
The library is published to Maven Central.
Note: HumanReadable 1.12+ requires kotlinx-datetime 0.7+, see https://github.com/jacobras/Human-Readable/issues/148.
dependencies {
implementation("nl.jacobras:Human-Readable:2.0.0")
}
An interactive demo is available at https://jacobras.github.io/Human-Readable/.
HumanReadable.timeAgo(now - 134.minutes) // "2 hours ago"
HumanReadable.timeAgo(now + 8.minutes) // "in 8 minutes"
HumanReadable.duration(5.seconds) // "5 seconds"
HumanReadable.duration(7.days) // "1 week"
HumanReadable.duration(544.hours) // "3 weeks"
The formatter switches to a bigger unit (minute, hour, day, ...) as soon as it can.
There are a number of configuration options available for both timeAgo() and duration().
HumanReadable.timeAgo(
instant = now - 134.minutes,
formatting = FormatStyle(
date = FormatStyle.Date.Long, // or Short: "1 hr, 50 min" or Narrow: "1h 50m"
time = FormatStyle.Time.Regular,
indicateApproximation =
),
parts = PartsConfig(
max = ,
smallestDuration = minutes,
subpartCutOffs = mapOf(TimeUnit.Hours to ),
onlyConsecutiveParts =
),
units = setOf(TimeUnit.Days),
rounding = Rounding.HalfUp
)
The above parameters can be set globally via HumanReadable.config.time. Passed-in parameters take preference over the
global configuration.
HumanReadable.config.time.units = setOf(TimeUnit.Hours)
HumanReadable.timeAgo(now - 2.days) // "48 hours ago"
Visit the interactive demo to see more examples in action.
File size formatting uses base 1024.
HumanReadable.fileSize(333) // "333 B"
HumanReadable.fileSize(2_048, decimals = 1) // "2.0 kB"
HumanReadable.fileSize(21_947_282_882, decimals = 2) // "20.44 GB" in English / "20.44 Go" in French
Available since version 1.8, localised since 1.10.
HumanReadable.abbreviation(3_000) // "3K"
HumanReadable.abbreviation(500_000) // "500K"
HumanReadable.abbreviation(2_500_000, decimals = 1) // "2.5M"
Available since version 1.10.
// English
HumanReadable.number(1_000_000.34) // "1,000,000.34"
// French
HumanReadable.number(1_000_000.34) // "1 000 000.34"
// Dutch
HumanReadable.number(1_000_000.34) // "1.000.000,34"
Available since version 1.11.
// Metric examples
HumanReadable.distance(value = 956, unit = DistanceUnit.Meter) // "956 m"
HumanReadable.distance(value = 1534, unit = DistanceUnit.Meter) // "1.5 km"
HumanReadable.distance(value = 5400, unit = DistanceUnit.Meter, decimals = 2) // "5.40 km"
// Imperial examples
HumanReadable.distance(value = 5200, unit = DistanceUnit.Foot)
HumanReadable.distance(value = , unit = DistanceUnit.Foot)
HumanReadable.distance(value = , unit = DistanceUnit.Foot, decimals = )
Note: numbers in meters and feet are always formatted with zero decimals. The passed in number of decimals is only used for the larger units kilometers and miles.
The library uses an internal i18n mechanism. It detects the current locale by default, but it's changeable at
runtime via HumanReadable.config.languageTag:
HumanReadable.timeAgo(instant) // "3 days ago"
HumanReadable.config.languageTag = "nl"
HumanReadable.timeAgo(instant) // "3 dagen geleden"
HumanReadable.config.languageTag = "fr"
HumanReadable.timeAgo(instant) // "il y a 3 jours"
If the requested locale is not supported, the library will fall back to HumanReadable.fallbackLanguageTag, which by
default is set to English.
Missing a language? Feel free to open an issue about it. Or, add it yourself:
src/commonMain/kotlin/nl/jacobras/humanreadable/i18n/translationsXxStrings.kt (where Xx is
the language code). Follow the
example of other translations.Follow the Unicode spec at https://st.unicode.org/cldr-apps/v#/en/Duration/ or https://github.com/unicode-org/cldr-json/blob/main/cldr-json/cldr-units-full/main/en/units.json, if you prefer the JSON format.
translations map in
src/commonMain/kotlin/nl/jacobras/humanreadable/i18n/translations.kt.Surfaced from shared tags and platforms — no rankings paid for.