Internationalization: The Global Language

· 8 min read
i18nInternationalizationlocalizationangularfrontendaccessibilityglobalinclusive-design

Introduction

When I worked on the Orpak CMS — a platform serving fuel retail operators across multiple countries — the Internationalization requirement was not optional. The platform needed to work in English, Hebrew, and Arabic. Hebrew and Arabic read right-to-left. The currency formatting, date conventions, and number separators were different in every region. A gas station operator in Tel Aviv and one in Dubai were using the same application, and neither of them should have had to think about the other’s language to use it.

That project gave me a concrete understanding of something that most frontend tutorials treat as a footnote: Internationalization is not a feature you add at the end. It is an architectural decision that shapes how you write every string, every date, every number, and every layout in the application from the very beginning.

This article is about what Internationalization is, why it matters beyond the obvious business case, what the concepts are, and how to introduce it properly — whether you are starting fresh or adding it to an existing project.

What Internationalization Actually Means

The terms matter because they are used interchangeably when they are not the same thing.

Internationalization (i18n) — the process of designing and building an application so that it can be adapted to different languages and regions without engineering changes. The abbreviation i18n counts the eighteen letters between the “i” and the “n.” Internationalization is the engineering work.

localization (l10n) — the process of actually adapting the application for a specific language or region — translating the strings, adjusting date and number formats, accommodating cultural conventions. localization is the translation and adaptation work.

Globalization (g11n) — the combination of both, describing the full practice of making software that serves a global audience.

The reason the distinction matters: Internationalization is the prerequisite. If the application is not built to be internationalized, localization is not a content task — it is a reengineering task. You cannot translate an application that has hardcoded strings scattered through components. You cannot support RTL layouts in an application whose CSS was written entirely with physical directional properties. The Internationalization work happens first, in the code. The localization work happens after, in the content.

Why It Matters Beyond the Business Case

The business case for Internationalization is straightforward: a product that only works in one language has a market that is a fraction of what it could be. But I want to make a different argument first.

When you build an application in one language and one region without thought for other languages and regions, you are making an implicit assumption about who the software is for. You are assuming your users share your locale, your number conventions, your date format, your text direction. That assumption is usually comfortable because it is invisible — you do not notice you have made it until you encounter someone it excludes.

The person who uses a screen reader in Arabic and encounters a right-to-left application where the layout mirrors correctly is getting the same experience as an English speaker. The person who encounters an application that has been translated into their language but whose dates are formatted in a way they cannot parse is being told, implicitly, that they were not really the intended user — just an afterthought.

Internationalization is, in this sense, a form of respect. It is the engineering decision that says: the people who use this application may not share my native language, my regional conventions, or my text direction, and I am going to make sure that difference does not matter.

This connects directly to accessibility. Both Internationalization and accessibility are practices of building for the full range of human variability rather than the specific human the developer imagined when they wrote the code. Both require deliberate decisions during development rather than retrofitting after. And both are frequently treated as optional features rather than baseline expectations.

The Core Concepts

String externalization

The foundational concept. Every piece of user-facing text in the application lives in a translation file — not hardcoded in components.

// ❌ Hardcoded string — cannot be translated without changing the component
@Component({
  template: `<h1>Welcome back, {{ user.name }}</h1>`
})

// ✅ Externalized string — lives in a translation file
@Component({
  template: `<h1>{{ 'WELCOME_BACK' | translate: { name: user.name } }}</h1>`
})
// en.json
{
  "WELCOME_BACK": "Welcome back, {{ name }}",
  "TICKET_COUNT": "You have {{ count }} open ticket",
  "TICKET_COUNT_plural": "You have {{ count }} open tickets"
}

// ar.json
{
  "WELCOME_BACK": "مرحباً بعودتك، {{ name }}",
  "TICKET_COUNT": "لديك {{ count }} تذكرة مفتوحة",
  "TICKET_COUNT_plural": "لديك {{ count }} تذاكر مفتوحة"
}

// he.json
{
  "WELCOME_BACK": "ברוך שובך, {{ name }}",
  "TICKET_COUNT": "יש לך {{ count }} כרטיס פתוח",
  "TICKET_COUNT_plural": "יש לך {{ count }} כרטיסים פתוחים"
}

Pluralization rules — more complex than you expect

English has two plural forms: singular and plural. Arabic has six. Russian has three, with different rules for quantities ending in 1, 2-4, and 5+. Polish has four. The Unicode CLDR (Common Locale Data Repository) documents the plural rules for every language.

A translation system that only handles singular and plural will produce grammatically incorrect output in many languages. Use a library that handles CLDR plural categories:

