lisan-plugin-l10n

i18n, Reimagined!

A blazing fast and super small i18n library for Javascript

---

Website

Installation · API · Guides & Tips · Examples

---

Lisan Plugin l10n

Lisan localization plugin allows you to format your data based on the locale.

Installation

You can install lisan from the sources below, as you see fit.

from npm

npm install lisan-plugin-l10n

from CDN

<script src="https://unpkg.com/lisan-plugin-l10n/dist/index.umd.js" type="text/javascript"></script>

After adding the script tag above, all public variables will be accessible via window.lisanPluginL10n variables.

Usage

const { lisan } = require('lisan');
const { Localization } = require('lisan-plugin-l10n');
const { tr } = require('lisan-locales');

lisan.use(Localization);

lisan.setLocale(tr);

lisan.toOrdinal(3); // Returns: 3'üncü

Hint

Lisan provides Lisan Locales package which contains production-ready Localization configurations.

You can find the full list of Localization configs here.

Methods

For the full list of methods, see Lisan Localization API.

Locale Configuration

Type Signature

interface LocaleConfig {
  name: string;

  conditions?: Conditions;

  number?: NumberFormatOptions;
  currency?: CurrencyFormatOptions;

  ordinal?: (num: number) => string;

  date?: {
    masks: DateMasks;
    amPm: string[];

    // weeks
    // Sunday is the first day
    weekdays: string[];
    weekdaysShort: string[];
    weekdaysMin: string[];

    // months
    months: string[];
    monthsShort: string[];
  };
}

name

Type: string (Required)
Default: ""

name is a string with a BCP 47 language tag.

---

conditions

Type: Conditions (Optional)
Default: {}

conditions is an object contains Condition Tag and Condition Functions.

conditions object will be passed down to lisan.addConditions method.

Type Signature

type ConditionFunction = (num: string | number) => boolean;
type Conditions = Record<string, ConditionFunction>;

Condition keys are especially useful to achieve Pluralization.

---

number

Type: NumberFormatOptions (Optional)
Default: {}

number takes number formatting options. When defined, the number formatter will be available in translations and lisan.toNumber method will be added to lisan instance.

Number formatting options have the following type definition.

Type Signature

interface NumberFormatOptions {
  grouping: {
    delimiters: string[];
    blocks: number[];
  };
  fraction: {
    delimiter: string;
    digits: number;
  };
  zeroFormat: string;
  nullFormat: string;
}

number.grouping

This option is being used to format numbers to have groups. Eg. thousand separators, lakh, wan

number.grouping.blocks

blocks is an array of numbers to define the length of each group.

• Grouping is done from right to left that means the first number in the array determines the last group length.
• The Grouping will continue by the last number in the array.

number.grouping.delimiters

delimiters is an array of numbers to define the delimiter of each group.

• Delimiters match with groups by the array indices.
• If the length of the blocks array is bigger than the length of delimiters, the last delimiter will be used for the rest of the groups.
• If the length of the blocks array is less than the length of delimiters, registerLocale method throws an Exception.

Grouping Examples

const output = lisan.toNumber(12345678901234567890);

blocks	delimiters	Output
[3]	[',']	12,345,678,901,234,567,890
[3, 2]	[',']	1,23,45,67,89,01,23,45,67,890
[3, 2]	['-', '.']	1.23.45.67.89.01.23.45.67-890
[2, 1, 2, 3]	['-', ' ', '#']	12#345#678#901#234#56 7-90
[3, 2, 2, 4]	['-', ' ',' ','#']	1#2345#6789#0123 45 67-890

Info

Grouping configuration options were inspired by cleave.js configuration options.

number.floating

number.floating.precision

This option is used to define the length of the decimal points.

• If the length of decimal points is longer than precision value, the decimal points will be rounded.
• If precision is 0, the floating-point will be hidden.
• If precision is -1, the floating-point will be printed as it is.

number.floating.delimiter

This option is used to define delimiter for the decimal point.

Decimal Point Examples

const output = lisan.toNumber(1234.1234567);

precision	delimiters	Output
0	.	1234
-1	.	1234.1234567
2	.	1234.12
3	,	1234,123
5	#	1234#12346

number.zeroFormat

This option is used to output a custom text when the given number equals 0.

number.nullFormat

This option is used to output a custom text when the given number equals to null.

---

currency

Type: CurrencyFormatOptions (Optional)
Default: {}

currency takes currency formatting options. When defined, the currency formatter will be available in translations and lisan.toCurrency method will be added to lisan instance.

Currency formatting options have the following type definition.

Type Signature

