I18n Service

Overview

I18n service provides APIs which are supposed to be used in JavaScript module to get supported languages & regions, and format locale-sensitive data.

import { I18nService } from "@singleton-i18n/angular-client";

Supported Language & Region & City APIs

getSupportedLanguages

Get the supported languages which are available in singleton service for the specific product.

getSupportedLanguages(): Promise<languagesList>;

getSupportedRegions

Get the supported regions from singleton service, the supported region list should be unified in all products.

getSupportedRegions(languageTag: string): Promise<regionsList>;

getCities

Get the cities list of the specified region and display the cities’ names in a specific language.

Note that the current city list is only available in English, and there is no translation in other languages.

getCities(regionCode: string, languageTag: string): Promise<citiesList>;

Example Code

this.i18nService.getSupportedLanguages().then( languages => {
    this.languages = languages;
    // eg: [ { displayName: "English", languageTag: "en" },
    //       { displayName: "français", languageTag: "fr" },
    //       { displayName: "简体中文", languageTag: "zh-Hans" }
    //      ]
});
this.i18nService.getSupportedRegions('fr').then( regions => {
        this.regions = regions;
        // eg: assuming that languageTag is fr
        // [ [ 'FR': 'France'],
        //   [ 'GE': 'Géorgie' ],
        //   [ 'CN': 'Chine' ] ]
});

Data Formatting APIs

Data formatting APIs are locale-sensitive; their return depends on the locale. So when using these formatting APIs in the JavaScript module, locale pattern data is required, which can be loaded synchronously or asynchronously depending on the way of i18n data initialization. If the i18n data was loaded in synchronous, these APIs could be used to format data directly. Otherwise, the stream API is the right way to get locale through the subscription and consume these APIs in an observer. For more details, please refer to the session ‘Data initialization’ and sample code below.

Format date

Formats a date according to the given options and locale.

formatDate(value: any, pattern: string, locale?: string, timezone?: string): string;

Format number

Formats a number according to the given options and locale.

formatNumber(value: any, locale?: string, formatOptions?: NumberFormatOptions): string;

Format percent

Formats a number into percentage string according to the given options and locale.

formatPercent(value: any, locale?: string, formatOptions?: NumberFormatOptions): string;

Format currency

Formats a number into currency string according to the given options and locale.

formatCurrency(value: any, currencyCode?: string, locale?: string, formatOptions?: NumberFormatOptions): string;

formatOptions

Format relative time

Formats simple relative dates. Details

formatRelativeTime( from: Date, to: Date, locale?: string, options?: Object ): string

Get localized Pattern

Get a localized version of the predefined patterns. If the input pattern is not the predefined pattern, return the input pattern directly. If the locale data is missing for the current locale, fallback to source locale and return source pattern instead.

getLocalizedPattern(pattern: string, locale?: string): string;

Stream API

Since the live update is relying on the observable object to notice the available current locale, formatting data based on the i18n service should be performed in the subscription of the ‘stream’ to ensure the pattern data is ready for this locale.

public stream(): Observable<string | any>;

Example Code

import { I18nService } from '@singleton-i18n/angular-client';
import { Component, OnInit, OnDestroy } from '@angular/core';

@Component({
    selector: 'test',
    templateUrl: './test.component.html'
})
export class TestComponent implements OnInit, OnDestroy {
    subscription: any;
    time: string;
    currency: string;
    constructor(private i18nService: I18nService) {}

    ngOnInit() {
        this.subscription = this.i18nService.stream.subscribe((locale: string) => {
            this.time = this.i18nService.formatDate(new Date(), 'short', locale );
            this.currency = this.i18nService.formatCurrency(10, 'CNY', locale);

            // By default, the locale is the current locale, eg: 'zh-Hans'
            // output: y/M/d ah:mm
            const localizedPattern = this.i18nService.getLocalizedPattern('short');
            
            // Explicitly set locale parameter, eg: 'en-US'
            // output: M/d/yy, h:mm a
            const EnPattern = this.i18nService.getLocalizedPattern('short', 'en-US');

            // format options usage
            let formatOptions = { notation: 'compact', compactDisplay: 'long' };
            const compactNumber = this.i18nService.formatNumber( 1000000, locale, formatOptions);
            // output: 1 million

            formatOptions = { maxFractionDigits: 6 };
            const roundedNumber = this.i18nService.formatNumber( 1.23456789, locale, formatOptions);
            // output: 1.234568
        });
    }
    ngOnDestroy() {
        this.subscription.unsubscribe();
        this.subscription = undefined;
    }
}