Small Gleam helpers to make numbers, bytes, durations and lists human-friendly.
| Function | Description |
|---|---|
humanize.number/1 |
Compact numbers: 1_234 → "1.2K" |
humanize.number_with/3 |
Control decimals and DecimalSeparator (Dot or Comma) |
humanize.bytes_decimal/1, humanize.bytes_binary/1 |
File sizes (1000 vs 1024). Supports up to YB/YiB (decimal and binary, respectively). |
humanize.duration/1, humanize.duration_precise/1 |
Human readable durations |
humanize.list/1, humanize.list_locale/3, humanize.list_with_oxford/1 |
Natural language lists |
humanize.ordinal/1 |
Ordinal suffixes (1st, 2nd, 3rd, ...) |
humanize.time_ago_unix/5 |
Humanize a Unix timestamp relative to now (locale-aware) |
humanize.time_ago_unix_with_overrides/6 |
Same as above but accepts runtime locale overrides |
humanize.time_ago_timestamp/5 |
Like time_ago_unix but takes gleam_time/timestamp.Timestamp values |
humanize.time_ago_timestamp_with_overrides/6 |
Timestamp version with locale overrides |
humanize.make_locale/6 |
Construct a custom locale entry to pass as an override |
internals/locales.gleam |
Internal table with built-in locales (it, en, es, fr, de, pt) |
Note: the library now depends on gleam_time when using the
time_ago_timestamp*APIs.
import humanize
humanize.number(1_234) // "1.2K"
humanize.number_with(1_234_567, 2, humanize.Comma) // "1,23M"
humanize.bytes_decimal(1_536_000) // "1.5 MB"
// Large units
humanize.bytes_decimal(1_000_000_000_000_000) // "1 PB"
humanize.bytes_binary(1_125_899_906_842_624) // "1 PiB"
humanize.duration(125) // "2 minutes"
humanize.duration_precise(125) // "2 minutes, 5 seconds"
humanize.list(["a", "b", "c"]) // "a, b and c"
humanize.list_with_oxford(["a", "b", "c"]) // "a, b, and c"
humanize.list_with_ampersand(["a", "b", "c"]) // "a, b & c"
humanize.ordinal(23) // "23rd"import humanize
// Basic lookup using built-in locales
humanize.time_ago_unix(1_620_000_000, 1_620_000_360, "en", False, 1) // "6 minutes ago"
// with gleam_time timestamps (requires adding `gleam_time` deps)
import gleam/time/timestamp
humanize.time_ago_timestamp(
timestamp.from_unix_seconds(1_620_000_000),
timestamp.from_unix_seconds(1_620_000_360),
"en",
False,
1,
) // "6 minutes ago"
// For custom locale examples see the "Locale overrides" section below.
// Edge cases and behaviour near rounding boundaries
humanize.percent_with(12, 1, humanize.Dot, True) // "12.0 %"
humanize.number(999) // "999"
humanize.number(1000) // "1.0K"
humanize.number_with(999_950, 1, humanize.Dot) // promoted to "1.0M"
humanize.bytes_decimal(999) // "999 B"
humanize.bytes_decimal(1000) // "1 KB"
humanize.bytes_decimal(999_950) // promoted to "1.0 MB"
// Override example: future and precise
let my_units = [#(3600, "hX", "hX"), #(60, "minX", "minX"), #(1, "sX", "sX")]
let my_locale = humanize.make_locale("xx", "agoX", "inX", "nowX", " & ", my_units)
// future
humanize.time_ago_unix_with_overrides(1_000_120, 1_000_000, "xx", [my_locale], False, 1) // "inX 2 minX"
// precise
humanize.time_ago_unix_with_overrides(1_000_000 - { 3600 + 120 }, 1_000_000, "xx", [my_locale], True, 2) // "1 hX & 2 minX agoX"You can construct custom locale entries and pass them as overrides to time_ago_unix_with_overrides.
| Parameter | Type | Description |
|---|---|---|
code |
String |
Identifier code for the locale (e.g. it-roma). |
ago |
String |
Suffix for past tense (e.g. ago, fa). |
in_ |
String |
Prefix for future tense (e.g. in, tra). |
nowv |
String |
Text for the "now" case (e.g. now, adesso). |
conj |
String |
Conjunction used between units (e.g. and, e, &). |
units |
List(#(Int, String, String)) |
List of tuples (seconds, singular, plural), ordered from largest to smallest (years → months → ... → seconds). |
The library helper is:
pub fn make_locale(
code: String,
ago: String,
in_: String,
nowv: String,
conj: String,
units: List(#(Int, String, String)),
) -> #(String, LocaleData)Quick example:
let my_units = [#(3600, "ora_custom", "ore_custom"), #(60, "minuto_custom", "minuti_custom"), #(1, "secondo_custom", "secondi_custom")]
let my_locale = humanize.make_locale("it-roma", "fa", "tra", "adesso", " e ", my_units)
// Pass the override list to the call
humanize.time_ago_unix_with_overrides(past, now, "it-roma", [my_locale], False, 1)| Example | Result |
|---|---|
humanize.percent(50) |
"50%" |
humanize.percent_with(12, 1, humanize.Dot, False) |
"12.0%" |
humanize.percent_ratio(1, 3, 2, humanize.Comma) |
"33,33%" |
humanize.percent_ratio(1, 6, 1, humanize.Dot) |
"16.7%" |
This project is available under the MIT License. See LICENSE.
Run locally:
gleam run # Run the project
gleam test # Run the testsMade with Gleam 💜