Skip to main content

Localize Currency Amounts Without Hard-Coded Symbols or Locales

2026-11-19

Localize Currency Amounts Without Hard-Coded Symbols or Locales

A German build shows $1,234.56 next to German copy. A US build of the same wallet shows US$ 1.234.567,89 because someone froze the formatter to nl_NL. A yen price renders as ¥1234.00 with two fraction digits the currency does not use. Reviewers file all three as "bad localization." In each case the app treated currency as a glyph to glue onto a number, or it treated the developer's locale as the money's locale.

This guide is for mobile and web engineers and localization leads who already format dates and plain numbers with locale-aware APIs, as covered in localizing app dates, times, and numbers, and who need in-app prices and balances to survive multilingual release. It does not reopen store listing IAP metadata, which lives in localizing in-app purchase and subscription metadata. It also does not reopen compact suffixes, native digit shapes, or editable decimal input; those are adjacent formatting problems with their own contracts.

The short answer

  1. Store money as an amount plus an ISO 4217 currency code. Never persist "$1,200" as data.
  2. Format with the platform currency API (Intl.NumberFormat with style: "currency", Apple NumberFormatter / FloatingPointFormatStyle.Currency, ICU currency units) using the app's selected locale.
  3. Keep the ISO 4217 currency code on the money object and bind the formatter locale to the app language separately; never freeze the locale to match the currency or the developer's machine.
  4. Decide foreign-currency symbol policy with currencyDisplay (or the platform equivalent). Treat foreign-currency disambiguation (US$ versus $) as an explicit currencyDisplay policy, not as a bug to strip after formatting.
  5. Keep store IAP and system purchase-sheet price strings out of the in-app Money formatter; those surfaces use storefront rules that your app locale cannot safely rewrite.

Why hard-coded currency fails

Currency formatting is more than putting a dollar sign on the left. CLDR currency patterns move the ¤ currency placeholder, choose grouping and decimal separators from the locale, and pick fraction digits from the currency. The CLDR number and currency patterns guide states that symbols such as % and ¤ may change position, and that they are replaced with local equivalents. Unicode's LDML Part 3 is the normative home for that data. ICU's Formatting Numbers user guide puts Currencies beside decimals, units, and percentages for the same reason: the unit and the locale both matter.

Hard-coded $ + toFixed(2) ignores all of that. It also destroys the currency identity. The dates and numbers guide linked above already warns that an API that receives only $1,200 cannot recover the currency code. Once the display string is the stored value, round-trips, analytics, and refunds become locale archaeology.

Issue trackers show the frozen-locale variant of the same bug. ethos-protocol's ethos-mobile #313 asks teams to audit XLM balance formatting for a hardcoded en-US NumberFormatter / NumberFormat, which would print the wrong separators for many non-US locales. sflinter's banktivity-swift-mcp #36 is sharper: formattedBalance rendered USD with a hardcoded nl_NL locale, so US users saw US$ 1.234.567,89 with a non-breaking space, Dutch grouping, and a comma decimal. That is not European formatting. It is a developer's convenience locale leaking into production money.

Separate currency identity from presentation locale

Two fields travel with every amount you show:

Field Answers Example
Currency code What money is this? USD, EUR, JPY
Formatter locale How should separators and symbol placement look? de-DE, en-US, ja-JP matching the app language

Those fields answer different questions. A traveler can hold USD while reading the app in German. A Japanese catalog can price in JPY while the UI language is English. Keep the ISO 4217 currency code on the money object and bind the formatter locale to the app language separately; never freeze the locale to match the currency or the developer's machine.

MDN's Intl.NumberFormat constructor makes the split explicit: style: "currency" requires a currency property (ISO 4217, normalized to uppercase), and the locale argument controls presentation. There is no default currency. Apple's NumberFormatter uses numberStyle = .currency with currencyCode and a separate locale. The modern format styles FloatingPointFormatStyle.Currency, Decimal.FormatStyle.Currency, and IntegerFormatStyle.Currency (iOS 15+) encode the same contract in Swift.

type Money = { amount: number; currency: string }; // ISO 4217

export function formatMoney(value: Money, appLocale: string): string {
  return new Intl.NumberFormat(appLocale, {
    style: "currency",
    currency: value.currency,
  }).format(value.amount);
}

formatMoney({ amount: 1234.56, currency: "USD" }, "de-DE");
// often "1.234,56 $" or a localized US-dollar form for German
formatMoney({ amount: 1234.56, currency: "EUR" }, "de-DE");
// "1.234,56 €"
formatMoney({ amount: 1234, currency: "JPY" }, "ja-JP");
// "¥1,234" with zero fraction digits by default

The JPY case is the fraction-digit trap. MDN's constructor examples show Japanese yen formatting without a minor unit. Stack Overflow 49724537 (score 88) is a practitioner report about forcing zero or two fraction digits with Intl.NumberFormat. Prefer the currency's ISO default unless product policy documents an override, and never invent decimals because toFixed(2) felt tidy.

Treat US$ versus $ as policy

When the currency does not match the locale's usual currency, many formatters disambiguate. Swift NumberFormatter with currencyCode = "USD" and locale = en_GB produces US$100.00 rather than $100.00, as reported in Stack Overflow 67191994. Question 62005326 shows the complementary case: exotic currencies may render as a code (DKK) in one locale and a symbol (kr.) in another. Question 39458003 shows a formatter emitting the ¤ placeholder instead of a real symbol, which its answers trace to the project's region configuration.

