maxaggedon / icu-loader

A package to load full ICU data in Node.js environment with JavaScript Intl API

ICU Loader ·

A package to load full ICU data in Node.js environment with JavaScript Intl API

But Why?

To use JavaScript Intl API, Node.js needs to run with --icu-data-dir option that provides us to have Intl API in our Node environment but because of the structure of the Node.js we're not able to use this option directly as requiring it in our scripts. through child_process module, this feature will be possible.

Example

import { IDate } from 'icu-loader'

let date = new IDate(new Date(2016, 9, 16))
date.toLocaleString('en-US', { year: 'numeric', month: 'long', day: 'numeric' })
  .then(result => console.log(result)) // October 16, 2016

Table of Contents

• Requirements
• Usage
• Contributing
• License

Requirements

ICU Loader requires the following to run:

• Node.js 6.2.0+
• full-icu package (it'll be install as dependencies)

Usage

ICU Loader is easiest to use when installing with npm:

npm install icu-loader --save

Then you can load the module into your codes by the ES module or CommonJS:

// ES module
import {IDate, IString, INumber} from 'icu-loader';

// Or import specific class
import IString from 'icu-loader';

// CommonJS
let date = require('icu-loader').IDate;
let string = require('icu-loader').IString;
let number = require('icu-loader').INumber;

According to JavaScript Intl API, the module has the following objects (IDate, IString, INumber) and various methods.

The star (*) sign means the argument is optional.

IDate

Syntax

new IDate()
new IDate(dateObj)

Argument Name	Type	Description
dateObj	Date, String	the reference date object

Methods

All arguments of the methods of Date object are same, the following methods:

• toLocaleString(dateObj, locale, [options])
• toLocaleDateString(dateObj, locale, [options])
• toLocaleTimeString(dateObj, locale, [options])

Arguments

Argument Name	Type	Description
locale	String	the locale string that date will be displayed in
options *	Object	documents

Example

import IDate from 'icu-loader'

let date = new IDate(new Date(2016, 9, 16))

// US English uses month-day-year order and 12-hour time with AM/PM
date.toLocaleString('en-US')
  .then(result => console.log(result)); // "9/16/2016, 0:00:00 PM"

// request a weekday along with a long date
var options = { weekday: 'long', year: 'numeric', month: 'long', day: 'numeric' };
date.toLocaleString('de-DE', options)
  .then(result => cosnole.log(result)); // "Sonntag, 16. Oktober 2016"

// Arabic in most Arabic speaking countries uses real Arabic digits
date.toLocaleDateString('ar-EG')
  .then(result => cosnole.log(result)); // "۲۰۱۶/۹/۱۶"

// Korean uses year-month-day order and 12-hour time with AM/PM
date.toLocaleTimeString(new Date(2016, 9, 16, 14, 15, 05), 'ko-KR')
  .then(result => cosnole.log(result)); // "오후 2:15:05"

// sometimes even the US needs 24-hour time
date.toLocaleTimeString(new Date(), 'en-US', { hour12: false }))
  .then(result => cosnole.log(result)); // "19:00:00"

IString

Syntax

new IDate(string)

Argument Name	Type	Description
string	String	the reference string object

Methods

The IString class just has one method to comparing two string in same or different locales, the following method:

• localeCampare(referenceStr, compareString, locale, [options])

Arguments

Argument Name	Type	Description
compareString	String	the comparable string
locale	String	the locale string that string will be compared in
options *	Object	documents

Example

import IString from 'icu-loader'

// The letter  "a" is before "c" yielding a negative value
new IString('a').localeCompare('c')
  .then(result => cosnole.log(result)); // -2 or -1 (or some other negative valu e)

// Using locales
new IString('ä').localeCompare('z', 'sv')
  .then(result => cosnole.log(result)); // a positive value: in Swedish, ä sorts after z

// in German, ä has a as the base letter
new IString('ä').localeCompare('a', 'de', { sensitivity: 'base' }))
  .then(result => cosnole.log(result)); // 0

Number

Syntax

new INumber(number)

Argument Name	Type	Description
number	Number	the reference number object

Methods

this class has one method to represent a number in different locales, the following method:

• toLocaleString(numberObj, locale, [options])

Arguments

Argument Name	Type	Description
locale	String	the locale string that number will be displayed in
options *	Object	documents

Example

import INumber from 'icu-loader';

// English locale
new INumber(3500).toLocaleString()
  .then(result => cosnole.log(result)); // Displays "3,500" if in U.S.

// German uses comma as decimal separator and period for thousands
new INumber(123456.789).toLocaleString('de-DE')
  .then(result => cosnole.log(result)); // 123.456,789

// Using options
new INumber(30000000000).toLocaleString('fa-IR', { style: 'currency', currency: 'IRR' })
  .then(result => cosnole.log(result)); // ‎ریال۳۰٬۰۰۰٬۰۰۰٬۰۰۰

Contributing

To contribute to ICU Loader, clone this repo locally and commit your code on the development branch. Please run the linter before opening a pull request:

## To run tests
npm run test

## To find out the errors
npm run lint

## To fix automatically the errors
npm run lint:fix

License

ICU Loader is licensed under the MIT license, also full-icu package is part of ICU.

Copyright © 2018, Masoud Ghorbani