// Angular's built-in ICU message format — handles complex pluralization
@Component({
  template: `
    <span i18n>
      {ticketCount, plural,
        =0 {No open tickets}
        =1 {One open ticket}
        other {{{ ticketCount }} open tickets}
      }
    </span>
  `
})
// ngx-translate with ICU via @ngx-translate/core
// en.json
{
  "TICKET_STATUS": "{count, plural, =0{No tickets} =1{One ticket} other{# tickets}}"
}

Date, time, and number formatting

Date formats vary dramatically by locale. November 3rd 2026:

  • US English: 11/03/2026
  • UK English: 03/11/2026
  • German: 03.11.2026
  • Japanese: 2026年11月3日
  • Arabic: ٣‏/١١‏/٢٠٢٦

Never format dates or numbers manually. Use the platform’s built-in Intl API:

// The Intl API — browser-native, no library required
// Formats correctly for any locale

// Date formatting
const date = new Date('2026-11-03');

new Intl.DateTimeFormat('en-US').format(date); // "11/3/2026"
new Intl.DateTimeFormat('en-GB').format(date); // "03/11/2026"
new Intl.DateTimeFormat('de').format(date); // "3.11.2026"
new Intl.DateTimeFormat('ar-SA').format(date); // "٣‏/١١‏/٢٠٢٦"

// Number formatting
new Intl.NumberFormat('en-US').format(1234567.89); // "1,234,567.89"
new Intl.NumberFormat('de').format(1234567.89); // "1.234.567,89"
new Intl.NumberFormat('ar').format(1234567.89); // "١٬٢٣٤٬٥٦٧٫٨٩"

// Currency formatting
new Intl.NumberFormat('en-US', {
  style: 'currency',
  currency: 'USD',
}).format(1500); // "$1,500.00"

new Intl.NumberFormat('de', {
  style: 'currency',
  currency: 'EUR',
}).format(1500); // "1.500,00 €"

new Intl.NumberFormat('ar-SA', {
  style: 'currency',
  currency: 'SAR',
}).format(1500); // "١٬٥٠٠٫٠٠ ر.س."

In Angular, use the built-in pipes — they wrap the Intl API with locale awareness:

<!-- Angular i18n pipes — locale-aware by default -->
<span>{{ ticket.createdAt | date:'mediumDate' }}</span>
<span>{{ fuelVolume | number:'1.2-2' }}</span>
<span>{{ price | currency:'USD' }}</span>

RTL — Right-to-Left layout

Arabic, Hebrew, Persian, and Urdu are read right-to-left. RTL support is not just direction: rtl on the body — it requires the entire layout to mirror. The sidebar that is on the left in LTR is on the right in RTL. The icon that is before text in LTR is after text in RTL. The scroll position of a horizontal scroll container is reversed.

The correct tool is CSS logical properties, as I described in the Orpak project write-up:

/* ❌ Physical properties — hardcoded to LTR */
.card {
  padding-left: 1rem; /* always left, even in RTL */
  margin-right: 1.5rem; /* always right, even in RTL */
  border-left: 3px solid var(--color-primary); /* always left */
  text-align: left; /* always left */
}

/* ✅ Logical properties — follow document direction automatically */
.card {
  padding-inline-start: 1rem; /* left in LTR, right in RTL */
  margin-inline-end: 1.5rem; /* right in LTR, left in RTL */
  border-inline-start: 3px solid var(--color-primary);
  text-align: start; /* left in LTR, right in RTL */
}

Toggle RTL with a single attribute on the root element:

<!-- LTR -->
<html lang="en" dir="ltr">
  <!-- RTL — the entire layout mirrors through logical properties -->
  <html lang="ar" dir="rtl"></html>
</html>

When you set dir="rtl" and have written your CSS with logical properties throughout, the layout mirrors automatically. No per-component overrides. No parallel stylesheet. One attribute change.

Introducing i18n into an Existing Angular Project

The most common situation is not a greenfield project — it is an existing application that needs to be internationalized. Here is the order I would approach it in.

Step one: Audit the hardcoded strings

Before installing anything, run an audit. Find every hardcoded user-facing string in the application. In a large Angular project this is a grep for strings in template files and TypeScript services — anything that would be read by a user that is not coming from a translation key.

# Find potential hardcoded strings in templates
# Looks for text content between HTML tags
grep -rn '>[A-Z][^<>{}]*<' src/app --include="*.html" | grep -v '{{' | grep -v "i18n"

This gives you the scope of the work. The scope is almost always larger than expected.

Step two: Install and configure ngx-translate or Angular i18n

Two main options for Angular:

Angular’s built-in i18n — compile-time extraction and translation. Each locale is a separate build. Better performance, more complex deployment.

ngx-translate — runtime translation switching. One build, locale loaded dynamically. Easier to set up for most projects, supports runtime language switching.

