Skip to main content

Localize Compact Numbers Like 1.2K Without Hard-Coded Suffixes

2026-11-16

Localize Compact Numbers Like 1.2K Without Hard-Coded Suffixes

Your profile screen shows "12.4K followers" and your dashboard shows "$3.2M revenue". In English that looks finished. Switch the app to Japanese and the same numbers still read 12.4K, even though a Japanese reader expects 1.2万. Switch to Hindi and the app never reaches lakh. Switch to Ukrainian and the noun after the number takes the wrong form. Compact number formatting is a locale feature with its own data, thresholds, and grammar, and treating it as a string helper is how an otherwise translated app keeps one stubborn English detail on its busiest screens.

This guide covers what breaks, which platform APIs replace the helper, how plurals interact with compact numbers, and how to test the result. It assumes you already format ordinary numbers with locale-aware APIs, as covered in our guide to localizing app dates, times, and numbers.

The short answer

  1. Delete hand-written K, M, B helpers and call the platform's compact formatter with the user's locale.
  2. Check the minimum OS level for each API and plan a fallback for older devices.
  3. Choose plural forms from the compacted value, or design the label so no noun has to agree with it.
  4. Keep the exact number for accessibility labels, tooltips, sorting, and exports.
  5. Never parse a compact string back into a number.
  6. Test each locale at its own threshold boundaries, not only at 1,000 and 1,000,000.

Why hand-written K and M helpers fail

The popular answers teach the helper. The Stack Overflow question iOS convert large numbers to smaller format has a score of 68, roughly 32,500 views, and 29 answers. Its top-voted answer divides by powers of 1,000 and appends a fixed array of suffixes: K, M, G, T, P, E. That code is easy to read and it works for English. It cannot work for most other languages, because the rules it hard-codes are not universal.

Three assumptions are baked into that helper.

Every language groups by thousands. Unicode's CLDR project, which supplies locale data to iOS, Android, and browsers, shows the difference in its number and currency pattern guidance. English compact patterns step through 0K, 0M, 0B, and 0T. Japanese patterns do nothing special for four digits, switch to 0万 (ten thousand) at five digits, and then to 0億 (one hundred million) at nine digits. The same table shows 1,234,567 written as 1.2M in English and 123万 in Japanese. The ICU4X compact formatter source documents the same split in its examples: French uses millions, Bangla uses lakhs, and Japanese uses myriads for a number of the same size.

The suffix is a single Latin letter. Locale data for German produces forms such as 1,2 Mio. and 1,2 Mrd., with a space, a comma decimal, and an abbreviated word. Android's CompactDecimalFormat reference uses "1,2 Mrd." for German as its own example and warns that the result "may sometimes exceed 7 characters" for some languages.

The noun after the number does not care. In many languages it does, and the plural section below shows how.

Practitioners keep running into these gaps. One developer asked how to show currencies with localized million and billion text in Swift, giving 3,31 Mio. € for German and kr 23 mill. for Norwegian as the target, and noting that the generic K/M/B answer "does not solve the whole problem." Another asked how to reach ICU's compact decimal format from Swift before Apple exposed it directly. These are author reports, but they line up with what the locale data says.

Use the platform compact number formatter

Every major platform ships compact notation backed by CLDR data. The work is choosing the right API for your minimum OS version.

Platform API Available from
iOS, iPadOS, macOS .notation(.compactName) on number format styles iOS 15, macOS 12
Android android.icu.number.NumberFormatter with Notation.compactShort() API 30
Android (older) android.icu.text.CompactDecimalFormat API 24
Web, React Native with Intl Intl.NumberFormat with notation: "compact" Modern engines

iOS and macOS

Apple documents compactName as "a locale-appropriate compact name notation," available from iOS 15 and macOS 12. Apply it to an integer or floating-point format style and let the locale decide the rest:

let followers = 1_234_567

// Uses the current locale
let label = followers.formatted(.number.notation(.compactName))

// Explicit locale, for tests or an in-app language setting
let japanese = followers.formatted(
    .number.notation(.compactName).locale(Locale(identifier: "ja_JP"))
)

If your app has its own language picker, pass that locale explicitly rather than relying on the process default. A formatter that silently follows the device while the rest of the screen follows the app language is a common source of mixed-language UI.

