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);

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);

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

License

This package is MIT licensed.