Back to BlogArchitecture & Engineering

Internationalising a SaaS: i18n, RTL and Locale Data Without a Rewrite

Rupak Amin

Founder & Lead Engineer, RAITHub

10 min read

RAITHub ships and tests production software. See QA as a Service or talk to us.

Internationalise a SaaS by building for it before you have a second language: keep every user-facing string out of the code and in message files; express plurals, gender and interpolation as rules a translator can honour; format dates, numbers and currency with the locale, never by hand; and make the layout direction-aware so it mirrors for right-to-left languages. Retrofitting these into a shipped product is the expensive path.

This is engineering guidance for SaaS on a modern web stack. RTL is treated as an engineering skill, not a translation service. If you would rather have it built and tested for you, see how RAITHub would build this below.

What is the difference between i18n and localisation?

Internationalisation (i18n) is the engineering that makes a product able to adapt: no hard-coded text, no assumptions that a day is "MM/DD/YYYY" or that text flows left to right. Localisation (l10n) is adapting it for one locale: the translations, the regional formats, the cultural choices. i18n is yours to build once; localisation is added per market. The order matters, because a product that was not internationalised cannot be localised without touching every screen.

ConcernNaive versionInternationalised version
TextStrings in the codeKeys resolved from per-locale message files
Plurals"1 item(s)" or an if/elseLocale plural rules (some languages have up to six forms)
Dates and numbersHand-formattedIntl APIs that format by locale
LayoutLeft-to-right onlyDirection-aware, mirrors for RTL
Money"$" prependedCurrency formatted per locale, stored in minor units

How should translatable text be structured?

Move every string the user sees into message files keyed by a stable identifier, and resolve the key at render time for the active locale. A translator then edits text, never code, and a missing translation can fall back to the default language instead of showing a blank.

// en.json         { "cart.title": "Your cart", "cart.items": "{count, plural, one {# item} other {# items}}" }
// ar.json         { "cart.title": "سلتك", "cart.items": "{count, plural, zero {لا عناصر} one {عنصر} ... other {# عنصر}}" }

import { IntlMessageFormat } from 'intl-messageformat'

export function t(messages: Record<string, string>, key: string, locale: string, vars?: object) {
  const template = messages[key] ?? key // fall back to the key, never a blank
  return new IntlMessageFormat(template, locale).format(vars)
}

// t(ar, 'cart.items', 'ar', { count: 3 }) applies Arabic plural rules automatically.

Use the ICU MessageFormat syntax for plurals, gender and interpolation, rather than concatenating fragments. Gluing "You have " + count + " items" assumes English word order and a single plural form; Arabic has up to six plural categories and Polish three, and the Unicode plural rules define which forms each language needs. ICU keeps that logic in the message, where the translator controls it.

How do you format dates, numbers and currency by locale?

Never build a date or number string by hand. The browser's Intl APIs format for a locale, including the calendar, separators, currency symbol and decimal places.

new Intl.DateTimeFormat('ar-EG', { dateStyle: 'long' }).format(date)   // Arabic, Egyptian conventions
new Intl.NumberFormat('de-DE').format(1234.5)                          // "1.234,5" (dot groups, comma decimal)
new Intl.NumberFormat('ja-JP', { style: 'currency', currency: 'JPY' }).format(1000) // "¥1,000", no decimals

Store timestamps in UTC and money in integer minor units, and let the formatter decide presentation; the money rules are in the multi-currency support guide. Keep locale (how to format) separate from currency (what the money is) and from time zone (when to bucket), because a user in Germany might pay in dollars and read your dashboard in Berlin time.

What does supporting right-to-left actually take?

More than translating into Arabic or Hebrew. The whole layout mirrors: text aligns right, the sidebar moves, icons that imply direction flip, and progress flows the other way. Build it with logical CSS properties so the browser mirrors automatically when the document direction changes.

/* Physical properties do NOT mirror; logical properties do. */
.panel { margin-inline-start: 1rem; padding-inline: 1.5rem; text-align: start; }
/* Set direction once, high up; children inherit it. */
html[dir="rtl"] { direction: rtl; }

Logical properties (margin-inline-start, padding-inline, text-align: start) resolve against the writing direction, so one stylesheet serves both. Mixed content, such as an English product code inside an Arabic sentence, needs the Unicode bidirectional algorithm to order it correctly; test it rather than assuming. RAITHub treats RTL as a QA discipline, with a dedicated checklist in the Arabic RTL QA checklist.

Where do locale, currency and time zone each belong?

Store the user's preferred language, their time zone, and the currency context separately, and never infer one from another. A browser's language header is a hint for a first guess, not the user's settled choice, so let them pick and persist it. The active locale drives text and formatting; the time zone drives when a "day" starts, as in the SaaS dashboard guide; the currency drives money, above.

Do-it-yourself estimate: extracting strings, wiring a message framework and formatting with Intl is 1–2 weeks on a small product; full RTL support and the QA pass add one to two more. The main risk is hidden hard-coded strings and concatenated sentences that only surface when a translator sees them.

Buy, build or hire?