interface CurrencyFormatOptions {
  grouping?: {
    delimiters: string[];
    blocks: number[];
  };
  fraction?: {
    delimiter: string;
    digits: number;
  };
  zeroFormat?: string;
  nullFormat?: string;
  template: (formattedNumber: string) => string;
}

Hint

currency inherits configuration from number configuration. So you can override any of the configurations.

{
  "currency": {
    "floating": {
      "delimiter": ".",
      "precision": 2
    },
    "template": function(formattedNumber) {
      return "$" + formattedNumber;
    }
  }
}

currency.template

template is a function used to format price values.

---

ordinal

Type: CurrencyFormatOptions (Optional)
Default: x => x.toString()

ordinal takes ordinal function. The ordinal formatter is always available in translations and lisan.toOrdinal method is always added lisan instance.

Type Signature

{
  ordinal: (number: number) => string;
}

---

date

Type: DateOptions (Optional)
Default: {}

date is being used to set the configuration for various date formatters and it has the following type definition.

interface DateOptions {
  masks: {
    dateTime: string;
    dateShort: string;
    dateMedium: string;
    dateLong: string;
    dateFull: string;
    timeShort: string;
    timeMedium: string;
    timeLong: string;
  };
  amPm: string[];

  // weeks
  weekdays: string[];
  weekdaysShort: string[];
  weekdaysMin: string[];

  // months
  months: string[];
  monthsShort: string[];
}

date.masks

date.masks is being used to generate formatters with the same mask name:

• dateTime
• dateShort
• dateMedium
• dateLong
• dateFull
• timeShort
• timeMedium
• timeLong

These formatters then can be used in dictionaries as below:

lisan.add({
  entries: {
    simpleExample: ({ date }, { dateTime }) =>
      `This is formatted ${dateTime(date)}`,
  },
});

Also a method is created for corresponding formatter.

• lisan.toDateTime()
• lisan.toDateFull()
• lisan.toDateLong()
• lisan.toDateMedium()
• lisan.toDateShort()
• lisan.toTimeLong()
• lisan.toTimeMedium()
• lisan.toTimeShort()

date.amPm

amPM is an array. Only takes two string values in lowercase format, first being the am indicator and the second indicating pm.

date.weekdays

weekdays is an array and contains the names of the weekdays. The first item of the array has to be Sunday.

date.weekdaysShort

Same as date.weekdays, but shorter day names (usually 3 letters, eg. Sat)

date.weekdaysMin

Same as date.weekdays, but shorter day names (usually 2 letters, eg. St).

date.months

months is an array and contains the names of the months. The first item of the array has to be January.

date.monthsShort

Same as date.months, but shorter month names (usually 3 letters, eg. Jan).

Date Formatting Tokens

	Token	Output
Month	M	1 2 ... 11 12
	Mo	1st 2nd ... 11th 12th
	MM	01 02 ... 11 12
	MMM	Jan Feb ... Nov Dec
	MMMM	January February ... November December
Quarter	Q	1 2 3 4
	Qo	1st 2nd 3rd 4th
Day of Month	D	1 2 ... 30 31
	Do	1st 2nd ... 30th 31st
	DD	01 02 ... 30 31
Day of Year	DDD	1 2 ... 364 365
	DDDo	1st 2nd ... 364th 365th
	DDDD	001 002 ... 364 365
Day of Week	d	0 1 ... 5 6
	do	0th 1st ... 5th 6th
	dd	Su Mo ... Fr Sa
	ddd	Sun Mon ... Fri Sat
	dddd	Sunday Monday ... Friday Saturday
ISO Week Number of Year	w	1 2 ... 52 53
	wo	1st 2nd ... 52nd 53rd
	ww	01 02 ... 52 53
Year	YY	70 71 ... 29 30
	YYYY	1970 1971 ... 2029 2030
AM/PM	A	AM PM
	a	am pm
Hour	H	0 1 ... 22 23
	HH	00 01 ... 22 23
	h	1 2 ... 11 12
	hh	01 02 ... 11 12
	k	1 2 ... 23 24
	kk	01 02 ... 23 24
Minute	m	0 1 ... 58 59
	mm	00 01 ... 58 59
Second	s	0 1 ... 58 59
	ss	00 01 ... 58 59
Fractional Second	S	0 1 ... 8 9
	SS	00 01 ... 98 99
	SSS	000 001 ... 998 999
Time Zone	Z	-07:00 -06:00 ... +06:00 +07:00
	ZZ	-0700 -0600 ... +0600 +0700
Unix Timestamp	X	1360013296
Unix Millisecond Timestamp	x	1360013296123

License

This package is MIT licensed.