Angular i18n $localize Example

By Arvind Rai, January 21, 2022

This page will walk through Angular i18n $localize example.
1. The $localize tags a template literal string for localization.

myText = $localize`source message text`;

2. We can provide meaning, description and id to template literal string.

myText = $localize`:meaning|description@@id:source message text`;

3. We can evaluate expression using ${ } in template literal string.

userMsg = $localize `Welcome ${this.name}!`;

Now let us discuss using $localize in detail.

Technologies Used
Use $localize
Provide Meaning, Description and Id
Use Variable
Escaping Colon Markers (:)
Complete Example
Run Application
Reference
Download Source Code

Technologies Used

Find the technologies being used in our example.
1. Angular 13.1.0
2. @angular/localize 13.1.0
3. Node.js 12.20.0
4. NPM 8.2.0

Use $localize

To use $localize, find the component code.
app.component.ts

myText = $localize `It is winter season and we are enjoying.`;

We need to pass source message text within (` `) of $localize function.
Now use myText component property in HTML template.
app.component.html

<div> {{myText}} </div>

When we run ng extract-i18n command, the $localize text will be included for translation in messages.xlf file.
messages.xlf

<trans-unit id="1341202961024915668" datatype="html">
  <source>It is winter season and we are enjoying.</source>
  <context-group purpose="location">
	<context context-type="sourcefile">src/app/app.component.ts</context>
	<context context-type="linenumber">8</context>
  </context-group>
</trans-unit>

Provide Meaning, Description and Id

We can provide meaning, description and id to $localize source message text with following syntax.

myText = $localize`:meaning|description@@id:source message text`;

Using meaning, description and id with $localize is optional. The $localize can use meaning, description and id in following ways.

myText = $localize `source message text`;
myText = $localize `:meaning|:source message text`;
myText = $localize `:description:source message text`;
myText = $localize `:@@id:source message text`;
myText = $localize `:meaning|description@@id:source message text`;

Examples:
1. Using meaning, description and id.

myText = $localize `:Enjoy winter|Expression of joy in winter season@@winterSeason:It is winter season and we are enjoying.`;

When we run the application, we will see following output on the browser.

It is winter season and we are enjoying.

To create messages.xlf file run the following command from root directory of the project.

ng extract-i18n --output-path src/locale

Now look into the src/locale/messages.xlf file. The transaction unit uses our specified meaning, description and id.

<trans-unit id="winterSeason" datatype="html">
  <source>It is winter season and we are enjoying.</source>
  <context-group purpose="location">
	<context context-type="sourcefile">src/app/app.component.ts</context>
	<context context-type="linenumber">8</context>
  </context-group>
  <note priority="1" from="description">Expression of joy in winter season</note>
  <note priority="1" from="meaning">Enjoy winter</note>
</trans-unit>

2. Using meaning only.

myText = $localize `:Enjoy winter|:It is winter season and we are enjoying.`;

3. Using description only.

myText = $localize `:Expression of joy in winter season:It is winter season and we are enjoying.`;

4. Using id only.

myText = $localize `:@@winterSeason:It is winter season and we are enjoying.`;

5. Using description and id.

myText = $localize `:Expression of joy in winter season@@winterSeason:It is winter season and we are enjoying.`;

6. Using meaning and id.

myText = $localize `:Enjoy winter|@@winterSeason:It is winter season and we are enjoying.`;

7. Using meaning and description.

myText = $localize `:Enjoy winter|Expression of joy in winter season:It is winter season and we are enjoying.`;

Use Variable

We can use variable and expression within $localize function using ${ } .
Find the component code.

name = 'Mohit';
age = 20;
userMsg = $localize `Hello ${this.name}! Your age is ${this.age} and you can vote.`;

Find the HTML template code.

<div> {{userMsg}} </div>

Find the output in browser.

Hello Mohit! Your age is 20 and you can vote.

Find the messages.xlf file.

<trans-unit id="1081475780083634280" datatype="html">
  <source>Hello <x id="PH" equiv-text="this.name"/>! Your age is <x id="PH_1" equiv-text="this.age"/> and you can vote.</source>
  ------
</trans-unit>

We can see that for variables name and age, translation unit is using ids as PH and PH_1 respectively.

Naming placeholders
To replace variable name ids in messages.xlf file, we can use placeholders for variables and expression. Find the source message text with placeholders for variables.

userMsg = $localize `Hello ${this.name}:userName:! Your age is ${this.age}:userAge: and you can vote.`;

Find the messages.xlf file.

<trans-unit id="3436119105737254770" datatype="html">
  <source>Hello <x id="userName" equiv-text="this.name"/>! Your age is <x id="userAge" equiv-text="this.age"/> and you can vote.</source>
  ------
</trans-unit>

We can see for variables name and age that translation unit is using ids as userName and userAge in place of PH and PH_1 .

Escaping Colon Markers (:)

1. We can use colon (:) in our source message text.

myMsg = $localize `This is my source message text with colon (:)`;

2. If we need to use colon (:) at start, then we need to escape it.

myMsg = $localize `\:This is my source message text with colon (:)`;

3. In case of metadata block, no need to escape colon (:) .

myMsg = $localize `:some description::This is my source message text with colon (:)`;

4. In case of colon (:) used between two variables without placeholder, this colon must be escaped.

myMsg  = $localize `Student ${this.stdId}\:${this.stdName}`;

5. If we are using placeholder for variables then colon (:) used between two variables is not required to escape.

myMsg = $localize `Student ${this.stdId}:studentId::${this.stdName}`;

Complete Example

app.component.html

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

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html'
})
export class AppComponent {
  myText = $localize `:Enjoy winter|Expression of joy in winter season@@winterSeason:It is winter season and we are enjoying.`;
 
  name = 'Mohit';
  age = 20;
  userMsg1 = $localize `Hello ${this.name}:userName:! Your age is ${this.age}:userAge: and you can vote.`;
  userMsg2 = $localize `Can you vote: ${this.age >= 18 ? 'Yes': 'No'}`;

  myMsg1 = $localize `:some description::This is my source message text with colon (:)`;

  stdId = 10;
  stdName = "Krishna";
  myMsg2 = $localize `Student ${this.stdId}:studentId::${this.stdName}`;
}

app.component.html

<div> {{myText}} </div>

<div> {{userMsg1}} </div>

<div> {{userMsg2}} </div>

<div> {{myMsg1}} </div>

<div> {{myMsg2}} </div>

app.module.ts

import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { AppComponent } from './app.component';

@NgModule({
  imports: [BrowserModule],
  declarations: [AppComponent],
  bootstrap: [AppComponent]
})
export class AppModule { }

Create Translation Files for Other Languages

Run ng extract-i18n command from root directory of the project.

ng extract-i18n --output-path src/locale

A file named as messages.xlf will be created in src/locale directory. For other languages, copy messages.xlf file in same location and rename it as below.

message.{locale}.xlf

Suppose for French locale (fr), file will be created as following.

messages.fr.xlf

In messages.fr.xlf, copy the text of <source> tag and create as <target> tag and translate text of this tag in French language.

<trans-unit id="winterSeason" datatype="html">
  <source>It is winter season and we are enjoying.</source>
  <target>C'est la saison d'hiver et nous en profitons.</target>
  ------ 
</trans-unit>

Run Application

To run the application, find the steps.
1. Download source code using download link given below on this page.
2. Use downloaded src in your Angular CLI application. To install Angular CLI, find the link.
3. Add @angular/localize library.
4. Run ng serve using command prompt.
5. Access the URL http://localhost:4200
Find the print screen of the output.