@quenty/metricutils 2.4.3 → 2.5.0

package/src/Shared/Formatting/MetricUnitFormatUtils.spec.lua

@@ -0,0 +1,280 @@
+--!strict
+--[[
+	@class MetricUnitFormatUtils.spec.lua
+]]
+
+local require = require(script.Parent.loader).load(script)
+
+local Jest = require("Jest")
+local MetricUnit = require("MetricUnit")
+local MetricUnitFormatUtils = require("MetricUnitFormatUtils")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+-- Formatting puts a no-break space between a number and its unit; these compare it as a plain space
+local function plain(text: string): string
+	return (string.gsub(text, "\u{00A0}", " "))
+end
+
+local function formatUnit(unit: any, amount: number, options: any?): string
+	return plain(MetricUnitFormatUtils.formatUnit(unit, amount, options))
+end
+
+local function formatData(value: any, options: any?): string
+	return plain(MetricUnitFormatUtils.format(value, options))
+end
+
+local function format(value: any, options: MetricUnit.FormatOptions?): string
+	return plain(MetricUnit.format(value, options))
+end
+
+describe("MetricUnitFormatUtils.formatNumber", function()
+	it("rounds to three decimals and groups thousands by default", function()
+		expect(MetricUnitFormatUtils.formatNumber(1234.5678)).toBe("1,234.568")
+		expect(MetricUnitFormatUtils.formatNumber(-1234.5)).toBe("-1,234.5")
+		expect(MetricUnitFormatUtils.formatNumber(2)).toBe("2")
+		expect(MetricUnitFormatUtils.formatNumber(-0.0004)).toBe("0")
+	end)
+
+	it("uses the locale's grouping and decimal mark", function()
+		expect(MetricUnitFormatUtils.formatNumber(1234.5, { locale = "de-de" })).toBe("1 234,5")
+		expect(MetricUnitFormatUtils.formatNumber(1234.5, { locale = "es-es" })).toBe("1.234,5")
+		expect(MetricUnitFormatUtils.formatNumber(1234.5, { locale = "en-gb" })).toBe("1,234.5")
+	end)
+
+	it("takes Intl-style digit options", function()
+		expect(MetricUnitFormatUtils.formatNumber(2, { minimumFractionDigits = 2 })).toBe("2.00")
+		expect(MetricUnitFormatUtils.formatNumber(2.345, { maximumFractionDigits = 1 })).toBe("2.3")
+		expect(MetricUnitFormatUtils.formatNumber(2.35, { maximumFractionDigits = 0 })).toBe("2")
+		expect(MetricUnitFormatUtils.formatNumber(123456, { maximumSignificantDigits = 2 })).toBe("120,000")
+		expect(MetricUnitFormatUtils.formatNumber(0.012345, { maximumSignificantDigits = 2 })).toBe("0.012")
+		expect(MetricUnitFormatUtils.formatNumber(1234.5, { useGrouping = false })).toBe("1234.5")
+	end)
+end)
+
+describe("MetricUnitFormatUtils.format units", function()
+	it("picks the unit that suits the size, or the one given", function()
+		local length = MetricUnit.meters(2500)
+		expect(format(length)).toBe("2.5 km")
+		expect(format(length, { unit = "meter" })).toBe("2,500 m")
+		expect(format(length, { autoUnit = false })).toBe("2,500 m")
+		expect(format(length, { maximumSignificantDigits = 1 })).toBe("3 km")
+		expect(format(MetricUnit.meters(0))).toBe("0 m")
+	end)
+
+	it("writes long names, pluralized, in American or Commonwealth spelling", function()
+		expect(format(MetricUnit.meters(2500), { unitDisplay = "long" })).toBe("2.5 kilometers")
+		expect(format(MetricUnit.kilometers(1), { unitDisplay = "long" })).toBe("1 kilometer")
+		expect(format(MetricUnit.kilometers(1), { unitDisplay = "long", minimumFractionDigits = 1 })).toBe(
+			"1.0 kilometers"
+		)
+		expect(format(MetricUnit.meters(2500), { unitDisplay = "long", locale = "en-gb" })).toBe("2.5 kilometres")
+		expect(format(MetricUnit.new(2, "liter"), { unitDisplay = "long", locale = "en-au" })).toBe("2 litres")
+		expect(format(MetricUnit.tonnes(2), { unitDisplay = "long" })).toBe("2 metric tons")
+		expect(format(MetricUnit.tonnes(2), { unitDisplay = "long", locale = "en-gb" })).toBe("2 tonnes")
+	end)
+
+	it("writes SI symbols with the locale's numbers in any locale", function()
+		expect(format(MetricUnit.meters(1234.5), { unit = "meter", locale = "de-de" })).toBe("1 234,5 m")
+		expect(format(MetricUnit.kilograms(2.5), { locale = "fr-fr" })).toBe("2,5 kg")
+	end)
+
+	it("writes derived units", function()
+		expect(format(MetricUnit.new(1500, "newton"))).toBe("1.5 kN")
+		expect(format(MetricUnit.new(1500, "newton"), { unitDisplay = "long" })).toBe("1.5 kilonewtons")
+		expect(format(MetricUnit.new(2500, "watt"), { unitDisplay = "long" })).toBe("2.5 kilowatts")
+		expect(format(MetricUnit.new(3, "kilowattHour"), { unit = "kilowattHour" })).toBe("3 kWh")
+		expect(format(MetricUnit.new(25000, "squareMeter"), { unit = "hectare" })).toBe("2.5 ha")
+		expect(format(MetricUnit.new(0.25, "liter"))).toBe("250 mL")
+		expect(format(MetricUnit.new(4096, "kibibyte"), { unit = "mebibyte" })).toBe("4 MiB")
+		expect(format(MetricUnit.new(9.81, "meterPerSecondSquared"), { unitDisplay = "long" })).toBe(
+			"9.81 meters per second squared"
+		)
+	end)
+
+	it("takes phrase overrides", function()
+		local length = MetricUnit.meters(2500)
+		expect(format(length, { strings = { kilometer = { short = { one = "%s klick", other = "%s klicks" } } } })).toBe(
+			"2.5 klicks"
+		)
+		expect(format(length, {
+			strings = {
+				kilometer = {
+					short = function(_amount: number, numberText: string): string
+						return numberText .. "!"
+					end,
+				},
+			},
+		})).toBe("2.5!")
+	end)
+
+	it("errors when the unit given is of another dimension", function()
+		expect(function()
+			format(MetricUnit.meters(1), { unit = "kilogram" })
+		end).toThrow("kilogram is mass, not length")
+	end)
+
+	it("writes dimensionless values and unnamed compounds", function()
+		expect(format(MetricUnit.none(0.25))).toBe("0.25")
+		expect(format(MetricUnit.kilograms(2) * MetricUnit.new(3, "meterPerSecond"))).toBe("6 m·kg/s")
+		expect(format(MetricUnit.kilograms(2) / MetricUnit.kilometers(1))).toBe("0.002 kg/m")
+	end)
+end)
+
+describe("MetricUnitFormatUtils.format rates", function()
+	it("writes the numerator in its own display unit, per the shortest time unit it fills", function()
+		expect(format(MetricUnit.new(5, "meterPerSecond"))).toBe("5 m/s")
+		expect(format(MetricUnit.new(5, "meterPerSecond"), { unitDisplay = "long" })).toBe("5 meters per second")
+		expect(format(MetricUnit.new(1600, "kilobytePerSecond"))).toBe("1.6 MB/s")
+		expect(format(MetricUnit.new(1600, "kilobytePerSecond"), { unitDisplay = "long" })).toBe(
+			"1.6 megabytes per second"
+		)
+		expect(format(MetricUnit.perDay(5))).toBe("5/d")
+		expect(format(MetricUnit.perDay(5), { unitDisplay = "long" })).toBe("5 per day")
+	end)
+
+	it("takes a whole rate unit, a numerator unit or a per unit", function()
+		expect(format(MetricUnit.new(18, "kilometerPerHour"), { unit = "kilometerPerHour" })).toBe("18 km/h")
+		expect(format(MetricUnit.new(18, "kilometerPerHour"), { unit = "kilometerPerHour", unitDisplay = "long" })).toBe(
+			"18 kilometers per hour"
+		)
+		expect(format(MetricUnit.new(1600, "kilobytePerSecond"), { unit = "kilobyte" })).toBe("1,600 kB/s")
+		expect(format(MetricUnit.new(1600, "kilobytePerSecond"), { perUnit = "minute" })).toBe("96 MB/min")
+		expect(format(MetricUnit.new(18, "kilometerPerHour"), { unit = "kilometer", perUnit = "hour" })).toBe("18 km/h")
+		expect(format(MetricUnit.new(60, "hertz"), { unit = "hertz" })).toBe("60 Hz")
+	end)
+
+	it("takes per phrase overrides", function()
+		expect(format(MetricUnit.perHour(3), { perStrings = { hour = { short = "%s an hour" } } })).toBe("3 an hour")
+	end)
+end)
+
+describe("MetricUnitFormatUtils.format temperatures", function()
+	it("writes an absolute temperature on a scale, °C by default", function()
+		expect(format(MetricUnit.celsius(21.5))).toBe("21.5 °C")
+		expect(format(MetricUnit.celsius(100), { unit = "fahrenheit" })).toBe("212 °F")
+		expect(format(MetricUnit.celsius(0), { unit = "kelvin" })).toBe("273.15 K")
+		expect(format(MetricUnit.celsius(1), { unitDisplay = "long" })).toBe("1 degree Celsius")
+		expect(format(MetricUnit.celsius(20), { unitDisplay = "long" })).toBe("20 degrees Celsius")
+	end)
+
+	it("writes a difference without an offset, K by default", function()
+		expect(format(MetricUnit.difference(3, "celsius"))).toBe("3 K")
+		expect(format(MetricUnit.difference(3, "celsius"), { unit = "celsius" })).toBe("3 °C")
+		expect(format(MetricUnit.difference(5, "celsius"), { unit = "fahrenheit" })).toBe("9 °F")
+		expect(format(MetricUnit.celsius(25) - MetricUnit.celsius(20), { unitDisplay = "long" })).toBe("5 kelvins")
+	end)
+
+	it("errors when the unit given is not a temperature", function()
+		expect(function()
+			format(MetricUnit.celsius(5), { unit = "meter" })
+		end).toThrow("meter is length, not temperature")
+	end)
+end)
+
+describe("MetricUnitFormatUtils.formatUnit", function()
+	it("writes an amount already in the unit", function()
+		expect(formatUnit("kilometerPerHour", 90)).toBe("90 km/h")
+		expect(formatUnit("liter", 1, { unitDisplay = "long" })).toBe("1 liter")
+		expect(formatUnit("celsius", 20)).toBe("20 °C")
+		expect(formatUnit("hour", 1.5)).toBe("1.5 hours")
+		expect(formatUnit("day", 1.5, { locale = "es-es" })).toBe("1,5 días")
+	end)
+end)
+
+describe("MetricUnitFormatUtils.format with a translator", function()
+	local function fakeTranslator(locale: string, entries: { [string]: string }): any
+		return {
+			GetLocaleId = function()
+				return locale
+			end,
+			FormatByKey = function(_self: any, key: string, args: { [string]: any }?): string
+				local text = entries[key]
+				if not text then
+					error("No key " .. key)
+				end
+				return (string.gsub(text, "{n}", function()
+					return (args :: any).n
+				end))
+			end,
+			ObserveFormatByKey = function()
+				error("unused")
+			end,
+		}
+	end
+
+	local spanish = fakeTranslator("es-es", {
+		["units.mile.long.one"] = "{n} milla",
+		["units.mile.long.other"] = "{n} millas",
+		["units.mile.short.other"] = "{n} mi",
+		["units.kilometer.long.other"] = "{n} kilómetros",
+		["per.hour.long"] = "{n} por hora",
+	})
+
+	it("writes long names in the translator's language, with its plural rules and numbers", function()
+		expect(format(MetricUnit.new(3, "mile"):ToUSCustomary(), { unitDisplay = "long", translator = spanish })).toBe(
+			"3 millas"
+		)
+		expect(format(MetricUnit.new(1, "mile"):ToUSCustomary(), { unitDisplay = "long", translator = spanish })).toBe(
+			"1 milla"
+		)
+		expect(format(MetricUnit.new(1.5, "mile"):ToUSCustomary(), { unitDisplay = "long", translator = spanish })).toBe(
+			"1,5 millas"
+		)
+		expect(format(MetricUnit.new(5, "kilometerPerHour"), {
+			unitDisplay = "long",
+			unit = "kilometer",
+			perUnit = "hour",
+			translator = spanish,
+		})).toBe("5 kilómetros por hora")
+	end)
+
+	it("keeps symbols for short display, and English when a key is missing", function()
+		expect(format(MetricUnit.new(3, "mile"):ToUSCustomary(), { translator = spanish })).toBe("3 mi")
+		expect(format(MetricUnit.kilograms(3), { unitDisplay = "long", translator = spanish })).toBe("3 kilograms")
+		local broken = fakeTranslator("es-es", {})
+		expect(format(MetricUnit.new(3, "mile"):ToUSCustomary(), { unitDisplay = "long", translator = broken })).toBe(
+			"3 miles"
+		)
+	end)
+end)
+
+describe("MetricUnitFormatUtils.format input", function()
+	it("takes a MetricUnit or its plain data", function()
+		expect(formatData(MetricUnit.kilometers(1))).toBe("1 km")
+		expect(formatData(MetricUnit.toData(MetricUnit.kilometers(1)))).toBe("1 km")
+		expect(formatData({ amount = 278.15, dimensions = { temperature = 1 }, absolute = true })).toBe("5 °C")
+		expect(function()
+			formatData({ hello = true })
+		end).toThrow("expected a MetricUnit or MetricUnitData")
+	end)
+
+	it("writes bare rates by their per id, and frequencies in hertz", function()
+		expect(format(MetricUnit.perHour(3), { unit = "perHour" })).toBe("3/h")
+		expect(format(MetricUnit.perHour(3), { unit = "perHour", unitDisplay = "long" })).toBe("3 per hour")
+		expect(format(MetricUnit.perHour(3), { perUnit = "h" })).toBe("3/h")
+		expect(formatUnit("perDay", 5)).toBe("5/d")
+	end)
+end)
+
+describe("MetricUnitFormatUtils.format rates written as asked", function()
+	it("writes a rate in the numerator unit asked for, whatever the value's system shows", function()
+		expect(format(MetricUnit.new(60, "milePerHour"), { unit = "kilometer" })).toBe("0.027 km/s")
+		expect(format(MetricUnit.new(60, "milePerHour"), { unit = "kilometer", perUnit = "hour" })).toBe("96.561 km/h")
+		expect(format(MetricUnit.new(10, "studPerSecond"), { unit = "meter" })).toBe("2.8 m/s")
+	end)
+
+	it("writes a rate per the time unit asked for, whatever the value's system shows", function()
+		expect(format(MetricUnit.new(60, "milePerHour"), { perUnit = "second" })).toBe("88 ft/s")
+		expect(format(MetricUnit.new(60, "milePerHour"), { unit = "meter", perUnit = "second" })).toBe("26.822 m/s")
+	end)
+end)
+
+describe("MetricUnitFormatUtils plural forms by locale", function()
+	it("picks duration words by the locale's plural rule", function()
+		expect(format(MetricUnit.hours(1.5), { locale = "fr-fr", unit = "hour" })).toBe("1,5 heure")
+		expect(format(MetricUnit.hours(1.5), { locale = "en-us", unit = "hour" })).toBe("1.5 hours")
+	end)
+end)

