Best Practices for Angular Internationalization

When building an application, it is not a question of if it might be used by a global audience, but a matter of when it will be offered to global markets. This is why it is important to build an application with internationalization (i18n) in mind.

Planning to support multiple languages, not only includes the GUI (graphical user interface), but also other aspects like formatting dates and numbers, applying different currencies, and supporting language-specific fonts (including bi-directional). Depending on the framework or content management system (CMS) you are going to use to build your application, you might have different alternatives to internationalize it. In this blog, we will cover the best practices for the internationalization process of an Angular app.

Overview

To internationalize your Angular app to support multiple languages; follow these steps:

1- Install needed dependencies.

2- Prepare project for translation.

3- Extract text to be sent to translator.

4 – Use .xlf file after translation and set project to localization.

Let’s start our journey.

Install Dependencies

Install a localized package to a project by using the Angular CLI and (ng add @angular/localize) command, then we will add the @angular/localize package, afterward, the package.json file will be updated.

Prepare Components for Translation

Prepare the Value of an Element

To prepare the fixed text in the template, we will use the i18n attribute to mark all static text to be translated;

We must place the i18n attribute on every element tag we want to translate.

Example:

<h1 i18n> Welcome in GPI! </h1>

We added the i18n attribute in the element to mark the h1 element tag as a translatable element.

When Angular executes the extract process, it will understand that the h1 tag is to be translated.

Prepare the Attribute of an Element

To mark the title attribute for translation, you will add i18n-title.

Example:

<img [src]=”logo” i18n-title title=”GPI logo” alt=” GPI logo”/>

In the previous example we used the following format to mark the “title” attribute for translation:

i18n-{attribute_name}=”{i18n_metadata}” {attribute_name}=”{attribute_value}”

Preparing Text in Component Code

As we use a variable in the ts class, we need to also mark this text for translation, to do that we use backtick (`) characters to surround the text and metadata.

For text only:

$localize `string_to_translate`;

To add i18n metadata we will surround it by (:) as shown here:

$localize `:{i18n_metadata}:string_to_translate`

When we need to include interpolated text, will use this format:

$localize `string_to_translate ${variable_name}:placeholder_name:`;

Preparing Plural Expressions

The difficulty with plural expressions is that different languages have different pluralization rules. To mark plural expressions, we use the plural clause:

{ component_property, plural, pluralization_categories },

Notice that we will put plural in the (pluralization_categories) part:

Example : =0 { } zero { }

Notice this example:

( updated x minutes ago )

<span i18n>Updated X minutes ago </span>

We can mark it as:

<span i18n>Updated {minutes, plural, =0 {just now} =1 {one minute ago} other

{{{minutes}} minutes ago}}</span>

For more detailed information about the pluralization category, check out  Angular Documentation.

Preparing Alternate Expressions

We can use the (select) clause to mark choices for alternate text:

Format: { component_property, select, selection_categories }

We enter the text (English) surrounded by the curly brace ({}) characters after the selection category:

<span i18n>The main course is {main_course, select, meat { meat } fish { fish } other {other}}</span>

Export Content for Translation

Now that we have finished preparing the components, we will extract all marked text by using Angular CLI.

By using ”extract-i18n” command, Angular will create a source language file named “messages.xlf ” and it will be created in the root directory.

To create the file in specific directory we can use: “ng extract-i18n –output-path src/locale”

Then, create a copy of the file for each language; we rename each language file depending on the locale needed following this format:

file_name.{locale}.xlf  like   messages.fr.xlf

it is preferred to create a directory for translation files like: src/locale inside .xlf file, we will find the <trans-unit> tag for every marked text. Inside this tag there is tag <source>, this tag contains marked source text.

The translator can use the xlf editor App or manually by adding a new tag named <target> and write the value inside.

Simple example:

<trans-unit id=”introduction” datatype=”html”>

<source>Hello</source>

<target>Bonjour</target

</trans-unit>

Import Translated Content

Now we need to prepare the app for localization by adding specific properties in angulal.json file.

As in next snippet code, we will add the new property “i18n” and we will specify the source locale that is the locale used in source code.

We will add other property “locales” and the specific locales that the App can support.

Once we finish, we need to merge the translations into our application.

Go to the angular.json file and add new settings

“i18n”: {

“sourceLocale”: “en-US”,

“locales”: {

“fr-CA”:”src/locale/messages.fr.xlf”,

//.. } }

Moreover, we will add another property in this path: architect > build > options

Add “localize”: true

Now the app is ready to build; by using Angular CLI, we will write this command “ng build –localize”.

For more details and in-depth understanding please check Angular Documentation.

Format Data Based on Locale

We will use the pipes that Angular provides for this purpose, notice the data transformation pipes use the LOCALE_ID token to format data based on rules of each locale.

Currencies Formatting

Using CurrencyPipe transforms a number into a currency string.

currencyObj: number = 0.359;

{{currencyObj | currency}}  // output ‘$0.36’

Numbers Formatting

Decimal Pipe transforms a number into a decimal number string.

pi: number = 3.14159265359;

Without specified formatting:

{{pi | number}}    output: ‘3.142’

With specified formatting:

{{pi | number:’4.1-5′}} output: ‘0,003.14159’

With specified formatting and locale:

{{pi | number:’4.1-5′:’fr’}}  output: ‘0 003,14159’

Numbers Dates

Use DatePipe to format a date value.

dateObj: number = Date.now();

{{ dateObj | date }} // output is ‘Jun 15, 2022’

or format like

{{ dateObj | date:’medium’ }} // output is ‘Jun 15, 2022, 9:43:11 PM’

Conclusion

The localization of an application is an important aspect to consider when starting the design process. By developing the application to be language-independent and able to handle the intricacies of multiple languages from inception, you will save time and money.

With the continued growth of the global marketplace, most websites nowadays are prepared for localization. Angular makes this process easier by providing simple localization techniques, with simple steps to follow, you can get a fully localized application. Designing an application with localization in mind is the best practice to avoid a lot of complexity when localization is introduced at later stages of the project lifecycle.