@talenra/components documentation

Tutorial: Localization

In this tutorial we'll explore how to add internationalization (i18n) support to your Talenra application. We'll follow the same approach used in our tutorial app, where we progressively added support for multiple languages including German, French, and Italian.

The source code is available through our tutorials repository. You can follow along by looking at the localization-related commits.

Prerequisites

This tutorial assumes you completed the previous tutorial. We'll use the code from the first tutorial as our starting point.

If you want to start fresh, you can get the source code and checkout the state before localization was added:

Example :
# Clone the repository
git clone git@gitlab.svanet.ch:talenra/talenra-tutorials.git my-talenra-tutorial

# Change to your local directory
cd my-talenra-tutorial

# Review the commit history
git log --oneline

# Checkout the commit before localization was added
git checkout -b my/localization <commit-before-localization>

# Install dependencies
npm install

Step 1: Setting up Angular localize

First, we need to add Angular's localization support to our app. This provides the foundation for translating our application.

Add the localize package

Start by adding a reference to the localize types at the top of your src/main.ts file:

Example :
// src/main.ts
/// <reference types="@angular/localize" />

import { bootstrapApplication } from '@angular/platform-browser';
// ... rest of imports

Configure your build

Next, update your Angular configuration.

Include the localize polyfill in the build options:

Example :
// angular.json
// projects › talenra-tutorials › architect › build › options
"polyfills": [
  "zone.js",
  "@angular/localize/init"
]

Configure where translation files will be extracted:

Example :
// angular.json
// projects › talenra-tutorials › architect
"extract-i18n": {
  "builder": "@angular/build:extract-i18n",
  "options": {
    "outputPath": "src/locale"
  }
}

And don't forget to add the localize polyfill to your test configuration too:

Example :
// angular.json
// projects › talenra-tutorials › architect › test › options
"polyfills": [
  "zone.js",
  "zone.js/testing",
  "@angular/localize/init"
]

Mark your first text for translation

Now let's mark some text in our template so Angular knows it needs translation. Simply add the i18n attribute to any element:

Example :
<!-- src/app/welcome/welcome.component.html -->
<talenra-workspace-simple>
  <p i18n>welcome works!</p>
</talenra-workspace-simple>

Extract the messages

Run the extract command to generate your first translation file:

Example :
ng extract-i18n

This creates a file at src/locale/messages.xlf containing all the text you've marked for translation. Pretty neat!

Step 2: Adding the Talenra Localize component

The Talenra library includes a handy component for testing translations. Let's add it to see our translations in action.

Import the component

Update your welcome component to import LocalizeComponent:

Example :
// src/app/welcome/welcome.component.ts
import { Component } from '@angular/core';
import { LocalizeComponent } from '@talenra/components/tutorial';
import { WorkspaceSimpleComponent } from '@talenra/components/workspace-simple';

@Component({
  imports: [WorkspaceSimpleComponent, LocalizeComponent],
  templateUrl: './welcome.component.html',
  styleUrl: './welcome.component.scss',
})
export class WelcomeComponent {}

Add it to your template

Now add the component to your template:

Example :
<!-- src/app/welcome/welcome.component.html -->
<talenra-workspace-simple>
  <p i18n>welcome works!</p>
  <talenra-localize />
</talenra-workspace-simple>

The <talenra-localize> component will display a test message that helps you verify translations are working correctly.

Step 3: Supporting multiple languages

Now for the exciting part - let's add support for multiple languages! We'll configure German, French, and Italian translations.

Install the merge tool

First, install a helpful tool that manages translation files for you:

Example :
npm install --save-dev ng-extract-i18n-merge

This tool automatically merges new translations with existing ones, so you don't lose work when adding new text.

Configure your locales

Tell Angular about the languages you want to support. Add this to your angular.json:

Example :
// angular.json
// projects › talenra-tutorials
"i18n": {
  "sourceLocale": "en-US",
  "locales": {
    "de-CH": {
      "translation": ["src/locale/messages.de-CH.xlf"]
    },
    "fr-CH": {
      "translation": ["src/locale/messages.fr-CH.xlf"]
    },
    "it-CH": {
      "translation": ["src/locale/messages.it-CH.xlf"]
    }
  }
}

Add build configurations

For each language, add a build configuration. This tells Angular how to build your app for that specific locale:

Example :
// angular.json
// projects › talenra-tutorials › architect › build
"configurations": {
  "de": {
    "localize": ["de-CH"],
    "optimization": false,
    "extractLicenses": false,
    "sourceMap": true
  },
  "fr": {
    "localize": ["fr-CH"],
    "optimization": false,
    "extractLicenses": false,
    "sourceMap": true
  },
  "it": {
    "localize": ["it-CH"],
    "optimization": false,
    "extractLicenses": false,
    "sourceMap": true
  }
}

Configure the development server

Add serve configurations so you can easily test each language:

Example :
// angular.json
// projects › talenra-tutorials › architect › serve
"serve": {
  "configurations": {
    "de": {
      "buildTarget": "talenra-tutorials:build:de"
    },
    "fr": {
      "buildTarget": "talenra-tutorials:build:fr"
    },
    "it": {
      "buildTarget": "talenra-tutorials:build:it"
    }
  }
}