package/src/Shared/Formatting/RxMetricUnitFormatUtils.lua

@@ -0,0 +1,62 @@
+--!strict
+--[=[
+	Observable formatting, for UI that should follow the player's language. Kept apart from
+	[MetricUnitFormatUtils] so formatting itself needs no Rx and runs anywhere, servers and specs included.
+
+	@class RxMetricUnitFormatUtils
+]=]
+
+local require = require(script.Parent.loader).load(script)
+
+local MetricUnitFormatUtils = require("MetricUnitFormatUtils")
+local Observable = require("Observable")
+local Rx = require("Rx")
+
+local RxMetricUnitFormatUtils = {}
+
+local ANY_TRANSLATION_KEY = "units.meter.other"
+
+--[=[
+	Observes [MetricUnitFormatUtils.format] in the translator's language: emits again when the player's locale
+	changes or its translations finish streaming in, with English names until then. Numbers follow the translator's
+	locale unless `options.locale` is given.
+
+	```lua
+	local translator = serviceBag:GetService(require("MetricUnitTranslator"))
+	maid:GiveTask(RxMetricUnitFormatUtils.observeFormat(translator, MetricUnit.new(3, "mile"), {
+		unitDisplay = "long",
+	}):Subscribe(function(text)
+		label.Text = text -- "3 miles", "3 millas", "3 Meilen"
+	end))
+	```
+
+	@param translator MetricUnitTranslatorLike -- [MetricUnitTranslator]
+	@param value MetricUnit | MetricUnitData
+	@param options MetricUnitFormatOptions?
+	@return Observable<string>
+]=]
+function RxMetricUnitFormatUtils.observeFormat(
+	translator: MetricUnitFormatUtils.MetricUnitTranslatorLike,
+	value: any,
+	options: MetricUnitFormatUtils.MetricUnitFormatOptions?
+): Observable.Observable<string>
+	assert(type(translator) == "table" and translator.ObserveFormatByKey, "Bad translator")
+
+	local formatOptions: MetricUnitFormatUtils.MetricUnitFormatOptions = table.clone(options or {})
+	formatOptions.translator = translator
+
+	return RxMetricUnitFormatUtils._observeTranslationChanges(translator):Pipe({
+		Rx.map(function()
+			return MetricUnitFormatUtils.format(value, formatOptions)
+		end) :: any,
+		Rx.distinct() :: any,
+	}) :: any
+end
+
+function RxMetricUnitFormatUtils._observeTranslationChanges(
+	translator: MetricUnitFormatUtils.MetricUnitTranslatorLike
+): Observable.Observable<string>
+	return translator:ObserveFormatByKey(ANY_TRANSLATION_KEY, { n = "" })
+end
+
+return table.freeze(RxMetricUnitFormatUtils)

