A download finishes and the banner says 1.5 MB left. In English that looks fine. In French the rest of the screen is already translated, but the size still says MB instead of Mo. In German the number keeps a hard-coded . where a comma belongs. In Russian the unit stays Latin while every other label uses Cyrillic. The code that produced all three is usually a short helper: pick a power of 1024, format a float, append KB, MB, or GB.
That helper encodes English storage labels and one team's unit base. This guide shows how to replace it with platform formatters, how to bind the app's selected language, how to decide between SI and IEC bases, and how to keep the whole size inside a message translators can reorder.
The short answer
Do not build a file size from a number plus an English unit suffix. Prefer a platform formatter bound to the app language: Apple ByteCountFormatStyle or ByteCountFormatter, Android Formatter.formatFileSize / formatShortFileSize with a Context whose configuration locales match the in-app language, and web Intl.NumberFormat with a sanctioned unit such as byte, kilobyte, megabyte, or gigabyte. Decide whether your product uses SI (1000) or IEC (1024) and label that choice honestly. Pass the formatted size into a translatable message as one argument, and test separators, unit translations, RTL wrapping, and the boundaries where the unit steps up.
Why the hand-rolled helper keeps shipping
The helper is easy to write and easy to unit-test in English. Absolutex's pull request #74 describes a typical pattern: a formatSize function that hard-coded B/KB/MB/GB/TB in a module that already held resources but never used them for units. The fix was to call Formatter.formatFileSize, which localizes the number, the separator, and the unit together. LocalSend's open pull request #3473 makes the same move for file sizes and transfer speeds so those values follow the selected language across the app, notifications, and the web download page.
These are practitioner reports, and they keep recurring because the English helper looks correct in the default build. Storage screens, download progress, cache cleaners, and host-metrics panels all need a human-readable size. Teams ship the helper once, then localize every surrounding string while the size stays English.
Physical measurement units are a different problem. Distance and mass need a product policy for metric versus imperial. Digital file sizes need a different contract: a raw byte count, a chosen base (1000 or 1024), and a localized display string. Mixing the two leads people to put KB in ordinary translation files, which is the same class of mistake as concatenating a translated kilometer suffix onto a raw number.
What the platform formatters actually do
Apple's documentation for ByteCountFormatter defines it as a formatter that converts a byte count into a localized description with the appropriate byte modifier (KB, MB, GB, and so on). Modern Swift code is steered toward ByteCountFormatStyle, which formats an integer as a memory or file size through the FormatStyle API. Both are authoritative for Apple platforms. Neither is a substitute for deciding whether your product talks about file sizes or memory sizes, and countStyle exists specifically so that choice is explicit.
Android's Formatter.formatFileSize formats a content size as bytes, kilobytes, megabytes, and similar units. The AOSP implementation in Formatter.java shows two details that matter for localization. First, formatFileSize uses SI units by default (FLAG_SI_UNITS), and the class documentation states that as of Android O the prefixes follow the SI system so kB is 1000 bytes. On N and earlier, powers of 1024 were used with KB labels. Second, the locale comes from the Context configuration (localeFromContext), and right-to-left locales wrap the result in bidi formatting characters.
On the web, ECMA-402 lists sanctioned simple unit identifiers that include byte, kilobyte, megabyte, gigabyte, terabyte, and petabyte. MDN's Intl.supportedValuesOf documents the same unit names for Intl.NumberFormat when style is "unit". That gives you a locale-aware number, separator, and unit name without maintaining a per-language suffix table. Unicode LDML unit elements are the shared data behind those displays.
General date, time, and number formatting covers decimals and grouping. File-size UI still needs the unit layer on top of that, which is why a plain toLocaleString call is not enough by itself.
The missing locale property on Apple's classic API
Apple's classic ByteCountFormatter has no locale property, so an in-app language change can leave storage labels in the device language unless you migrate to ByteCountFormatStyle or otherwise bind the formatter to the app-selected locale. Stack Overflow question 60433836 starts from the Apple documentation promise of localized units, then reports that the units still come back in English while Finder shows them localized. OpenRadar issue 30919856, mirrored again as SR-4193, states the gap directly: DateFormatter and NumberFormatter expose locale, but ByteCountFormatter does not, so formatting in a locale that differs from the system default is awkward.
What to do differently: prefer ByteCountFormatStyle / Measurement.FormatStyle.ByteCount in Swift, and make the locale of that format style follow the app's selected language rather than only the device region. If you still use ByteCountFormatter, document that it tracks the process/system locale and verify behavior after an in-app language change, including widgets, share extensions, and notification text that show sizes. Do not assume that changing Bundle.main localization alone retargets a long-lived formatter instance.
SI versus IEC is a product decision, not a formatting detail
SI (1000) and IEC (1024) bases disagree silently: Android formatFileSize uses SI units since Oreo while many hand-rolled helpers still divide by 1024 and print MB, so the same byte count can read 16 GB in one place and 17.18 GB in another. Stack Overflow question 66019926 compares Formatter.formatFileSize with a custom readable-size helper and shows the mismatch teams notice in logs. Meshtastic-Android pull request #7469 fixed host metrics that showed 1024-based sizes labelled KB/MB/GB with a hard-coded decimal point, while a chart plotted mebibyte values labelled as MB. After the fix, Android host metrics use decimal sizes, French can show ko, Russian can show кБ, and comma locales get a comma.
What to do differently: pick one base for user-facing storage UI and stick to it across screens. If you follow Android's post-O SI behavior and most OS storage panels, use 1000 and labels such as kB/MB/GB (or their localized forms). If you truly mean binary units, use IEC labels (KiB/MiB/GiB) instead of printing MB for 1,048,576 bytes. Put that rule in the shared formatter, not in each view. When comparing free space to a file size, format both with the same policy or you will invent "not enough space" bugs that are really unit bugs.
Keep the whole size inside the message
A localized unit changes length and grammar (French Mo/ko, Russian кБ), so the formatted size must enter a translatable message as one argument rather than a number glued to a translated suffix. French often uses Mo and ko where English uses MB and kB. Russian uses Cyrillic abbreviations. Some locales change spacing between the number and the unit. A pattern such as t("download_remaining") + " " + size + " " + t("unit_mb") cannot reorder those pieces and cannot absorb a unit that already includes spacing rules.
What to do differently: format the size first, then inject it into one ICU or platform message:
download_remaining = {size} left to download
storage_used = This device is using {size} of app data
Give translators a note that {size} already includes the unit. Do not ship keys like unit_mb for digital sizes when the platform formatter already localized the unit. If a screen needs the numeric magnitude for a progress bar, keep the raw byte count in code and use the formatted string only for display.
Implementation sequence
- Inventory every storage, download, cache, attachment, and host-metrics surface that prints a human-readable size, including notifications and widgets.
- Define the product rule: SI or IEC, file style versus memory style on Apple (
countStyle), and short versus long unit display on web (unitDisplay). - Add one shared helper per platform that takes a byte count and the app locale (or a correctly configured Android
Context) and returns a display string. - On Apple, prefer
ByteCountFormatStylewith an explicit locale; avoid relying on classicByteCountFormatterfor in-app language switching. - On Android, call
Formatter.formatFileSize/formatShortFileSizewith a context whoseconfiguration.localesmatch the app language, and do not reintroduce a 1024 helper beside it. - On web, use
Intl.NumberFormat(appLocale, { style: "unit", unit, unitDisplay: "short" })with a sanctioned unit from the ECMA-402 list, picking the unit magnitude in code or letting a small wrapper choosekilobyte/megabyte/gigabyteconsistently with your SI/IEC policy. - Replace concatenations so messages receive the full formatted size as one argument.
- Delete the old
formatByteshelpers once call sites are gone, so the English suffix table cannot return through a utility import.
Example web wrapper when you already know the magnitude:
function formatFileSize(bytes, locale) {
const units = ["byte", "kilobyte", "megabyte", "gigabyte", "terabyte"];
let value = bytes;
let unitIndex = 0;
while (value >= 1000 && unitIndex < units.length - 1) {
value /= 1000;
unitIndex += 1;
}
return new Intl.NumberFormat(locale, {
style: "unit",
unit: units[unitIndex],
unitDisplay: "short",
maximumFractionDigits: 2,
}).format(value);
}
Treat that loop as an implementation recommendation for SI displays. If your product needs binary steps, change both the divisor and the unit identifiers so the label matches the math.
Failure modes to catch early
- Mixing SI and IEC on adjacent widgets so free space and file size disagree.
- Freezing a formatter to the device locale after the user picked another app language.
- Translating
MBin strings files while the number is still formatted with English separators. - Parsing a display string such as
1,5 Moback into bytes. Keep the raw count; never round-trip through presentation text. - Using compact-number formatters meant for social counts (
1.2K) for storage sizes. Those abbreviations follow a different CLDR compact-decimal system and are the wrong tool for byte counts. - Assuming web binary units exist under the names you remember. Stick to the sanctioned identifiers your runtime lists through
Intl.supportedValuesOf("unit").
How to verify
Build a fixture table of byte counts around the step boundaries (999, 1000, 1024, 1_000_000, 1_048_576, 1_000_000_000) and assert the formatted strings for at least en-US, a comma-decimal locale such as de-DE or fr-FR, a Cyrillic locale such as ru-RU, and an RTL locale such as ar. After an in-app language change, reopen storage and download screens and confirm sizes follow the new language without an app restart if your product promises that. On Android, verify the Context used for formatFileSize is the same localized context as the rest of the UI. On Apple, verify ByteCountFormatStyle output after changing the app language override. Compare one screen to the OS Settings storage summary only if your product intentionally matches that policy; otherwise document the deliberate difference.
VoiceOver and TalkBack should read the full localized size, including the unit. If a custom accessibility label rebuilds the string from parts, it will reintroduce the English helper.
Next action
Pick one high-traffic size label in your app, replace its helper with the platform formatter bound to the app language, and add boundary fixtures for two non-English locales before deleting the shared formatBytes utility. Once that path is clean, migrate the remaining call sites behind the same helper so SI/IEC policy and locale binding stay in one place.
