npm package: @mirai/locale
Description: Test publication on npm
Latest version: 0.3.23

# 💾 @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.

```js
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')

```js
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

```js
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

```js
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)

```js
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

```js
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

```js
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.

```js
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.

```js
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.

```js
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

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

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