package/src/Shared/Localization/MetricUnitFallbackStrings.lua

@@ -0,0 +1,289 @@
+--!strict
+--[=[
+	English unit names for [MetricUnitFormatUtils] when no translator is given. They need no translator, so specs,
+	servers and anything formatting before a translator loads always get readable text. Translated names stream to clients through [MetricUnitTranslator], a
+	`JSONTranslator` holding the same keys.
+
+	Lookups resolve through [ResolveLocaleUtils], so `en-us` lands on American English and `en-au` on Commonwealth
+	English. Without a translator, short phrases are the symbols in [MetricUnitDefinitions]; with one, they are the player's language's
+	(`5 км`, `5公里`). A no-break space joins a number to its unit either way.
+
+	@class MetricUnitFallbackStrings
+]=]
+
+local require = require(script.Parent.loader).load(script)
+
+local MetricUnitDefinitions = require("MetricUnitDefinitions")
+local ResolveLocaleUtils = require("ResolveLocaleUtils")
+
+local MetricUnitFallbackStrings = {}
+
+local DEFAULT_LOCALE = "en-us"
+
+--[=[
+	A unit phrase with `%s` for the already formatted number: a singular and plural pair, or a function of the
+	rounded amount and the formatted number for languages with more plural forms.
+
+	@type UnitPhrase { one: string, other: string } | (amount: number, numberText: string) -> string
+	@within MetricUnitFallbackStrings
+]=]
+export type UnitPhrase = { one: string, other: string } | (number, string) -> string
+
+--[=[
+	The short and long phrase for one unit, such as `"%s km"` and `"%s kilometers"`.
+
+	@interface UnitNames
+	.short UnitPhrase
+	.long UnitPhrase
+	@within MetricUnitFallbackStrings
+]=]
+export type UnitNames = { short: UnitPhrase, long: UnitPhrase }
+
+--[=[
+	[UnitNames] for every unit written by name, keyed by unit id: every unit [MetricUnitDefinitions] gives `names`. Time
+	units are written with [TimeLocalizationUtils]' duration words instead, and bare rates with [PerStrings].
+
+	@type UnitStrings { [UnitId]: UnitNames }
+	@within MetricUnitFallbackStrings
+]=]
+export type UnitStrings = { [string]: UnitNames }
+
+--[=[
+	How to write something per a time unit, with `%s` for the numerator already written: `"%s/h"` and
+	`"%s per hour"`.
+
+	@interface PerNames
+	.short string
+	.long string
+	@within MetricUnitFallbackStrings
+]=]
+export type PerNames = { short: string, long: string }
+
+--[=[
+	[PerNames] for every time unit a rate can be written per.
+
+	@interface PerStrings
+	.second PerNames
+	.minute PerNames
+	.hour PerNames
+	.day PerNames
+	.week PerNames
+	.month PerNames
+	.year PerNames
+	@within MetricUnitFallbackStrings
+]=]
+export type PerStrings = {
+	second: PerNames,
+	minute: PerNames,
+	hour: PerNames,
+	day: PerNames,
+	week: PerNames,
+	month: PerNames,
+	year: PerNames,
+}
+
+--[=[
+	Unit phrases a caller passes to override a locale's, keyed by unit id: `{ kilometer = { short = "%s klicks" } }`.
+
+	@type UnitStringOverrides { [string]: { short: UnitPhrase?, long: UnitPhrase? } }
+	@within MetricUnitFallbackStrings
+]=]
+export type UnitStringOverrides = { [string]: { short: UnitPhrase?, long: UnitPhrase? } }
+
+--[=[
+	Per phrases a caller passes to override a locale's, keyed by time unit id.
+
+	@type PerStringOverrides { [string]: { short: string?, long: string? } }
+	@within MetricUnitFallbackStrings
+]=]
+export type PerStringOverrides = { [string]: { short: string?, long: string? } }
+
+--[=[
+	Everything one locale needs.
+
+	@interface UnitLocale
+	.units UnitStrings
+	.per PerStrings
+	@within MetricUnitFallbackStrings
+]=]
+export type UnitLocale = {
+	units: UnitStrings,
+	per: PerStrings,
+}
+
+-- U+00A0, not CLDR's narrow U+202F: create.roblox.com does not document how TextLabels render U+202F
+local NO_BREAK_SPACE = "\u{00A0}"
+MetricUnitFallbackStrings.NO_BREAK_SPACE = NO_BREAK_SPACE
+
+local function withNoBreakSpaceAfterNumber(template: string): string
+	return (string.gsub(template, "^%%s ", "%%s" .. NO_BREAK_SPACE))
+end
+
+type Spelling = (string) -> string
+
+local function american(text: string): string
+	return text
+end
+
+--[=[
+	`text` in Commonwealth English spelling: metre for meter, litre for liter, tonne for metric ton.
+
+	@param text string
+	@return string
+]=]
+function MetricUnitFallbackStrings.toCommonwealthSpelling(text: string): string
+	text = string.gsub(text, "metric tons?", { ["metric ton"] = "tonne", ["metric tons"] = "tonnes" })
+	text = string.gsub(text, "meter", "metre")
+	text = string.gsub(text, "liter", "litre")
+	return text
+end
+
+function MetricUnitFallbackStrings._lazyEnglishUnits(spelling: Spelling): UnitStrings
+	return setmetatable({}, {
+		__index = function(self, id: string): UnitNames?
+			local unit = MetricUnitDefinitions.getUnit(id)
+			if not (unit and unit.names) then
+				return nil
+			end
+			local names = MetricUnitFallbackStrings._englishNamesOf(unit, spelling)
+			rawset(self, id, names)
+			return names
+		end,
+	}) :: any
+end
+
+function MetricUnitFallbackStrings._englishNamesOf(
+	unit: MetricUnitDefinitions.UnitDefinition,
+	spelling: Spelling
+): UnitNames
+	local short = "%s" .. NO_BREAK_SPACE .. unit.symbol
+	local templates = unit.shortTemplates
+	local names = unit.names or { one = unit.symbol, other = unit.symbol }
+	return table.freeze({
+		short = table.freeze({
+			one = if templates then withNoBreakSpaceAfterNumber(templates.one) else short,
+			other = if templates then withNoBreakSpaceAfterNumber(templates.other) else short,
+		}),
+		long = table.freeze({
+			one = "%s" .. NO_BREAK_SPACE .. spelling(names.one),
+			other = "%s" .. NO_BREAK_SPACE .. spelling(names.other),
+		}),
+	})
+end
+
+local PER_TIME_UNIT_IDS: { [string]: boolean } =
+	table.freeze({ second = true, minute = true, hour = true, day = true, week = true, month = true, year = true })
+
+function MetricUnitFallbackStrings._lazyEnglishPerStrings(): PerStrings
+	return setmetatable({}, {
+		__index = function(self, id: string): PerNames?
+			local unit = if PER_TIME_UNIT_IDS[id] then MetricUnitDefinitions.getUnit(id) else nil
+			if not unit then
+				return nil
+			end
+			local names = table.freeze({ short = "%s/" .. unit.symbol, long = "%s per " .. id })
+			rawset(self, id, names)
+			return names
+		end,
+	}) :: any
+end
+
+local AMERICAN_ENGLISH: UnitLocale = table.freeze({
+	units = MetricUnitFallbackStrings._lazyEnglishUnits(american),
+	per = MetricUnitFallbackStrings._lazyEnglishPerStrings(),
+})
+
+local COMMONWEALTH_ENGLISH: UnitLocale = table.freeze({
+	units = MetricUnitFallbackStrings._lazyEnglishUnits(MetricUnitFallbackStrings.toCommonwealthSpelling),
+	per = MetricUnitFallbackStrings._lazyEnglishPerStrings(),
+})
+
+local LOCALES: { [string]: UnitLocale } = table.freeze({
+	en = AMERICAN_ENGLISH,
+	["en-gb"] = COMMONWEALTH_ENGLISH,
+	["en-au"] = COMMONWEALTH_ENGLISH,
+	["en-ca"] = COMMONWEALTH_ENGLISH,
+	["en-ie"] = COMMONWEALTH_ENGLISH,
+	["en-nz"] = COMMONWEALTH_ENGLISH,
+}) :: any
+
+local warnedLocales: { [string]: boolean } = {}
+
+--[=[
+	Whether a locale has its own unit names here, directly or through a locale of the same language.
+
+	@param locale string?
+	@return boolean
+]=]
+function MetricUnitFallbackStrings.hasLocale(locale: string?): boolean
+	return ResolveLocaleUtils.resolveClosestKey(locale or DEFAULT_LOCALE, LOCALES) ~= nil
+end
+
+--[=[
+	Returns the read-only [UnitLocale] for a locale, defaulting to American English. Warns once per unknown locale.
+
+	@param locale string?
+	@return UnitLocale
+]=]
+function MetricUnitFallbackStrings.getLocale(locale: string?): UnitLocale
+	local key = ResolveLocaleUtils.resolveClosestKey(locale or DEFAULT_LOCALE, LOCALES)
+	if key then
+		return LOCALES[key]
+	end
+
+	local name = tostring(locale)
+	if not warnedLocales[name] then
+		warnedLocales[name] = true
+		warn(
+			string.format(
+				"[MetricUnitFallbackStrings] - No unit names for locale '%s', reverting to '%s' instead.",
+				name,
+				DEFAULT_LOCALE
+			)
+		)
+	end
+	return LOCALES[ResolveLocaleUtils.resolveClosestKey(DEFAULT_LOCALE, LOCALES) :: string]
+end
+
+--[=[
+	The [UnitNames] of `unit` in a locale: the locale's own, or, for a unit a game's own [MetricUnitSystem] declares,
+	its English names and symbol from its definition.
+
+	@param locale string?
+	@param unit UnitDefinition
+	@return UnitNames
+]=]
+function MetricUnitFallbackStrings.getUnitNames(locale: string?, unit: MetricUnitDefinitions.UnitDefinition): UnitNames
+	local unitLocale = MetricUnitFallbackStrings.getLocale(locale)
+	local names = unitLocale.units[unit.id]
+	if names then
+		return names
+	end
+	local spelling = if unitLocale == COMMONWEALTH_ENGLISH
+		then MetricUnitFallbackStrings.toCommonwealthSpelling
+		else american
+	return MetricUnitFallbackStrings._englishNamesOf(unit, spelling)
+end
+
+--[=[
+	Returns the read-only [UnitStrings] for a locale, defaulting to American English. Each unit's names are built the
+	first time they are read.
+
+	@param locale string?
+	@return UnitStrings
+]=]
+function MetricUnitFallbackStrings.getUnitStringsForLocale(locale: string?): UnitStrings
+	return MetricUnitFallbackStrings.getLocale(locale).units
+end
+
+--[=[
+	Returns the read-only [PerStrings] for a locale, defaulting to American English.
+
+	@param locale string?
+	@return PerStrings
+]=]
+function MetricUnitFallbackStrings.getPerStringsForLocale(locale: string?): PerStrings
+	return MetricUnitFallbackStrings.getLocale(locale).per
+end
+
+return table.freeze(MetricUnitFallbackStrings)