OptionExamplesChoose this whenWatch out for
A translation management platformA hosted service for managing message files and translatorsYou have many strings and several languages to keep in syncIt manages translations, not your code structure or RTL layout
Machine translation onlyAn automated translation APIA first draft, or low-stakes internal textPlural, gender and tone errors reach users; weak for a product UI
Custom i18n buildAn i18n library plus ICU messages, as hereThe product is going multi-market and must mirror for RTLYou own the extraction, plural rules and the RTL QA
Hire a team to build itRAITHub or another studioYou want it internationalised once, correctly, with RTL testedGet the pseudo-localisation and RTL tests in the handover

How do you test internationalisation?

  • Pseudo-localisation: render the UI with accented, lengthened placeholder text to expose hard-coded strings and layouts that break when text grows.
  • Plurals: assert counts of 0, 1, 2 and many render correctly in a language with more than two plural forms.
  • Formatting: assert dates, numbers and currency match the locale's conventions, including a zero-decimal currency.
  • RTL: switch direction and assert the layout mirrors, alignment flips, and mixed LTR/RTL content orders correctly.
  • Fallback: remove a translation and assert the default language shows, never a blank or the raw key in production.

How RAITHub would build this

  • Message architecture: all user-facing text extracted to per-locale files with ICU plural, gender and interpolation, and a safe fallback.
  • Formatting: dates, numbers and currency formatted with Intl by locale, with locale, time zone and currency kept as separate settings.
  • RTL: a direction-aware layout built on logical CSS properties, with bidirectional content handled and checked.
  • Tests: pseudo-localisation, plural, formatting and RTL tests in CI.

Timeline: internationalising a product sits in the 4–6 week fixed scope for a focused build, longer where RTL and many locales are in scope. You receive: i18n and RTL tests in CI, handover docs and runbooks, and full IP under NDA.

Next step: a free 15-minute technical audit, then a written fixed quote. See the SaaS development service, pair it with the Arabic RTL QA checklist, and book the audit.

Frequently asked questions

What is the difference between i18n and localisation?

Internationalisation is the engineering that makes a product able to adapt: no hard-coded text, no layout or format assumptions. Localisation is adapting it for one locale with translations and regional formats. You build i18n once; you add localisation per market.

Why shouldn't I just concatenate strings for plurals?

Because word order and plural forms differ by language. Arabic has up to six plural categories, Polish three, and some languages reorder the sentence. ICU MessageFormat keeps plural and interpolation logic in the message, where the translator controls it.

How much work is right-to-left (RTL) support?

More than translating text: the layout mirrors, alignment and directional icons flip, and mixed-direction content must order correctly. Logical CSS properties let one stylesheet serve both directions, but RTL still needs its own QA pass.

Should I auto-detect the user's language?

Use the browser's language header only as a first guess, then let the user choose and persist their language, time zone and currency separately. Inferring one from another, such as currency from language, produces wrong results for many users.

Can I add internationalisation after launch?

Yes, but it is more expensive, because every hard-coded string and left-to-right assumption must be found and changed across the product. Building the structure early, even with one language, makes adding markets a content task rather than a rewrite.

Can I just run my app through machine translation and call it localised?

Machine translation covers strings, but localisation also means dates, numbers, currency, plurals, right-to-left layout and locale-specific content. Auto-translation alone produces broken plurals and layouts that overflow. Build the i18n structure first, then feed translations into it, machine or human, so the framework holds whatever quality you choose.

Will adding internationalisation risk breaking features that already work?

Not if it is done incrementally with tests. We extract strings and locale logic behind a framework while the default language keeps rendering exactly as before, and tests assert existing screens are unchanged. You receive that test suite and handover docs, so the migration is verifiable rather than a leap of faith.

We want to sell in a few more countries next year — how early should we build internationalisation and what does it involve?

Build the structure before you have the second language: externalise strings, store locale on the user and tenant, and avoid hard-coded formats and left-to-right assumptions. That turns each new market into a translation and testing task rather than a rewrite. Doing it after launch is far more expensive because every string must be found.

Who should I hire to internationalise my SaaS without a rewrite?

A team that treats i18n as architecture: no hard-coded strings, plural and interpolation rules that survive translation, locale-aware dates and numbers, and a layout that mirrors for right-to-left. RAITHub builds the structure so new languages drop in without touching features. Ask any vendor how they handle plurals and right-to-left layout, not just string files.

Is a localisation platform like Lokalise or Crowdin an alternative to building i18n myself?

A localisation platform manages the translation workflow, who translates what and how it ships, which is genuinely useful. It does not do the engineering: extracting hard-coded strings, handling plurals and interpolation, locale-aware formatting and right-to-left layout. Use a platform to manage translators; build the i18n architecture in your code so the translations have somewhere correct to go.

What's involved in internationalising a SaaS, and how long does it take?

Extracting hard-coded strings, a plural and interpolation system, locale-aware dates and numbers, a right-to-left-capable layout, and a way to load the right locale. Built into a young app it is a modest foundation; retrofitting it onto a large app is the longer job and should start with a pass to find every hard-coded string. Translation itself is separate and ongoing.

Can I just hard-code each language into my app myself instead of building i18n?

You can, but it multiplies maintenance: every new string must be edited in each language branch, plurals and formatting drift, and right-to-left layout gets bolted on badly. A proper i18n structure, strings externalised, plural and interpolation rules, locale-aware formatting, lets you add a language by dropping in a file. Build the structure once rather than hard-coding languages you will fight forever.

internationalisationi18nlocalisationRTLSaaSlocaleTypeScript

Ready to discuss your project?

Book a free 15-minute technical audit with our engineering team.