JavaScript Client Introduction

Overview

The Singleton JSClient(@singleton-i18n/js-core-sdk) is a Singleton Service-based JavaScript library used for l10n and i18n. It almost supports all JavaScript frameworks, and it can run in browsers, as well as NodeJS environments. With the Singleton JavaScript Client, it makes l10n and i18n implementation more easier in most projects. Now, let’s look at what it is and how it works.

Features

• JSClient Initilization
• Language and region management
• Load data API
• Provide string localization API
• Provide datetime,number,currency,percentage formatting API
• Source management via CLI scripts
• Runtime / Offline Mode

JSClient Initilization

How to initilize Singleton JSClient in frontend framework? it requires to figure out the root loading point where JSClient is able to comminicate with Singele Service fetching translations and patterns. E.g. index.js in React framework is the root loading point, during the initilizing process, it needs to provice basic product information (E.g. ProductID, Component, Version) and interacts with Singleton Service runtime, it will load corresponding translations and patterns by language and region when switching locale. Singleton JSClient offers API i18nClient.init(Configuration) as below snippet which is used to initilize JSClient when App startup. At the same time, Singleton JSClient also provides l10nService and i18nService APIs so that it is able to use their exposed methods to translate strings and format the data regarding datetime, number, percentage and currency.

Configuration

import { i18nClient as jsClient, getBrowserCultureLang, PatternCategories} from '@singleton-i18n/js-core-sdk';

const currentLanguage  = getBrowserCultureLang();

const initI18nClient = () => {

    const i18nClient = jsClient.init({
        productID: 'ProductName',
        version: '1.0.0',
        component: 'ReactUI',
        host: 'http://Single-Service:8091',
        language: currentLanguage,
        i18nScope: [PatternCategories.DATE],
        sourceBundle : {
                'app.title': 'Hello, world!',
                'plural.apples': '{0, one{ # apple}  other{ # apples} }'
            },
        timeout: 5000
    });

    return i18nClient;
}

export const i18nClient = initI18nClient();

Language and region management

Singleton JSClient provides two approaches to resolve Language and Region, the first one is directly detecting current user language preference in the browser settings, The other one is strongly recommended to be adopted in both SaaS and on-premise deployment mode through the language and region list provided by Singleton JSClient API fetching from Singleton service.

Resolve Browser Locale

Resolve browser locale through the API getBrowserCultureLang as below snippet.

import { getBrowserCultureLang } from '@singleton-i18n/js-core-sdk';

const currentLanguage  = getBrowserCultureLang();

User Preference Of Language List

Singleton JSClient offers the API getSupportedLanguages(): Promise<Object[] | null> through i18nService to fetch the supported languages of App from Singleton service runtime.

import { i18nClient } from '@singleton-i18n/js-core-sdk';

i18nClient.i18nService.getSupportedLanguages()
    .then(
        ...
    );

Load Data API

Singleton JSClient offers the load data API through coreService in order to load latest translations and patterns when switching locale(language and region). there are certain situations as below.

• When App startup, it needs to load translations and patterns according to user perference language and region.
• When user switching language list, it should load corresponding translations and patterns

/**
* Load resource prior to perform callback.
* @param callback
*/
async loadI18nData(callback?: () => void): Promise<any>


// Example in React index.jsx
import { i18nClient } from '@singleton-i18n/js-core-sdk';

const render = async () => {
    try {
        await i18nClient.coreService.loadI18nData();
    } catch (e) {
        console.error(e);
    } finally {
        ReactDOM.render();
    }
};

render();

Localization API

Singleton JSClient also offers localization API getMessage(key: string, args?: any[] | {}): string through l10nService which is mainly used to translate strings along with varibles involved as below snippet.

{
    'product.login.success': '{0} has logged in successfully!',
}

import { i18nClient } from '@singleton-i18n/js-core-sdk';

const username = 'Tom';

i18nClient.l10nService.getMessage('product.login.success', [username]);

Internationalization API

Singleton JSClient also provides I18n APIs through i18nService to format the data regarding Datetime, Number, Percentage and Currency.

Datetime Format API

public formatDate(value: any, pattern: string = 'mediumDate', timezone?: string): any

Pre-defined format options

Number Format API

public formatNumber(value: any, locale?: string): string

Percentage Format API

public formatPercent(value: any): string

Currency Format API

public formatCurrency(value: any, currencyCode?: string): any 

Source Management via CLI Scripts

Singleton JSClient similarly exposes two CLI scripts which are seperately used to upload source bundle onto Singleton service for translations and to download translations & patterns from Singleton service by locale.

Upload Source Bundle

This script typically collects the collection named ENGLISH from the files named .l10n.js or .l10n.ts, and then send them to the Singleton service.

• Command line arguments description

• Create source bundle

export const ENGLISH = {
    "network-error": 'Network instability.'',
    "data-error": 'Data error.',
    ...
}

• Configure script in package.json

collect-source-bundle
            --source-dir `pwd`/src/app
            --host https://singleton.service.com:8090
            --product Testing
            --component ReactUI
            --version 1.0
    

{
    ...
    scripts: {   
        "upload-source-bundle": "collect-source-bundle 
                                --source-dir `pwd`/src/app 
                                --host <Singleton Service host>
                                --product <product>
                                --component <component>
                                --version <product version>
    }
    ...
}
    

• Run the script

npm run upload-source-bundle

Download Translations & Patterns

Download translations and Patterns by language and region when Offline Mode.

• Command line arguments description

load-locale-data
  --directory `pwd`/src/app/assets
  --host https://singleton.service.com:8090
  --product Testing
  --component default
  --version 1.0
  --languages zh-cn,en-US

• Configure script in package.json

{
    ...
    scripts: {   
        "download-locale-data": "load-locale-data 
                            --directory `pwd`/src/app/assets
                            --host <Singleton Service host>
                            --product <product>
                            --component <component>
                            --version <product version>
    }
    ...
}

Run the script

npm run download-locale-data

Runtime / Offline Mode

Runtime Mode

Runtime mode means JSClient has to communicate with Singleton Service runtime fetching translations and patterns, it requires to deploy Singleon Service on backend.

Offline Mode

Offline mode doesn’t require to deploy Singleton Service on backend, it will be enabled no longer communicating with Singleton Service when setting ‘i18nAssets’ parameter at [Configuration], but it needs to depend on CLI script ‘download-locale-data’ exposed by Singleton JSClient to asynchronously fetch translations and patterns to local specified directory, then Singleton JSClient is able to load translations and patterns from local.