Why doesn't BIFF_LOCALE=en-NZ-u-hc-h24 for TZ=Pacific/Auckland use a 24 hour clock?

[passcod]

Following from the Guide...

let's say I'm in New Zealand:

$ env BIFF_LOCALE=en-NZ biff
Thu, 15/05/2025, 6:58:17 pm NZST

but I don't like the 12-hour clock:

$ env BIFF_LOCALE=en-NZ-u-hc-h24 biff
Thu, 15/05/2025, 6:58:19 pm NZST

uhhhh, what?

[BurntSushi]

TL;DR - Use BIFF_LOCALE=en-NZ-u-hc-h23 instead.

---

I actually wasn't sure which time zone identifier you were using, because that can impact localization. So I did:

$ biff tz list | xargs -n1 biff time in now | biff time fmt -f '%Q %Z' | rg NZST
Antarctica/McMurdo NZST
Antarctica/South_Pole NZST
NZ NZST
Pacific/Auckland NZST

I'm guessing you're in Pacific/Auckland? Here's a more reliable way to reproduce:

$ BIFF_LOCALE=en-NZ-u-hc-h24 TZ=Pacific/Auckland biff time fmt -f '%c' 2025-05-10T17:30
Sat, 10/05/2025, 5:30:00 pm NZST

$ BIFF_LOCALE=en-NZ-u-hc-h12 TZ=Pacific/Auckland biff time fmt -f '%c' 2025-05-10T17:30
Sat, 10/05/2025, 5:30:00 pm NZST

$ BIFF_LOCALE=en-NZ TZ=Pacific/Auckland biff time fmt -f '%c' 2025-05-10T17:30
Sat, 10/05/2025, 5:30:00 pm NZST

I'm not a locale expert, so I don't know if this is a bug in ICU4X or if this is a problem in how I'm using ICU4X. cc @sffc

For ICU4X, we'll need a Rust program using their library directly for this to be actionable for them I think. So I'll take my example from jiff-icu and adapt it to your specific use case. Here's the Cargo.toml:

[package]
publish = false
name = "jiff-icu-new-zealand-24hr"
version = "0.1.0"
edition = "2024"

[dependencies]
anyhow = "1.0.98"
icu = "2.0.0"
jiff = "0.2.13"
jiff-icu = "0.2.0"

[[bin]]
name = "jiff-icu-new-zealand-24hr"
path = "main.rs"

[profile.release]
debug = true

And main.rs:

use icu::{
    calendar::Iso,
    datetime::{fieldsets, DateTimeFormatter},
    locale::locale,
    time::ZonedDateTime,
};
use jiff::Zoned;
use jiff_icu::ConvertFrom as _;

fn main() -> anyhow::Result<()> {
    let zdt: Zoned = "2025-05-10T17:30[Pacific/Auckland]".parse()?;
    let icu_zdt = ZonedDateTime::<Iso, _>::convert_from(&zdt);

    // Format for the en-GB locale:
    let formatter = DateTimeFormatter::try_new(
        locale!("en-NZ-u-hc-h24").into(),
        fieldsets::YMDET::medium().with_zone(fieldsets::zone::SpecificLong),
    )?;
    assert_eq!(
        formatter.format(&icu_zdt).to_string(),
        "Sat, 10/05/2025, 5:30:00\u{202f}pm New Zealand Standard Time",
    );

    Ok(())
}

Running this, the assertion above passes. Which means it isn't using a 24 hour clock rendering.

My recollection is that ICU4X has an API for providing preferences for datetime formatting explicitly, instead of relying on a locale identifier. So when I went looking for that, I found HourCycle... Which has a variant called H23 that corresponds to the "24 hour clock." Uhhhhh. Okay... Could it be that simple? Let's try:

$ BIFF_LOCALE=en-NZ-u-hc-h23 TZ=Pacific/Auckland biff time fmt -f '%c' 2025-05-10T17:30
Sat, 10/05/2025, 17:30:00 NZST

Apparently. You need to use h23 to get a 24 hour clock? IDK if this is ICU4X's doing or Unicode's brilliant idea. Maybe they have reserved 24 for clocks that include 24:00 (i.e., midnight). Not sure.

---

I struggled to find a "locale identifiers for humans" text when I was writing Biff's docs. It's extremely opaque to me what the domain of values are and what I'm actually able to express.

