Documentation

Initial Setup

Start by adding Angular's localization package to your project:

ng add @angular/localize

This command will make the following changes:

  • Add the @angular/localize package to your dependencies
  • Add "@angular/localize/init" to the polyfills array in angular.json
  • Add the following reference to your main.ts:
/// <reference types="@angular/localize" />

It will also add the extract-i18n configuration to angular.json:

"extract-i18n": {
  "builder": "ng-extract-i18n-merge:ng-extract-i18n-merge",
  "options": {
    "buildTarget": "your-app:build",
    "format": "xlf",
    "outputPath": "src/locale",
    "includeContext": true,
    "resetTranslationState": true,
    "targetFiles": [
      "messages.fr.xlf",
      "messages.vi.xlf"
    ]
  }
}

Note: We'll modify the outputPath later in the configuration to match our workflow.

Angular i18n CLI Tool

To simplify the management of Angular i18n configuration, you can use our CLI tool:

npm install --save-dev @softwarity/angular-i18n-cli

This tool provides several features to streamline your i18n workflow:

  • Easy initialization of i18n configuration in your Angular project
  • Simple addition and removal of locales
  • Automatic configuration of build settings for each locale
  • Proper setup of XLIFF file formats

Angular i18n CLI

CLI tool to simplify Angular i18n configuration and locale management.

Install Translation Tool

For managing translation files, we'll use ng-extract-i18n-merge which simplifies the process of extracting and merging translations:

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

This tool offers several advantages:

  • Automatically extracts translatable strings from your application
  • Merges new translations with existing ones in a single step
  • Preserves existing translations during updates
  • Supports multiple target languages

Configuration Files

package.json

"scripts": {
  ...
  "extract-i18n": "ng extract-i18n",
  "build": "ng build --localize"
  ...
}

angular.json

Update the i18n configuration in angular.json:

"i18n": {
  "sourceLocale": "en",
  "locales": {
    "fr": {
      "translation": "src/locale/messages.fr.xlf"
    },
    "vi": {
      "translation": "src/locale/messages.vi.xlf"
    }
  }
},

Then replace the standard extract-i18n configuration with ng-extract-i18n-merge:

"extract-i18n": {
  "builder": "ng-extract-i18n-merge:ng-extract-i18n-merge",
  "options": {
    "buildTarget": "your-app:build",
    "format": "xlf",
    "outputPath": "src/locale",
    "includeContext": true,
    "resetTranslationState": true,
    "targetFiles": [
      "messages.fr.xlf",
      "messages.vi.xlf"
    ]
  }
}

Important Configuration Options:

  • buildTarget: Your application's build target name
  • outputPath: Directory where translation files will be stored
  • includeContext: Includes source file information in the XLIFF files
  • resetTranslationState: Marks all translations as needing review on changes
  • targetFiles: List of translation files to generate/update

Build configurations

Add configurations for each language in the build section:

"architect": {
  "build": {
    "configurations": {
      "fr": {
        "localize": ["fr"]
      },
      "vi": {
        "localize": ["vi"]
      }
    }
  }
}

Prepare Components for Translation

To make your components ready for translation, you need to mark the text that should be translated. Angular provides two ways to do this:

Angular Documentation: Marking Text for Translation

Learn more about how to prepare your application for translation.

Template Translation

Use the i18n attribute in your templates to mark text for translation:

<tag attribute="This is a sample attribute text that needs translation." 
  i18n-attribute="@@ATTRIBUTE_TEXT"
  i18n="@@TAG_TEXT">This is a sample text that needs translation.</tag>
// EXAMPLE
<button title="Title button" i18n-title="@@TITLE_BUTTON"i18n="@@LABEL_BUTTON">label button</button>

The @@prefix defines a custom ID for the translation. Using SNAKE_CASE is recommended for consistency.

Component Translation

For text in your component code, use the $localize template tag:

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

@Component({
  selector: 'app-example',
  template: '...'
})
export class ExampleComponent {
  title = $localize`:@@PAGE_TITLE:Welcome to our application`;
  errorMessage = $localize`:@@ERROR_MESSAGE:An error occurred while processing your request`;
}

Building and Serving

Build with Translations

Build your application with all translations:

npm run build

Or build for a specific language (using French as example):

ng build --configuration=fr

Development Server

Serve your application with translations during development:

ng serve --configuration=fr

⚠️ Important Note

After adding new translatable content or modifying existing translations:

  1. ng extract-i18n - to extract and update all translation files in one step

This simplified workflow ensures your translation files are always up-to-date with source content, making the internationalization process more efficient and error-free.