Introducing Localization Support for Transloco: The Internalization Library for Angular

AngularInDepth is moving away from Medium. More recent articles are hosted on the new platform inDepth.dev. Thanks for being part of indepth movement!

Transloco is a new internalization (i18n) library for Angular, it comes with many features which will help us to easily create multicultural applications! in this post, I will introduce the official’s Transloco’s localization plugin.

About a month ago we have introduced Transloco’s a translation (i18n) library for Angular, since then we have provided many features and plugins to support this library. In this piece, I will introduce one of Transloco’s most useful plugins which bring a full localization (L10N) support.

Localization refers to the adaptation of a product, application or document content to meet the language, cultural and other requirements of a specific target market (a locale).

Installation & Setup

Let’s go over the plugin’s features, but first, install the plugin assuming Transloco has already been added:

npm i @ngneat/transloco-locale

Now, Inject TranslocoLocaleModule along with TranslocoModule into AppModule:

Localization Pipes

The library provides a set of localization support pipes. Each of the pipes has built on top of the Javascript’s API and provides the native’s browser support for localization.

Let’s go over each of those pipes.

📅 Date Pipe

Transform a date into the locale’s date format.

The date expression could be:

• A Javascript Date object.
• A number (milliseconds since UTC epoch)
• An ISO formatted string.

💲 Currency Pipe

Transform a given number into the locale’s currency format.

The library comes out of the box with locale currency mapping, so once the locale changes the currency will automatically display the matching currency. The currency mapping could be customized if needed in the config or provided by LOCALE_CURRENCY_MAPPING token.

🔢 Decimal & Percent pipes

Transform a given number into current locale’s number format.

Setting the Locale

The library provides three different ways to set the locale.

• Through the translation file names:

Using locale format for the translation files will automatically set the locale:

├─ i18n/
   ├─ en-US.json
   ├─ en-GB.json
   ├─ es-ES.json

• Language Locale Mapping:

Users who don’t have more than one locale per language (e.g “en” for USA and “es” for Spain) could simply provide a language-locale mapping object using the config’s langToLocaleMapping property:

• Manually Setting Locale:

The third option in manually call the setLocale method provided by the LoaleService:

Configuration Options

The locales library could be customized and configured if need from the static method init of TranslocoLocaleModule.

Let’s explain each one of the config options:

• localeConfig?: Declare the default configuration of the locale's formatting. A general configuration could be set using the global property, for a configuration by locale use localeBased property (default value determined by the native Javascript's API).
• defaultLocale?: The default locale formatted in BCP 47 (default value: en-US),
• langToLocaleMapping?: A key-value object that maps Transloco language to its Locale (default value: {}).
• localeToCurrencyMapping?: A key-value object that maps the Locale to its the currency (formatted in ISO 4217) (the library provide a default value with all of the existing mappings).

Locale Format Options

There are two types of formatting options, one for date and one for number.

The formatted options could be declared in three levels

1. In the module’s configuration (as mentioned above):

2. It could be set in the component’s providers using LOCALE_CONFIG token:

3. We can pass it to each pipe in the HTML template:

Note the format option of the global, locale’s format and the ones being passed in the template will be merged. While the template is the stronger one then the locale and the global.

Number Format Options

• useGrouping- Whether to use grouping separators, such as “thousands” separators or thousand/lakh/crore separators. Possible values are true and false; the (default is true).
• minimumIntegerDigits- The minimum number of integer digits to use. Possible values are from 1 to 21 (default is 1).
• minimumFractionDigits- The minimum number of fraction digits to use. Possible values are from 0 to 20 (default is 0).
• maximumFractionDigits- The maximum number of fraction digits to use. Possible values are from 0 to 20 (default is 3).
• minimumSignificantDigits- The minimum number of significant digits to use. Possible values are from 1 to 21 (default is 1).
• maximumSignificantDigits- The maximum number of significant digits to use. Possible values are from 1 to 21 (default is 21).

Date Format Options

• dateStyle - The date formatting style.
• timeStyle - The time formatting style.
• timeZone - The time zone to use. The only value implementations must recognize is "UTC"; the default is the runtime's default time zone. Implementations may also recognize the time zone names of the IANA time zone database, such as "Asia/Shanghai", "Asia/Kolkata", "America/New_York".

Last But Not Least

Please visit our repository on GitHub, we would love to get some more contribution, or you can simply show us your support by starring the library.

ngneat/transloco

Thanks for reading!

You’re welcome to follow me on Twitter for more updates 🙌