Add convenient npm scripts

Make your life easier with these handy scripts in package.json:

Example :
// package.json
"scripts": {
  "start:de": "ng serve --configuration=de",
  "start:fr": "ng serve --configuration=fr",
  "start:it": "ng serve --configuration=it",
  "extract-i18n": "ng extract-i18n && ng run talenra-tutorials:ng-extract-i18n-merge",
  "ng-extract-i18n-merge": "ng run talenra-tutorials:ng-extract-i18n-merge"
}

Now you can start your app in any language with a simple command like npm run start:de!

Configure the merge tool

Add this configuration to angular.json so the merge tool knows which files to manage:

Example :
// angular.json
// projects › talenra-tutorials › architect
"ng-extract-i18n-merge": {
  "builder": "ng-extract-i18n-merge:ng-extract-i18n-merge",
  "options": {
    "buildTarget": "talenra-tutorials:build",
    "format": "xlf2",
    "outputPath": "src/locale",
    "targetFiles": ["messages.de-CH.xlf", "messages.fr-CH.xlf", "messages.it-CH.xlf"]
  }
}

Configure Talenra translations

The Talenra components have their own translations. Configure them in your app config:

Example :
// src/app/app.config.ts
import { ApplicationConfig, provideZoneChangeDetection } from '@angular/core';
import { provideRouter } from '@angular/router';
import { provideTalenraBaseConfig } from '@talenra/components/config';
import { TalenraBaseTranslations } from '@talenra/components/locales';
import { routes } from './app.routes';

export const appConfig: ApplicationConfig = {
  providers: [
    provideZoneChangeDetection({ eventCoalescing: true }),
    provideRouter(routes),
    // Provide the Talenra base configuration with translations for de-CH
    // Set the translations here if your app does not depend on LOCALE_ID
    provideTalenraBaseConfig({
      translation: {
        ...TalenraBaseTranslations.deCH.translations,
      },
    }),
  ],
};

Using i18n in your templates

Translating text content

Simply add the i18n attribute to any element with text:

Example :
<!-- src/app/welcome/welcome.component.html -->
<p i18n>Nice to have you with us</p>

Translating attributes

Use i18n-[attribute] to translate element attributes like titles or placeholders:

Example :
<!-- src/app/welcome/welcome.component.html -->
<talenra-workspace-header title="Welcome to the Talenra Tutorial" i18n-title />

Managing your translations

Extract and update translations

After adding new text to translate, run:

Example :
npm run extract-i18n

This command does two things:

  1. Extracts all new translatable text
  2. Merges it with your existing translation files

Your translators can then edit the files in src/locale/ to add translations.

Translation file format

The translation files use the XLF2 format and look like this:

Example :
<!-- src/locale/messages.de-CH.xlf -->
<?xml version="1.0" encoding="UTF-8"?>
<xliff version="2.0" xmlns="urn:oasis:names:tc:xliff:document:2.0" srcLang="en-US" trgLang="de-CH">
  <file id="ngi18n" original="ng.template">
    <unit id="3288962299510723256">
      <segment state="translated">
        <source>Welcome to the Talenra Tutorial</source>
        <target>Welcome to the Talenra Tutorial (de)</target>
      </segment>
    </unit>
    <unit id="7474691996622814129">
      <segment state="translated">
        <source>Nice to have you with us</source>
        <target>Nice to have you with us (de)</target>
      </segment>
    </unit>
  </file>
</xliff>

Testing your translations

Run in different languages

Test your app in different languages during development:

Example :
npm start         # English (default)
npm run start:de  # German
npm run start:fr  # French
npm run start:it  # Italian

Open your browser and you'll see the app in the selected language!

Build for production

When you're ready to deploy, build for specific locales:

Example :
ng build --configuration=de  # Build German version
ng build --configuration=fr  # Build French version
ng build --configuration=it  # Build Italian version
ng build --localize          # Build all languages at once

Tips and tricks

  • Start early: It's easier to add i18n from the beginning than to retrofit it later
  • Be consistent: Always mark user-facing text with i18n, even if you only support one language initially
  • Use the merge tool: The ng-extract-i18n-merge package saves you from manually managing translation files
  • Test regularly: Use the locale-specific serve commands to catch translation issues early
  • Keep it simple: Angular generates unique IDs for each text automatically - you don't need to manage them yourself

What we learned

In this tutorial, we added complete internationalization support to our Talenra app:

  1. We set up Angular's localize package for basic i18n support
  2. We integrated the Talenra LocalizeComponent to test translations
  3. We configured support for multiple languages with convenient development and build workflows

Your app now supports multiple languages, making it accessible to users worldwide. The setup we created makes it easy to add new languages or update translations as your app grows.

Next steps

  • Try adding a new language to your app
  • Explore Angular's advanced i18n features like pluralization and date formatting
  • Consider using a translation management service for larger projects

Happy translating!

results matching ""

    No results matching ""