Design Proposal: `unit` option for `number-format`

[ginnyTheCat]

Design Proposal: unit option for number-format

Motivation

Allowing one to format heights of mountains (or other units of distance, time, weight, etc.) which are often to found on maps. Since a option to format currencies already exists adding one for other units would be nice.

For example using ["number-format", ["get", "elevation", { locale: <language>, unit: "meter" }] to display 5.000 m in de-DE, 5,000米 in cmn-CN and 5 000 м in uk-UA.

Proposed Change

Add a new unit option to number-format that is mutually exclusive to the currency option that already exists for monetary quantities. The possible units allowed are specified in CLDR and ECMA-402.

In JavaScript this option when specified sets the Intl.NumberFormat style to "unit" and passes the unit via the unit option. Other platforms are likely to have similar functionality, since this is something ICU offers. A prototype implementation can be found in #1335.

API Modifications

A new unit option in the number-format options.

Migration Plan and Compatibility

This feature only adds new functionality and is fully backwards compatible.

Rejected Alternatives

I have looked for other issues and not found any about this.

I tried implementing this myself by formatting a arbitrary number using Intl.NumberFormat.formatToParts, finding the number using the type and then concatenating the rest on the start and end of a number expression. This however does not work since some languages change the unit display based on the number provided (pluralization rules). Also this is not doable when specifying styles using JSON and not during runtime using JavaScript.

[CommanderStorm]

So which units should be supported via this? 🤔

I'd like to not bloat us by including all the possible units
Specific SI-units (length, maybe area) maybe, but not feet/inches/fathoms/hectars/farenheit/nautical miles

But that is a very europe-centric view. Not sure if this is the best take.

[HarelM]

The scale control supports some units, we should probably align with it...

[ginnyTheCat]

I'd like to not bloat us by including all the possible units

I'm not sure if you mean bloat from a (1) bundle/binary size or (2) spec perspective.

1. As shown in the section below all platforms (except for iOS) already ship or provide ICU with the relevant APIs available, so this would not impact this I think.

2. Trimming down the API surface is always a good idea, but missing a unit you need and then having to wait a whole release cycle to get access to it is probably not great and would cause people to just fall back to hard coding the unit in English. Maps with temperature units are visible in every weather broadcast, even if at first glace they feel quite unnessesary to have support for them in a map library. If we would narrow the units down I think ECMA-403 has quite a nice selection that I would see as representative of both SI and imperial units. I fully understand however if a even smaller subset is chosen, but i wouldn't go as far as to fully exclude imperial units.

UTS 35 unit identifier support across platforms

JavaScript provides us with per spec at least ECMA-403 units, with the rest of the CLDR optionally supported.

Android ships with ICU supports all CLDR units.

On Linux and Windows (i didn't even know maplibre-native supported those) it seem to already be using ICU.

iOS has Dimension in Foundation to be used as a FormatStyle (them having a symbol string member doesn't put to much confidence in me that they give great localized formatting, but I don't have a device to test this on and the examples aren't great). I also found https://github.com/swiftlang/swift-foundation-icu but it seems to be more of an internal thing so idk. Maybe somebody who knows something about iOS development can chime in here.

[CommanderStorm]

Sounds Reasonable.

I think all style-relevant operations happen in the core on native => not in platform code
So ICU would have to be used in any case.
cc @louwers

I am still a bit uncear what this would mean for unit concretely. (as in: which strings should be allowed here)

[louwers]

Number formatting is actually done on the platform level.

We already ship a distance formatter utility for iOS. https://github.com/maplibre/maplibre-native/blob/e485a5b3c557092a77a29e963cefa08c08b6d69b/platform/darwin/test/MLNDistanceFormatterTests.m#L11 But it's not tied into the style's number-format expression.

I any case, we should define exact strings usable as unit as @CommanderStorm suggested and use some existing standard for that. Another question: is there a one-to-one mapping from locale to distance unit?

Why not ["number-format", ["get", "elevation", { locale: <language>, distance: "meter" }]?

[ginnyTheCat]

we should define exact strings usable as unit [...] and use some existing standard for that

That's why i suggested using the units specified in CDLR und ECMA-403 with the unit strings specified as "UTS 35, unit strings".

is there a one-to-one mapping from locale to distance unit?

You mean what locale a unit defaults for a given category? I would have to research this. For distance it would just be metric everywhere except in 3 countries.

Or do you mean whether given unit and locale -> string works?. This one no, due to units in some languages becoming plural the number is also required. So only unit, number and locale -> string works.

Why not ["number-format", ["get", "elevation", { locale: <language>, distance: "meter" }]

But then we would have to do ["number-format", ["get", "elevation", { locale: <language>, temperature: "celsius" }] and that for every unit category, or am I misunderstanding your suggestion?

[louwers]

That's why i suggested using the units specified in CDLR und ECMA-403 with the unit strings specified as "UTS 15, unit strings".

@ginnyTheCat Could you provide a links? Because those standards are not easy to find for me.

You mean what locale a unit defaults for a given category? I would have to research this. For distance it would just be metric everywhere except in 3 countries.

What I mean is that many countries use different units in different contexts. In (most of) Europe, feet is used for height in aviation, meter is used for heights of mountains and peaks, kilometer is on distances on road signs. Knots/nautical miles are used in aviation and shipping. Actually, mach is also sometimes used for fast aircrafts. m/s is used in meteorology for wind speeds. km/h is used for maximum speeds on highways.

That's my point, you cannot map unambiguously from unit + locale -> unit. If such a mapping and is standardized, it will most definitely will be a context + unit + locale -> unit.

[ginnyTheCat]

Could you provide a links? Because those standards are not easy to find for me.

ECMA-403 and the section of the CLDR I linked above, UTS 15 (sorry for my mistake) 35 is here.

That's my point, you cannot map unambiguously from unit + locale -> unit.

Unit is not distance in this circumstance, but meter or feet so I don't think this would be a problem.

[louwers]

Unit is not distance in this circumstance, but meter or feet so I don't think this would be a problem.

Fair point, but what would ["number-format", ["get", "elevation", { locale: "nl", unit: "foot" }] be? It still depends on the context what the right unit is for the nl locale.

[ginnyTheCat]

temperature: "feet"

I'm very confused especially since feet isn't a unit of temperature. My proposal would have had unit: "foot" which would format ["get", "elevation"] of 200 using locale "nl" as "200 ft" (you can try it out using new Intl.NumberFormat("nl", { style: "unit", unit: "foot" }).format(200) in JavaScript.

[louwers]

Sorry, I updated my comment.

new Intl.NumberFormat("nl", { style: "unit", unit: "foot" }).format(200)

This returns "200 ft". So maybe I misunderstood your whole suggestion. You don't want to convert units. You just want to format them only. Correct?

[ginnyTheCat]

You don't want to convert units. You just want to format them only. Correct?

Yes! Sorry for not being clear about this. Hope the example of how 3000 meters gets formatted in different locales in the first comment helps understanding the intented of the output of what I'm suggesting. I think it also makes sense since the currency option also doesn't try to do conversion (even if rates there change a bit more than between units hahahha) or more realistically feet or milligrams might be stored in the database already so a conversion wouldn't be wanted in the first place.

[louwers]

No, my bad, didn't check the linked issue!

I think it's a good idea.

[1ec5]

This proposal is entirely sound. The only reason mapbox/mapbox-gl-js#7626 omitted unit from the set of format options is that ICU hadn’t introduced this option yet. No browser would introduce support for it until the following year. The JavaScript option has been universally supported among mainstream browsers since 2020, mirroring support on the native platforms.

[ginnyTheCat]

mirroring support on the native platforms

I didn't really find a way to use ICU or unit formatting on iOS, but I fully agree with the rest of your comment.