Android

Android's documentation steers new code away from the older class. The CompactDecimalFormat page says it "is provided for backwards compatibility only" and encourages NumberFormatter, which was added in API level 30 and offers Notation.compactShort():

// API 30 and later
val text = NumberFormatter.withLocale(appLocale)
    .notation(Notation.compactShort())
    .format(1_234_567)
    .toString()

// API 24 to 29
val legacy = CompactDecimalFormat
    .getInstance(appLocale, CompactDecimalFormat.CompactStyle.SHORT)
    .format(1_234_567)

Read the limits on the legacy class before you rely on it. Its reference states that negative numbers and parsing are not supported and produce an UnsupportedOperationException, and that formatting a currency amount in the long style also throws. If your chart axis can go below zero, the API 24 path needs a guard. One Android developer asked how to actually get abbreviated notation from CompactDecimalFormat after calling parse("1200") and getting 1200 back, because parsing was never the way in.

Web and cross-platform code

MDN's Intl.NumberFormat constructor reference documents notation: "compact" with a compactDisplay option of "short" (the default) or "long":

const short = new Intl.NumberFormat(locale, { notation: "compact" });
const long = new Intl.NumberFormat(locale, {
  notation: "compact",
  compactDisplay: "long",
});

Tutorials such as ExpertBeacon's walkthrough of compact numbers with the JavaScript Internationalization API show the payoff well, including 500万 for Chinese and lakh output for Hindi. They stop at the formatted string, and the threshold, plural, and accessibility problems start right after it.

Compact thresholds come from locale data

Compact thresholds are locale data, so test each locale at its own switch points such as 10,000 for Japanese and 100,000 for Hindi instead of only at 1,000 and 1,000,000.

Thresholds affect layout as well as correctness. English output changes shape at 1,000 (from 999 to 1K) and at 1,000,000. Japanese output keeps full digits through 9,999 and then changes at 10,000, so a badge that looked fine in English can hold a four-digit number in Japanese and overflow. The CLDR pattern table makes this visible: the Japanese four-digit pattern is plain 0, which CLDR uses to mean "no compact form here, use ordinary formatting."

Hindi and Bangla move to lakh at 100,000, and ICU4X notes that a formatter will refuse a requested exponent that does not fit the locale, such as asking for millions in a locale that uses lakhs and crores. Do not try to force one global set of breakpoints onto every locale.

What to do differently:

  • Build test fixtures from each locale's boundaries, not from English ones. For Japanese, test 9,999, 10,000, and 99,999,999. For Hindi, test 99,999 and 100,000.
  • Size badges and table columns for the longest compact string you ship, not for 999K. German Mio. and Mrd. forms, Japanese four-digit plain numbers, and long-style output all run wider than English.
  • Let the formatter choose rounding. Android's legacy class defaults to two significant digits, and forcing more digits widens the result, as its reference warns.

Pick plural forms from the compacted value

Pick the plural form from the compacted value, not the raw count, because once 1,452 is shown as 1.4K the noun after it agrees with the thousands unit and some languages need a different form.

The maintainers of the @vintl/compact-number library explain the mistake with a Ukrainian example. With 1,452 cats, compact formatting gives "1,4 тис." If the app then picks the plural form using the original number, the result is "1,4 тис. коти", which is wrong. The correct phrase is "1,4 тис. котів", because the noun now follows the thousands unit, not 1,452.

French shows the same effect from the standards side. The CLDR plural rules chart gives French a many category whose examples include 1c6 and 2c6, illustrated with "1 M de jours". The c there is defined in Unicode LDML Part 3 as the compact decimal exponent: the power of 10 used in compact formatting. LDML also states that when that exponent is present, the other plural operands are computed after shifting by it. So the plural form depends on what the reader sees, not on the integer in your database.

Most app code gets this wrong because plural lookups usually take the raw count. A String Catalog plural variant or an Android getQuantityString call receives 1452 and picks the form for 1,452. Nothing in the formatter warns you.

