Arkian logo
Start free
Menu
← All articles

Number and Date Localization: A Developer's Field Guide

Number and Date Localization: A Developer’s Field Guide

Developer checking locale-specific number formatting

Number and date localization means showing every figure, date, time and price the way the reader’s locale writes it, and doing that with locale data instead of hand-built strings. The short version: store raw values, format them at the last moment with your platform’s internationalization API, and never concatenate separators, month orders or currency symbols yourself.

This guide covers what changes between locales, how to implement it, how currency fits in, and how small teams keep the formatting consistent when translated files ship in six or sixteen languages.

Arkian
Keep Localization Workflows Organized
Arkian automates multilingual scripts, voice outputs, and structured language packages, with validation and packaging built into a workflow for small teams.

TL;DR

  • Store numbers as numbers and moments as UTC instants. Format only at display time, with the user’s locale.
  • Use the built-in APIs (Intl in JavaScript, ICU, .NET, Java) instead of string concatenation.
  • Currency needs more than a symbol: placement, separators and ISO 4217 codes all vary, and $ alone is ambiguous.
  • Week start, calendar and time zone are locale data too. “Today” can be wrong if you hardcode Sunday.
  • Keep numbers and dates out of translated sentences where you can, and pass them as typed placeholders.

Table of Contents

What actually changes from one locale to the next

The same value is written differently around the world. The number 1,234.56 appears as “1,234.56” in US English, while Polish formatting produces “1 234,56”. Two things moved: the grouping separator and the decimal separator. A user who reads “1.234” in a German app and “1.234” in a US app is reading two different numbers, one thousand two hundred thirty-four and a little over one.

Dates are worse, because a wrong guess is silent. The string 04/05/2027 is April 5 for a US reader and May 4 for most readers in Britain. Nothing crashes. The user just books the wrong day.

Here is the checklist of things that vary:

Element What varies Typical failure
Decimal separator Period, comma, others A price of 1,5 parsed as 15
Grouping separator Comma, period, space, apostrophe 1.000 read as 1
Date order Month-day-year, day-month-year, year-month-day 04/05 read as the wrong month
Month and weekday names Language and capitalization Hardcoded English names in a French UI
Time format 12-hour or 24-hour clock “17:00” shown to a reader expecting 5 PM
Week start Sunday, Monday or Saturday Calendars that begin on the wrong day
Currency Symbol, position, spacing, code “$” meaning three different currencies
Negative numbers Minus sign or parentheses (accounting) Losses displayed as profits
Numerals Latin digits or other digit systems Unreadable digits in some Arabic markets

The Unicode CLDR number patterns page shows how this is expressed in data: a pattern such as “#,###.00” applied to 12345.678 can produce “12’345,67” when a locale uses an apostrophe for grouping and a comma for decimals. Patterns are data, not code, which is exactly why you should not rewrite them yourself.

Format at the edge, store raw

The rule that prevents most bugs is simple. Your database, API responses and internal state hold machine values: integers or decimals for amounts, ISO 8601 timestamps in UTC for moments. Display strings are produced at the edge, one step before the screen, from the value plus the user’s locale.

Raw values formatted for different locales

The ICU documentation frames it well: you cannot display the computer representation of the number 103, only a textual representation of it, and formatters are what translate between the two. If the stored value is already a formatted string, you have lost the ability to reformat it for the next user.

Three practical consequences:

  1. Never parse a displayed string back into data. If a field accepts typed input, parse it with a locale-aware parser, or accept only a machine format in an API.
  2. Never use a localized string as a key or a cache identifier. A key that includes “1,234.56” breaks for every other locale.
  3. Log and exchange data in neutral formats. Support tickets are far easier to read when timestamps are ISO 8601 and amounts are plain decimals.

Use the platform APIs, not string building

The most dependable approach is the native internationalization layer your platform already ships. In JavaScript that is the Intl namespace, which the MDN reference describes as the ECMAScript Internationalization API, with constructors for numbers, dates, plurals, lists and more. Other stacks have equivalents: ICU, .NET and Java all give you control over formatting.

Numbers

Intl.NumberFormat enables language-sensitive number formatting. MDN’s own example formats 123456.789 as euros for the de-DE locale. The W3C’s guidance on number, currency and unit formatting gives the same advice: format numbers, currencies and units according to the locale, and let Intl.NumberFormat do the work.

const n = 1234567.891;
new Intl.NumberFormat('en-US').format(n); // 1,234,567.891
new Intl.NumberFormat('de-DE').format(n); // 1.234.567,891
new Intl.NumberFormat('fr-FR').format(n); // 1 234 567,891 (with a narrow no-break space)

The French result uses a non-breaking space on purpose, so a number never wraps across two lines. That is a detail you would not think to build by hand.

Dates and times