On the web, currencyDisplay controls the tradeoff:

currencyDisplay Typical use
symbol (default) Localized symbol; may become US$ when the currency is foreign to the locale
narrowSymbol Prefer a short symbol when the platform has one
code Always show USD / EUR when ambiguity is unacceptable
name Spell out "US dollars" for accessibility or confirmation screens

Treat foreign-currency disambiguation (US$ versus $) as an explicit currencyDisplay policy, not as a bug to strip after formatting. Post-processing the string to delete US reintroduces CAD/AUD/USD collisions the formatter was trying to prevent. If the product wants a bare $ for USD in every locale, document that as a brand exception, set currencySymbol deliberately on Apple platforms, or choose currencyDisplay: "narrowSymbol" and test the collision set. Do not regex the output.

currencySign: "accounting" is a second policy knob. MDN shows accounting format wrapping negatives in parentheses in some locales. Pick it for ledgers; leave the default for storefront prices.

Keep store price strings out of the in-app formatter

StoreKit and Play Billing already return localized price strings for the system purchase sheet. The IAP metadata article warns against rebuilding a price with the wrong currency format or concatenating a currency symbol with a number from a second translation table. Keep store IAP and system purchase-sheet price strings out of the in-app Money formatter; those surfaces use storefront rules that your app locale cannot safely rewrite.

In-app surfaces that you own (wallet balances, cart lines, invoices, analytics) should format from structured Money values. System purchase UI should display the store's own localized price string. Mixing them produces the classic failure where the cart shows €9.99 while the sheet shows a differently rounded storefront price for another storefront country.

Implementation sequence

  1. Inventory. List every screen that shows money. Mark each value as structured Money (amount + code), a store-provided price string, or a hard-coded template. Search for "$", "€", "£", toFixed(, and formatter locales hard-coded to en_US or the developer's region.
  2. Define the type. Introduce Money { amount, currency } (or platform Decimal + currency code). Reject construction without a currency. Prefer minor-unit integers in storage when your ledger already uses them, and convert once at the formatting boundary.
  3. Centralize the formatter. One factory takes (money, appLocale, displayPolicy) and returns a string. On Apple platforms prefer FloatingPointFormatStyle.Currency / Decimal.FormatStyle.Currency with an explicit locale from the app language. On Android prefer ICU NumberFormatter with a currency unit rather than string concatenation. On the web use Intl.NumberFormat.
  4. Bind locale to the app language. When the user switches language in-app, rebuild or memoize formatters with the new locale. Do not read Locale.current alone if the product supports per-app language overrides.
  5. Set display policy. Choose default currencyDisplay / symbol width once. Document any brand exceptions. Add currencySign only where accounting negatives are required.
  6. Leave store strings alone. Pass StoreKit / Play price strings through to system sheets without re-formatting. Format your own Money values everywhere else.
  7. Stop parsing display strings. If users edit amounts, keep the currency in a separate control and parse the numeric field with a locale-aware number parser. Currency parse APIs exist, but they are not a substitute for structured input.
func formatMoney(_ amount: Decimal, currencyCode: String, appLocale: Locale) -> String {
  var style = Decimal.FormatStyle.Currency(code: currencyCode, locale: appLocale)
  // Optional product policy:
  // style = style.presentation(.narrow)
  return amount.formatted(style)
}

Failure modes worth testing

Failure What to check
Hard-coded $ Templates and concatenation still present after migration
Frozen locale Formatter uses en_US / nl_NL while the app language differs (banktivity #36, ethos-mobile #313)
Missing currency Money without a code becomes a bare number; a misconfigured region can surface ¤ (SO 39458003)
Wrong fraction digits JPY / other zero-decimal currencies gain .00
Stripped disambiguation USD in en_GB forced to $ and confused with other dollar currencies
Store string rewrite Cart formatter mutates StoreKit / Play localized price text
NBSP / narrow spaces Snapshot tests compare formatted output to hard-coded ASCII spaces (SO 54242039)
Sign-less money Removing the currency sign for layout (SO 44969852) without an accessible name elsewhere

In snapshot tests, assert policies you own: currency code, app locale, currencyDisplay, and whether accounting signs are enabled. Assert a small end-to-end matrix against the platform formatter instead of pinning every glyph for every locale. Platform data can change; your wiring should not.

Verify before release

  1. Format the same Money(1234.56, "USD") under en-US, en-GB, de-DE, and ja-JP. Confirm separators follow the app locale and that foreign-currency disambiguation matches your policy.
  2. Format Money(1234, "JPY") and confirm fraction digits follow the currency default unless product policy overrides them.
  3. Switch the in-app language without changing device region and confirm prices refresh through the shared factory.
  4. Confirm system purchase sheets still show store-provided localized price strings untouched.
  5. Grep the release build for hard-coded $ / € next to numeric templates and for formatter locales constructed with string literals such as "en_US".
  6. Run one VoiceOver / TalkBack pass on a confirmation screen that uses currencyDisplay: "name" or an equivalent accessible label when the visible symbol is ambiguous.

Next action

Pick one high-traffic money screen today. Replace every hard-coded symbol and frozen locale with a shared formatMoney(amount, currency, appLocale) factory, add the four-locale USD matrix plus one JPY case, and leave store purchase-sheet strings on the store path. That gives the team a pattern before the next catalog or wallet screen migrates.