Practical options, in order of preference:

  1. Design the label so nothing agrees with the number. "Followers: 1.4K" or an icon next to the number avoids agreement entirely. This is the safest choice for dense UI.
  2. Round first, then pluralize. Round the raw value to the compact unit the formatter will use and pass that rounded value to plural selection. This is the approach vintl takes, using CLDR data to compute the exponent. It works for most languages, and the library itself asks for native-speaker testing.
  3. Use full numbers where grammar matters. In a sentence such as a notification body, write the full count with ordinary locale formatting and let the plural rules work on it normally.

Whichever you choose, tell translators. A translator note on the plural string saying "the count is displayed in compact form, for example 1.4K" lets them flag languages where the sentence needs restructuring. This is the same class of problem as building sentences from fragments, covered in our guide to why you should stop concatenating strings.

Treat compact output as a lossy display string

Treat compact output as a lossy display string: never parse it back, store it, or use it alone as the accessibility label, and keep the exact value next to it.

The formatter throws information away on purpose. 1.2K could be 1,150 or 1,249. Android makes the boundary explicit for its legacy class: parsing compact text is unsupported and throws. Even where parsing seems to work, you would be guessing at a rounded value. So:

  • Keep the exact number in your model. Format at the view layer only. Never write a compact string into a database, cache key, analytics event, or CSV export.
  • Sort and filter on the exact number. A table sorted by its compact text puts 9K after 10K, because text sorts character by character.
  • Give assistive technology the precise value. This is a recommendation from first principles rather than a platform rule: a screen reader reading "1.2K" gives a blind user less than a sighted user gets from a tooltip, and the spoken form of abbreviations varies by voice and language. Set the accessibility label from the full locale-formatted number, or from the long compact style when the full number is too noisy.
  • Offer the exact value on demand. A tooltip, long-press, or detail screen with the full number serves users who need precision, such as creators checking revenue.

Currency and long-form output

Compact currency is where helpers break hardest, because the currency symbol, its position, and the spacing all change with locale. Android's NumberFormatter example in its reference combines Notation.compactShort() with a EUR currency unit and a precision limit, which is the right model: one formatter call handles symbol, scale, and rounding together.

Long-form output (1.2 million instead of 1.2M) is useful for accessibility labels and spacious layouts. On the web it is compactDisplay: "long". On Android, check which style your API path supports for currency before shipping, since the legacy class throws for long-style currency. Long forms also bring the plural problem back, because the unit word itself is inflected.

Test compact numbers before release

A compact number bug rarely shows up in English screenshots, so build a small matrix that forces it out. A practical set:

Locale Why it is in the matrix Values to test
en Baseline thousands grouping 999, 1,000, 999,999, 1,000,000
de Comma decimal, abbreviated words, wider strings 1,200, 1,200,000, 3,310,000,000
ja Myriad grouping, plain four-digit numbers 9,999, 10,000, 1,234,567, 100,000,000
hi Lakh and crore grouping 99,999, 100,000, 10,000,000
fr many plural category with compact millions 1,000,000, 2,000,000
uk Plural agreement after compacting 1,452, 21,000

For each cell, assert three things: the visible string comes from the formatter with the expected locale, the noun (if any) uses the form a native reviewer accepts, and the accessibility label carries the exact or long-form value. Add a layout snapshot at the widest value per locale. If your app supports an in-app language setting, run the matrix with the device locale set differently from the app locale, so a formatter that ignores your setting fails loudly.

Keep the expected strings in tests close to the formatter output rather than typing them by hand from memory. Locale data changes between OS releases, and a test that hard-codes yesterday's spacing will fail for the wrong reason.

Where translation fits

Compact notation itself is code, not translation. No translator should be asked to supply K or 万 as a string, and no translation file should contain a suffix table. What translators do own is the text around the number: the plural messages, the labels, and the notification sentences that embed counts.

That split is useful when you run strings through a translation workflow, whether human, AI-assisted with a tool such as i18nAgent, or both. Send the plural message with a context note saying the number is compact, include the full set of plural categories the target language needs, and review the Ukrainian, Polish, Arabic, and French results with that note in mind.

Next step

Search your codebase for the helper today. Look for arrays or switch statements containing "K", "M", and "B", and for divisions by 1,000 next to string interpolation. Replace each one with the platform compact formatter for your minimum OS level, move the exact value into the accessibility label, and add the six-locale matrix above to your UI tests before the next release.