💾 @mirai/locale

A locale-based formatting library.

📦 Setup

Add the package in your project:

yarn add @mirai/locale

currencyFormat()

Price formatter based on the currency and the locale.

An additional 'fancy' format option allows to shorten large numbers:

12 500 --> 12.5k
12 500 000 --> 12.5M

This method receives as a parameter an object with following properties:

• currency currency ISO code ('EUR' by default)
• fancy a boolean indicating if fancy format should be applied (optional, 'false' by default)
• locale locale string ('es-ES' by default)
• symbol a boolean that indicates if we show the symbol of the given currency meanwhile its length is no more than 2 chars, or 1 char if fancy is true (optional, 'false' by default)
• value the amount to be formatted (0 by default)
• ...others in the case we want extend the Intl.NumberFormat object.

import { currencyFormat } from '@mirai/locale';

const price = currencyFormat({ currency: 'EUR', fancy: true, locale: 'es-ES', value: 12350 });
>> '12,3k €'

dateCalc()

This method allows to add to/ subtract from a date a number of days, months or years and returns a Date object. Parameters to be provided:

• value a Date object with initial date
• amount number of days/months/years to be added/subtracted (0 by default)
• context units to be added/subtracted ('days'(default)/ 'months' / 'years')

import { dateCalc } from '@mirai/locale';

console.log(dateCalc(new Date(2022, 3, 28), 7, 'days'));
>> Thu Apr 28 2022 00:00:00 GMT+0200 (Central European Summer Time)

dateDiff()

This method calculates the duration of period between 2 dates and returns an object with years, months and days. Parameters to be provided:

• from a Date object with start date
• to a Date object with end date

import { dateDiff } from '@mirai/locale';

const newDate = dateDiff(new Date(2022, 2, 28), new Date(2023, 2, 28));
>> { years: 1, months: 12, days: 365 }

In case that the value of from is greater than to, the difference will be negative.

dateFormat()

Locale-based date formatter receiving the following parameters:

• value a Date object with date to be formatted
• Second parameter is a object containing:
  • locale locale string ('es-ES' by default)
  • delimiter delimiter type ('/' by default)
  • format a string with target date format (e.g. 'DD/MM/YYYY')
  • options a configuration object specifying the formats of weekday, year, month and day

import { dateFormat } from '@mirai/locale';

const today = dateFormat(new Date(), { locale: 'en-DB', weekday: 'long', year: 'numeric', month: 'long', day: 'numeric' });
>> 'Friday, 15 April 2022'

const anotherDate = dateFormat(new Date(2022, 4, 15), { delimiter: '-', format: 'DD-MM-YYYY' });
>> '15-04-2022'

getDateFormat()

This method returns a format string corresponding to locale passed as parameter:

• locale locale string ('es-ES' by default)

import { getDateFormat } from '@mirai/locale';

const defaultFormat = getDateFormat()
>> 'DD/MM/YYYY'
const usFormat = getDateFormat('en-US')
>> 'MM/DD/YYYY'
const arabicFormat = getDateFormat('ar');
>> 'YYYY/M/D'

isDate()

This method checks if the parameter received is a valid Date object:

• value to be checked

import { isDate } from '@mirai/locale';

const isDateObject = isDate(new Date(2023, 3, 28));
>> true

const isDateObj = isDate('some string');
>> false

parseDate()

This method converts a date string into a Date object. Parameters to be provided:

• value a date string
• format a string with applied format

import { parseDate } from '@mirai/locale';

console.log(parseDate('28/04/2022', 'DD/MM/YYYY'));
>> Thu Apr 28 2022 00:00:00 GMT+0200 (Central European Summer Time)

translate()

This method receives a dictionary and a key, and return the value for this key. Supports bindings (passed in arguments) in many ways:

• simple binding. In the value of dictionary you can have a binding like {language} and the method replace the binding for the value passed like binding in arguments.

import { translate } from '@mirai/locale';

const dictionary = {
  'hello.world': 'I love {language}',
  'select.boolean': 'I love {isCompiled, select, true {python} other {php}}',
  'exist.language': '{numLanguages, plural, =1 {Exist # language}  other {Exists # languages}}',
};
const key = { id: 'hello.world' };
const bindings = { language: 'python' };

translate({ dictionary, key, bindings });
>> 'I love python';

• select binding. In the value of dictionary you can have a binding like 'I love {isCompiled, select, true {python} other {php}}' and the method, select the option that corresponds with the binding value. This binding value can be a boolean or a number.

const key = { id: 'select.boolean' };
const bindings = { isCompiled: false };

translate({ dictionary, key, bindings });
>> 'I love php';

• plural binding. In the value of dictionary you can have a binding like {numLanguages, plural, =1 {Exist # language} other {Exists # languages}} and the method select the option that corresponds with the number that have the binding value. And also replace the text that have the character '#' for the number that have the binding value.

const key = { id: 'exist.language' };
const bindings = { numLanguages: 1 };

translate({ dictionary, key, bindings });
>> 'Exist 1 language';

Also supports HTML syntax in the value of dictionary.

UTC()

This method receives a date object as a parameter and converts it to UTC standard:

• value Date object to be converted

import { UTC } from '@mirai/locale';

const todayUTC = UTC(new Date(2022, 2, 28)) >> '2022-03-28T00:00:00.000Z';