// ngx-translate setup — app.module.ts
import { TranslateModule, TranslateLoader } from '@ngx-translate/core';
import { TranslateHttpLoader } from '@ngx-translate/http-loader';
import { HttpClient } from '@angular/common/http';

export function createTranslateLoader(http: HttpClient) {
  return new TranslateHttpLoader(http, './assets/i18n/', '.json');
}

@NgModule({
  imports: [
    TranslateModule.forRoot({
      defaultLanguage: 'en',
      loader: {
        provide: TranslateLoader,
        useFactory: createTranslateLoader,
        deps: [HttpClient],
      },
    }),
  ],
})
export class AppModule {}
// Language initialisation and switching service
@Injectable({ providedIn: 'root' })
export class LanguageService {
  constructor(private translate: TranslateService) {}

  initialise(): void {
    const saved = localStorage.getItem('locale') || 'en';
    this.setLanguage(saved);
  }

  setLanguage(locale: string): void {
    this.translate.use(locale);
    localStorage.setItem('locale', locale);

    // Set document direction for RTL languages
    const rtlLocales = ['ar', 'he', 'fa', 'ur'];
    document.documentElement.setAttribute(
      'dir',
      rtlLocales.includes(locale) ? 'rtl' : 'ltr'
    );
    document.documentElement.setAttribute('lang', locale);
  }
}

Step three: Extract and replace strings

Replace hardcoded strings with translation keys. The convention I use: FEATURE.COMPONENT.KEY.

// Before
@Component({
  template: `
    <h1>Ticket Management</h1>
    <p>You have {{ count }} open tickets</p>
    <button>Create Ticket</button>
  `
})

// After
@Component({
  template: `
    <h1>{{ 'TICKETS.LIST.TITLE' | translate }}</h1>
    <p>{{ 'TICKETS.LIST.OPEN_COUNT' | translate: { count } }}</p>
    <button>{{ 'TICKETS.LIST.CREATE_BTN' | translate }}</button>
  `
})
// src/assets/i18n/en.json
{
  "TICKETS": {
    "LIST": {
      "TITLE": "Ticket Management",
      "OPEN_COUNT": "You have {{ count }} open tickets",
      "CREATE_BTN": "Create Ticket"
    }
  }
}

For strings in TypeScript (service messages, error messages, notification text), inject TranslateService:

@Injectable({ providedIn: 'root' })
export class NotificationService {
  constructor(private translate: TranslateService) {}

  notifyResolved(ticketId: string): void {
    const message = this.translate.instant('TICKETS.NOTIFICATIONS.RESOLVED', {
      id: ticketId,
    });
    this.showToast(message);
  }
}

Step four: Replace physical CSS with logical properties

Work through the stylesheets and replace physical directional properties with their logical equivalents. This is the most time-consuming step in an existing project and the one most frequently skipped — which produces RTL layouts that partially mirror.

/* Global find and replace patterns */
margin-left     → margin-inline-start
margin-right    → margin-inline-end
padding-left    → padding-inline-start
padding-right   → padding-inline-end
border-left     → border-inline-start
border-right    → border-inline-end
left: 0         → inset-inline-start: 0
right: 0        → inset-inline-end: 0
text-align: left   → text-align: start
text-align: right  → text-align: end
float: left     → float: inline-start
float: right    → float: inline-end

Not every physical property needs replacing — margin-top and padding-bottom have no directional meaning in LTR/RTL. Only the horizontal axis properties need the logical equivalents.

The Impact on Real People

The impact of Internationalization is often described in market terms — expanded audience, more revenue, broader reach. These are real. But the more immediate impact is simpler than that.

When a person encounters software in their own language, formatted in their regional conventions, with a layout that follows the natural direction of their writing, they are being told that they were considered. That the people who built the software thought about them specifically.

When they encounter the opposite — menus in a language they do not read, dates in a format they cannot parse, a layout that feels backwards because it was built for a different text direction — they are being told, implicitly, that they were not considered. That the software was built for someone else and they are using it by accident.

That experience is not neutral. It accumulates. It shapes who feels comfortable and capable using digital tools and who feels like an outsider to them.

Conclusion

Internationalization is an architectural decision disguised as a content task. It looks like translation — and translation is part of it — but the foundation is engineering: externalizing strings, using locale-aware formatting, writing CSS with logical properties, managing document direction. Without that foundation, translation is not possible at scale, and RTL support is not possible at all.

The good news is that the engineering foundation is not large. It is a set of habits more than a set of tools. Use the Intl API for dates and numbers. Use logical CSS properties for all horizontal layout. Externalise every user-facing string from the start. Set up a translation loading mechanism before you have translations to load. These are not expensive decisions — they are almost free when made at the start and expensive when retrofitted.

The languages your application does not speak today are not hypothetical future requirements. They are real users who are either waiting or who have already decided to use something else.

All articles