Angular Internationalization: Helping Apps Cross Borders

There are 6,500¹ languages spoken today in a world of roughly 7.7 billion² people. Globalization, or g11n, has given people and businesses the ability to reach across not only oceans and great distances but also borders, so it's easy to see why having the ability to cross language and cultural divides would be extremely important when it comes to customer outreach.

What's more, Harvard Business Review published findings that customers were far more likely to make a purchase from websites that were in their native language. Cross-border ecommerce is slated to reach almost $5 trillion by 2020³, so it behooves all companies thinking or operating in a digital space to consider what would be most appealing to their audience.

But you don’t have to rebuild your app 6,500 times to cover all those languages and all those people. By using Angular internationalization, or i18n, you can develop a foundation that will be easy to translate multiple times as well as update regularly.

What is g11n?

Let's take a minute to talk about globalization and its siblings, internationalization and localization. Globalization is the process by which different cultures, beliefs, and ways of life have become interdependent because of technology. The world is large, and people throughout all of it can reach each other across vast distances in insanely short amounts of time.

Because of this, it's important to acknowledge the differences from one culture to the next. Businesses that want to operate in a cross-culture space need to know their audience and how to sell to them. You won't make a profit if you don't know what your audience needs or wants. 

This is where internationalization and localization come in. Internationalization, or i18n, gets used interchangeably with globalization quite often, but the two terms actually differ.

• Internationalization is the process by which a product is made to be localized, either to a specific country, region, or town. It removes roadblocks that might slow the localization process and ensures that the best resources are being used for the project.
• Localization, or l10n, is the process by which software, documentation, or another product is made ready for a specific area and/or audience. This takes into account not only language and user interface aspects, but time and other numerical formatting, keyboard usage, and more. All of these things can go into making an attractive and desirable product—be it physical, web, or mobile—that will be used by customers across the globe.

Why the numbers?

Globalization, internationalization, and localization are often represented in software and web development by numeronyms, or number-based words. Though their presentation can vary, these particular numeronyms are spelled out by replacing the letters between the first and last with a number. For example, there are 18 letters between the i and n in internationalization, as shown below.

i+ n₁t₂e₃r₄n₅a₆t₇i₈o₉n₁₀a₁₁l₁₂i₁₃z₁₄a₁₅t₁₆i₁₇o₁₈ +n

The first numeronym is believed to be s12n, which was an email account assigned to Digital Equipment Corporation (DEC) employee Jan Scherpenhuizen because his last name contained too many characters for an account name. Because of this numeronym, colleagues who found Jan’s name difficult to pronounce instead sometimes referred to him as s12n.⁴

Now let’s talk about how to implement localization and internationalization in Angular.

What is Angular?

Angular is an open-source web framework based in TypeScript, and offers an out-of-the-box option to internationalize and thus easily localize an application in real time. By using the Angular command-language interface (CLI) to generate most of the boilerplate necessary to create files for translators, you can publish your app in multiple languages via versioning. 

The built-in internationalization functionality became available with Angular 8, released in May 2019. This update brought the internationalization support in-house and is suitable for both large and small applications. Angular will build separate versions of an app, each in a different language as instructed. Because of this, there is no content-switching depending on the locale like other internationalization libraries; each version of your app is completely independent.

This simplifies each version of the app and keeps the file size small. Each version contains only the translations specific for the region or audience that they are for.

How does Angular Internationalization work?

Mark text for translation
We can simply add the i18n attribute to HTML element around content that should be translated. 

<h1 i18n>Welcome!</h1>

It's best to provide as much context as possible for the translator; we can add additional context and even a description by giving the attribute a value.

<h1 i18n="greeting|this is the first thing users see when they come to the site">Welcome!</h1>

Notice that the context and the greeting are separated by a pipe symbol (|); in this example, the context comes before the description. This provides the differentiation that Angular needs in order to feed that information into the message.xlf file, where the translation will need to be placed. 