The Intl.DateTimeFormat constructor produces locale-aware date and time strings, and you choose the shape with options such as dateStyle and timeStyle rather than assembling pieces.

const d = new Date(Date.UTC(2027, 3, 5, 15, 30));
new Intl.DateTimeFormat('en-US', { dateStyle: 'long', timeStyle: 'short', timeZone: 'America/New_York' }).format(d);
new Intl.DateTimeFormat('en-GB', { dateStyle: 'long', timeStyle: 'short', timeZone: 'Europe/London' }).format(d);

Pass dateStyle and timeStyle instead of hand-picking month: '2-digit', because the style presets let the locale decide the order, separators and 12-hour or 24-hour clock. Pass a timeZone explicitly when the event belongs to a place, such as a webinar or a flight, rather than to the viewer.

The anti-patterns

  • month + '/' + day + '/' + year: bakes in US order.
  • '$' + amount.toFixed(2): bakes in symbol position, decimal separator and one currency.
  • amount.toString().replace('.', ','): fixes one locale and breaks grouping.
  • A hand-maintained table of formats per country. CLDR guidance points the other way: lean on established locale-data libraries, because custom mapping tables cannot stay accurate across every region and scenario.

Currency localization rules

Currency is where number formatting and business logic collide, so it deserves its own rules.

Format the amount and keep the currency separate. An amount is a number plus an ISO 4217 code such as USD, EUR or CAD. The display is derived from both. Intl.NumberFormat with style: 'currency' and a currency option handles symbol, placement and separators in one call.

Do not equate a symbol with a currency. The dollar sign is shared by several currencies. Per CLDR’s currency symbol guidance, each currency code can be represented in several ways, and you need to check which currency a symbol belongs to. In a US English interface, “$” reads as US dollars, but in an app that shows USD, CAD and AUD side by side, a bare symbol is ambiguous. Show the code or a qualified symbol (US$, CA$) in multi-currency screens.

Respect position and spacing. Microsoft’s globalization guidance notes that each country or region has its own standards for writing currency values, and that libraries like ICU and frameworks like .NET and Java let you control the output. Some locales put the symbol before the number, others after it, with or without a space.

Handle accounting formats. CLDR also defines accounting patterns, where negative amounts appear in parentheses instead of with a minus sign. If your product shows invoices or ledgers, use the accounting style where your audience expects it.

Do not convert silently. Formatting is not conversion. Showing 19.00 in a different locale’s style changes how it looks, not what it is. Converting between currencies needs a rate, a date for that rate and a rounding rule, and it should be a visible product decision.

Mind the decimals. The number of minor-unit digits depends on the currency, not on the locale. Let the API decide, and store amounts as integers in the minor unit or as exact decimals, never as binary floats.

For reference, here is how one price in the same app might render, using the pricing of a real plan: a membership at 19.00 CAD per month. A US reader of a multi-currency page should see the code or a qualified symbol next to it, so it is never mistaken for US dollars.

Time zones, calendars and the start of the week

Date localization is not only month and day order. The MDN documentation for Intl.DateTimeFormat covers calendars and time zones as well as formatting, and the standard approach is to store instants in UTC and convert to the user’s time zone for display.

The week is locale data too. In the US the week starts on Sunday, while other regions start on Monday or Saturday. If you hardcode Sunday, a weekly chart, a “this week” filter or a calendar grid will look wrong to much of the world, and “today” can land on the wrong side of a day boundary when the offset is mishandled.

Some habits that keep you out of trouble:

  • Use named IANA time zones (America/Chicago), not fixed offsets. Offsets change with daylight saving time; names carry the rules.
  • For calendar dates with no time (a birthday, an invoice due date), store a plain date, not midnight UTC. Otherwise it shifts a day in some zones.
  • Show the time zone whenever an event is shared between people in different places.
  • Take week start and weekend days from locale data, not constants.
  • Use ISO 8601 (2027-04-05) for anything a machine reads: APIs, exports, file names.

Keep numbers and dates out of translated sentences

Here the formatting problem meets the translation problem. A sentence like “You have 3 messages since April 5” has a number, a noun that changes with the number, and a date. Translate it as a flat string and you get one of two outcomes: the date is frozen in one format, or the translator is forced to guess where a variable goes.

The fix is to translate a template with typed placeholders and let the formatter fill them in:

"inbox.summary": "{count, plural, one {# message} other {# messages}} since {date, date, medium}"

Now the plural rule, the number format and the date style all come from the locale at runtime, and the translator only handles the words. Our post on three ICU message format checks to run before shipping walks through where these templates go wrong.

A few related rules:

  • Never split a sentence into fragments around a variable. Word order differs between languages.
  • Do not put pre-formatted numbers or dates in a translation file. Put the placeholder.
  • Make sure your locale codes are valid before any of this runs. Formatting depends on the locale tag, and a malformed tag silently falls back to a default. See six BCP 47 rules that prevent locale breaks.