[passcod]

Thanks for the investigation and the answer!

[robertbastian]

Apparently. You need to use h23 to get a 24 hour clock? IDK if this is ICU4X's doing or Unicode's brilliant idea. Maybe they have reserved 24 for clocks that include 24:00 (i.e., midnight). Not sure.

Yes, you need to use h23. h11 uses 0-11, h12 uses 1-12, h23 uses 0-23, and h24 uses 1-24. ICU4X does not implement h24 because no locale uses it (I believe it is also being removed from Unicode).

https://www.unicode.org/reports/tr35/tr35-dates.html#Contents:~:text=Default%20Value%3A%20Auto-,The%20hour%20cycle,-%2C%20which%20corresponds%20directly

[BurntSushi]

So to be more concrete, my choices here seem to be:

1. Get locale info from system.
2. Build up an entire CLI user interface from whole cloth in a way that matches the preferences exposed by ICU4X.
3. Do what I do today and let an end user type a Unicode locale string.

For (1), I guess on Unix this would be extracting a Unicode locale from a POSIX locale, and I don't think I know myself how I would change my POSIX locale settings at the level of "use a 24 hour clock instead of a 12 hour clock." And it's not obvious to me that everything configurable in a Unicode locale is also configurable via POSIX locales in exactly the same way. If I were to bet, I'd say they aren't. So even if I have (1) (and to be clear, I think it would be great to do this, I'm just waiting on y'all to publish that integration), that seems to suggest still needing (2) or (3).

For (2), this seems like a fair bit of work and I am not an expert in localization. So I'm not sure I'd get this right. And if I were to attempt this, I'd probably... just copy what ICU4X does for Unicode locale identifiers, but error for things that aren't supported. Because it's succinct and matches a known specification.

(3) seems like the obvious answer for me here. My users aren't non-technical end users. They are programmers. In a similar way that IANA time zone identifiers aren't "for users," they are still something that programmers can reasonably work with. The only thing missing are some better failure modes.

but then you have to know what you're doing and not set invalid tags

It doesn't have to be that way though. If you can detect invalid tags enough to drop them, then it should be possible to provide some kind of API for them to be validated in some way.

The string representation should be used for interchange only (in a lenient way for forward and backward compatibility).

If that's true, then why is there a icu::locale::locale! macro that does compile time construction of a Locale? That seems to suggest that it is expected for programmers to type locale identifiers. Biff's users are programmers. It also seems like a bug to me to type an identifier with invalid tags that get silently dropped. So an API to improve failure modes for parsing locale identifiers could help users of ICU4X too. I know I'd certainly want to be bleated at if I typed in a locale identifier with invalid tags.

[robertbastian]

If you can detect invalid tags enough to drop them, then it should be possible to provide some kind of API for them to be validated in some way.

They are dropped in impl From<&Locale> for DateTimeFormatterPreferences. This code needs to work with locales from the future (e.g. with a hypothetical future h25) and should not be fallible, as callers who don't control the locale cannot do anything with these errors.

It sounds like you want some kind of DateTimeFormatterPreferences::from_locale_strict(&Locale) -> Result<Self, Self>. If you want to contribute, the code is here.

If that's true, then why is there a icu::locale::locale! macro that does compile time construction of a Locale?

Well, that's also interchange. The programmer has a locale in mind and writes it out as a string for the program to parse. They do need to write it out correctly.

[BurntSushi]

It sounds like you want some kind of DateTimeFormatterPreferences::from_locale_strict(&Locale) -> Result<Self, Self>.

Well... yeah. I asked specifically about this several comments ago:

Is there a way to do a "strict parse" so that if something the user types gets silently dropped, then that gets turned into an error? Biff could then at least log that.

Also:

Well, that's also interchange. The programmer has a locale in mind and writes it out as a string for the program to parse. They do need to write it out correctly.

OK. If interchange is going to be defined that broadly, then Biff's use of it is also interchange. It seems to me like Biff users and ICU4X users alike would benefit from some way of detecting if they've typed an invalid locale string.

[robertbastian]

Well... yeah. I asked specifically about this several comments ago

I'm sorry that I didn't read your mind when you asked for "strict parse" but meant strict conversion to preferences! My bad!

[BurntSushi]

Goodness I'm so sick of talking to you. Enjoy your block.