Internationalization

Angular Server Rendering: Internationalization (i18n)

The Universal Translator Magic

Imagine you have a magical book that can speak in any language. When a French kid opens it, the words become French. When a Japanese kid opens it, the words become Japanese. Your Angular app can be that magical book!

This magic is called Internationalization (we call it i18n because there are 18 letters between the “i” and “n” in “internationalization” - cool trick, right?).

Our Analogy: The Restaurant Menu

Think of your app as a restaurant. You have ONE kitchen (your code), but you want to give menus in different languages to different guests.

• Internationalization Setup = Setting up a printing system for menus
• Marking Translations = Putting little sticky notes on words that need translating
• Translation Files = Having separate menu cards for each language
• Locale Configuration = Knowing which guest speaks which language
• Format Functions = Making sure dates, numbers, and money look right for each country

1. Internationalization Setup

What Is It?

Before your app can speak different languages, you need to prepare it. It’s like setting up a translation booth at the United Nations - you need the equipment first!

How To Set It Up

First, add the localize package to your Angular project:

ng add @angular/localize

This adds the “translation booth” to your app.

What Happens?

graph TD
    A["Your Angular App"] --> B["ng add @angular/localize"]
    B --> C["polyfills.ts Updated"]
    B --> D["angular.json Configured"]
    C --> E["Ready for Translation!"]
    D --> E

After running the command:

• A special file gets added to help translations work
• Your app configuration learns about translations
• You’re ready to start marking words for translation!

2. Marking Translations

What Is It?

Remember those sticky notes? Now you put them on every word or sentence that needs to be translated. In Angular, we use the i18n attribute.

The Simple Way

<h1 i18n>Welcome to our App!</h1>

That’s it! The i18n attribute is your sticky note. It tells Angular: “Hey, this text needs translation!”

Adding More Details

You can give translators helpful hints:

<h1 i18n="site header|A greeting
  shown on the homepage">
  Welcome to our App!
</h1>

The format is:

• Before | = What/Where (context)
• After | = Description for translators

Giving an ID

<h1 i18n="@@welcomeHeader">
  Welcome to our App!
</h1>

The @@ creates a unique name. Like naming your sticky note so you can find it easily!

Translating Attributes

What about things like placeholder text?

<input
  i18n-placeholder
  placeholder="Enter your name">

Add i18n- before any attribute name to translate it!

3. Translation Files

What Are They?

These are the actual “menu cards” in different languages. Angular creates a master file, and translators fill in translations.

Creating the Master File

Run this command:

ng extract-i18n

This creates messages.xlf - your master translation file. It’s like a blank menu waiting to be filled.

What’s Inside?

<trans-unit id="welcomeHeader">
  <source>Welcome to our App!</source>
  <target><!-- Translation here --></target>
</trans-unit>

• source = Original text (English)
• target = Where the translation goes

Creating Language Files

Copy the master file for each language:

• messages.fr.xlf (French)
• messages.es.xlf (Spanish)
• messages.ja.xlf (Japanese)

Then fill in the translations:

<trans-unit id="welcomeHeader">
  <source>Welcome to our App!</source>
  <target>Bienvenue dans notre App!</target>
</trans-unit>

graph TD
    A["ng extract-i18n"] --> B["messages.xlf"]
    B --> C["messages.fr.xlf"]
    B --> D["messages.es.xlf"]
    B --> E["messages.ja.xlf"]
    C --> F["French Translator"]
    D --> G["Spanish Translator"]
    E --> H["Japanese Translator"]

4. Locale Configuration

What Is It?

A locale is like a guest’s name tag that says:

• What language they speak
• What country they’re from

Examples: en-US (English, USA), fr-FR (French, France), ja-JP (Japanese, Japan)

Configure in angular.json

{
  "projects": {
    "your-app": {
      "i18n": {
        "sourceLocale": "en-US",
        "locales": {
          "fr": "src/locale/messages.fr.xlf",
          "es": "src/locale/messages.es.xlf"
        }
      }
    }
  }
}

Building for Different Languages

ng build --localize

This creates separate app folders for each language!

graph TD
    A["ng build --localize"] --> B["dist/en-US/"]
    A --> C["dist/fr/"]
    A --> D["dist/es/"]

Server-Side Locale Detection

For Server Rendering, you can detect the user’s preferred language:

import { LOCALE_ID } from '@angular/core';

// In your server code
const userLocale =
  request.headers['accept-language']
  .split(',')[0] || 'en-US';

5. Format Functions

What Are They?

Different countries write dates, numbers, and money differently:

• USA: 12/25/2024, $1,000.00
• France: 25/12/2024, 1 000,00 €
• Japan: 2024年12月25日, ¥1,000

Angular’s format functions handle this automatically!

Date Formatting

import { formatDate } from '@angular/common';

const today = new Date();

// For US
formatDate(today, 'shortDate', 'en-US');
// Output: "12/25/24"

// For France
formatDate(today, 'shortDate', 'fr-FR');
// Output: "25/12/24"

Number Formatting

import { formatNumber } from '@angular/common';

const bigNumber = 1234567.89;

// For US
formatNumber(bigNumber, 'en-US');
// Output: "1,234,567.89"

// For Germany
formatNumber(bigNumber, 'de-DE');
// Output: "1.234.567,89"

Currency Formatting

import { formatCurrency } from '@angular/common';

const price = 1000;

// US Dollars
formatCurrency(price, 'en-US', '#x27;);
// Output: "$1,000.00"

// Euros in France
formatCurrency(price, 'fr-FR', '€');
// Output: "1 000,00 €"

Using Pipes in Templates

Even easier - use pipes directly in your HTML:

<!-- Date -->
<p>{{ today | date:'fullDate' }}</p>

<!-- Number -->
<p>{{ bigNumber | number }}</p>

<!-- Currency -->
<p>{{ price | currency:'EUR' }}</p>

Angular automatically uses the current locale!

The Complete Picture

graph TD
    A["1. Setup"] --> B["ng add @angular/localize"]
    B --> C["2. Mark Translations"]
    C --> D["Add i18n attributes"]
    D --> E["3. Extract & Create Files"]
    E --> F["ng extract-i18n"]
    F --> G["Translate .xlf files"]
    G --> H["4. Configure Locales"]
    H --> I["Update angular.json"]
    I --> J["5. Format Data"]
    J --> K["Use formatDate/Number/Currency"]
    K --> L["Build & Deploy!"]

Quick Summary

You Did It!

Your Angular app is now a universal translator. It can speak any language, show dates the way each country expects, and make everyone feel at home.

Remember:

1. Setup once with @angular/localize
2. Mark everything that needs translation
3. Create files for each language
4. Configure locales in your project
5. Format data to match local customs

Now your app can welcome the whole world!