Where this breaks in real localization files

Most number and date bugs in shipped apps are not in the formatter call. They come from files.

  • A translator “helpfully” localizes a literal. A string says “Offer ends 12/31” and the translator changes it to “31/12” for German. That works until the next release, when the English source is edited and the translation drifts.
  • Hardcoded separators in the source. The English string includes “1,000 users” as text, so every language inherits the comma.
  • Mixed platform formats. The iOS file uses a placeholder style that the Android file does not, so the same date logic is implemented twice, differently. If you ship both, check iOS .strings and Android XML outputs against each other.
  • Plural and number forms missing for some languages. A file that has “one” and “other” works in English and fails in languages that need more categories.
  • Audio and scripts. Voice output is the least forgiving. A text-to-speech engine reading “04/05” or “1.234” will say the wrong thing aloud, so numbers and dates in scripts should be written the way they should be spoken in each language.

A short pre-release test pass catches nearly all of it:

  1. Run the UI in at least one locale with a different decimal separator, one with a different date order, and one right-to-left locale.
  2. Test a negative amount, a zero, a very large number and a number with many decimals.
  3. Test a date near midnight and near a daylight-saving change, in a time zone far from the server.
  4. Search the source strings for digits and slashes. Each hit is either a placeholder candidate or a deliberate literal.
  5. Read the generated audio for one numeric-heavy script.

Why it matters for trust

A date or number in an unfamiliar format reads as a small signal that the product was not made for you. Microsoft’s globalization documentation makes the same point about currency: each locale has its own conventions, and users notice when a product ignores them. Users rarely complain; they just hesitate before entering a card number.

The same applies beyond the app. If you publish localized marketing pages or help content, those pages need the same discipline, and tools for multilingual SEO content only help if the numbers, dates and prices on the page match what the reader expects.

Our perspective

We build localization production for small teams, and the pattern we see is consistent: the formatter is rarely the problem. The problem is the handoff. Strings travel through spreadsheets, chat threads and review passes, and somewhere along the way a literal date, a pasted price or a half-translated placeholder slips in.

Our view is that numbers and dates should be decided once, in the source, as placeholders with types, and then checked automatically on every language file before anyone reviews it. That is why we validate and package outputs as part of production rather than leaving it to a manual pass at the end. A reviewer’s time is better spent on tone than on spotting that “1.000” means something different in German.

We also think small teams should not need repository access or a full translation management system to get this right. Clean, structured files, checked for placeholder integrity and shaped for each platform, are enough. Our Quiet Harbour case study shows what a coherent localized product looks like across several languages.

— Arkian

Producing the files without the manual work

If you ship an app or content in several languages and want the formatting checked as part of production, Arkian generates localization strings, voice output and structured language packages, delivered as JSON, iOS strings, Android XML, YAML and MP3/WAV files. Placeholders stay intact, and the files arrive packaged for review. You can start with a membership at 19.00 CAD per month, or buy one-off packs: Starter at 29.00 CAD, Pro at 79.00 CAD and Studio at 249.00 CAD. Details are on the pricing page.

A working checklist

  • Values stored raw: numbers as numbers, instants in UTC, calendar dates as plain dates.
  • All display goes through Intl, ICU or your platform’s equivalent, with a valid locale tag.
  • Currency shown with code or qualified symbol wherever more than one currency can appear.
  • Week start, time format and time zone come from locale data and user settings.
  • Translations contain typed placeholders, not pre-formatted values.
  • Voice scripts spell out numbers and dates the way each language says them.
  • A release test covers one locale per formatting family.

FAQ

What is the difference between number localization and translation?

Translation changes the words. Number localization changes how values are written: separators, digit shapes, currency position and date order. A fully translated French screen that still shows “1,234.56” and “04/05/2027” in US style is only half localized.

Should I format dates on the server or the client?

Format where you know the user’s locale and time zone, which is usually the client. If you must format on the server, for emails or PDFs, pass the user’s saved locale and time zone explicitly instead of using the server’s defaults. Either way, send raw values over the wire.

Can I use $ for every dollar currency?

Not safely. The dollar sign is shared by several currencies, and CLDR advises checking which currency a symbol stands for. In multi-currency screens, show the ISO 4217 code or a qualified symbol so a CAD price is never read as USD.

Do I need a library if the browser already has Intl?

For formatting, usually not. Intl.NumberFormat and Intl.DateTimeFormat cover most needs without extra weight. You may still want a library for date arithmetic, recurring events or server-side formatting on stacks without built-in support.

How do I localize numbers inside translated strings?

Use placeholders with types, such as plural, number and date arguments in ICU message format, and let the formatter fill in the value at runtime. Translators then adjust word order and plural forms without touching the value itself.

Sources