Angular will generate IDs for each item tagged, but these IDs will change whenever the translated text changes. We can make the IDs static by adding two address signs (@) within the value assigned to the attribute. 

<h1 i18n=”greeting|this is the first thing users see when they come to the site@@greeting”>Welcome!</h1>

This ID can be added with or without the context and/or description. The ID for each element must be unique.

Generate a translation file

Once all the text that needs to be translated is tagged appropriately (this tagging can also be done for attributes, plural expressions, and alternative text), the translation file will need to be generated. We can do this by running ng xi18n in the terminal. 

This causes the Angular CLI to generate one message.xlf file in the src folder. Make as many copies depending on how many languages you wish to have your app support. 

Each message.xlf file will have to be tailored for one language. For easier organization, group all the message.xlf files in one 'locales' folder. Add a language extension to each folder per the language that file will support. For example:

message.de.xlf

Add translations

Now we’ll have to add areas for the translations within the translation file.

<trans-unit id="greeting" datatype="html">
  <source>Welcome!</source>
  <context-group purpose="location">
    <context context-type="sourcefile">
      app/app.component.html
    </context>
    <context context-type="linenumber">
      3
    </context>
  </context-group>
  <note priority="1" from="description">
    greeting
  </note>
  <note priority="1" from="meaning">
    this is the first thing users see when they come to the site
  </note>
</trans-unit>

The translation file will have already pulled all the text tagged for translations, as well as the context and descriptions provided. Underneath the source tag, we will need to add a target for the translation. The target goes under the <source></source> HTML elements.

<trans-unit id="greeting" datatype="html">
  <source>Welcome!</source>
  <target>Willkommen!</target>
  <context-group purpose="location">
    <context context-type="sourcefile">
      app/app.component.html
    </context>
    <context context-type="linenumber">
      3
    </context>
  </context-group>
  <note priority="1" from="context">
    greeting
  </note>
  <note priority="1" from="description">
    this is the first thing users see when they come to the site
  </note>
</trans-unit>

Edit the JSON file

Lastly, we modify the angular.json file to instruct Angular on how to build the various language versions of the application.

We will add a separate configuration for each language in the build section of the .json file.

"build": {
  "builder": "@angular-devkit/build-angular:browser",
  "options": {
    "outputPath": "dist/i18n/default",
    "index": "src/index.html",
    "main": "src/main.ts",
    "polyfills": "src/polyfills.ts",
    "tsConfig": "src/tsconfig.app.json",
    "assets": ["src/favicon.ico", "src/assets"],
    "styles": ["src/styles.css"],
    "scripts": []
  },
  "configurations": {
    "de": {
      "aot": true,
      "outputPath": "dist/i18n/de/",
      "i18nFile": "src/messages.de.xlf",
      "i18nFormat": "xlf",
      "i18nLocale": "de"
    },
    ...
  },
  ...
}

To ensure server commands function properly, modify the configuration of the server section as well:

"serve": {
  "builder": "@angular-devkit/build-angular:dev-server",
  "options": {
    "browserTarget": "i18n:build"
  },
  "configurations": {
    "de": {
      "browserTarget": "i18n:build:de"
    },
    "production": {
      "browserTarget": "i18n:build:production"
    }
  }
},

Angular i18n pipes

Angular is set up by default for US-en (U.S. english) data, and new locale data must be imported manually. This can be done in the app.module.ts file, with the following script:

import { registerLocaleData } from '@angular/common'
import localeDe from '@angular/common/locales/de'

registerLocaleData(localeDe, 'de')

Now the Angular pipes DatePipe, CurrencyPipe, DecimalPipe, and PercentPipe will use locale data based on the LOCALE_ID. 

Conclusion

This is a summarized view of using internationalization with Angular; refer to angular.io for more in-depth information. 

There are many reasons to make your application available in many languages; whether it’s reaching new people, finding new information, or bringing your business to new shores, making your app available and comprehensible in someone’s native tongue has many advantages. 

Angular is a great framework that allows the easy translation of your app into as many languages as your fingers can type.