Edit

Full API Reference

Here you can find all the methods provided by lisan library and it's official plugins lisan-plugin-loader, lisan-plugin-l10n.

Methods

• lisan.use(fn)
• lisan.setLocaleName(name)
• lisan.getLocaleName()
• lisan.add(dictionary)
• lisan.addConditions(conditions)
• lisan.addFormatters(formatters)
• lisan.t(key, placeholders?)
• lisan.c(key, value, placeholders?)
• lisan.load(dictionaryName)
• lisan.loadLocale(localeName)
• lisan.setLocale(localeConfig)
• lisan.toNumber(number)
• lisan.toCurrency(amount)
• lisan.toOrdinal(number)
• lisan.toDateTime(time)
• lisan.toDateFull(time)
• lisan.toDateLong(time)
• lisan.toDateMedium(time)
• lisan.toDateShort(time)
• lisan.toTimeLong(time)
• lisan.toTimeMedium(time)
• lisan.toTimeShort(time)

Lisan Methods

Methods below are coming from lisan package.

lisan.use(fn)

Useful when you'd like to extend Lisan's functionalities.

Input

parameter	type	description
fn	TSLisan.Plugin	Plugin function that mutates lisan instance

Returns: void

Usage

const { lisan } = require('lisan');

lisan.use(self => {
  self.newMethod = () => console.log("I'm a new Method");
});

lisan.newMethod();

// Outputs: "I'm a new Method"

For more information, See: How to write Plugins.

lisan.setLocaleName(name)

Updates the locale name of lisan instance.

Input

parameter	type	description
name	string	Updates locale name to given value

Returns: void, returns configured locale name.

Usage

const { lisan } = require('lisan');

lisan.setLocaleName('en-US');

console.log(lisan.getLocaleName()); // Outputs: "en-US"

lisan.getLocaleName()

Returns the configured locale name of lisan instance.

Returns: string

Usage

const { lisan } = require('lisan');

lisan.setLocaleName('en-US');

console.log(lisan.getLocaleName()); // Outputs: "en-US"

lisan.add(dictionary)

Registers dictionary object to Lisan instance. New dictionary entries are merged with existing dictionary entries.

Existing dictionary keys will be overwritten by the latest ones.

If dictionary locale is defined and different than the selected locale name, then the dictionary object will not be registered. This mechanism is there to prevent loading a dictionary created explicitly for another language or locale. See: lisan.setLocaleName()

Input

parameter	type	description
dictionary	TSLisan.Dictionary	Dictionary object that contains entries

Returns: this, returns the instance, so add methods are chainable.

Usage

const { lisan } = require('lisan');

lisan.add({
  entries: {
    helloWorld: 'Hello World',
    helloPerson: ({ name }) => `Hello ${name}`,
  },
});

lisan.t('helloPerson', { name: 'John' });

// Outputs: "Hello John"

lisan.addConditions(conditions)

Adds new condition tags that can be used in Conditional Groups.

Input

parameter	type	description
conditions	TSLisan.Conditions	Object that contains condition functions

Returns: this, returns the instance, so methods are chainable.

Usage

const { lisan } = require('lisan');

lisan.addConditions({
  // "Condition Tag": Condition Function,
  few: num => num > 1 && num <= 5,
});

lisan.add({
  entries: {
    // "Conditional Group Key":
    howManyPeople: {
      zero: 'There is nobody.',
      one: 'There is one person.',
      few: 'There are a few people.',
      other: 'There are a lot of people.',
    },
  },
});

lisan.c('howManyPeople', 0);
// Returns: "There is nobody."

lisan.c('howManyPeople', 1);
// Returns: "There is one person!"

lisan.c('howManyPeople', 3);
// Returns: "There are a few people."

lisan.c('howManyPeople', 10);
// Returns: "There are a lot of people."

lisan.addFormatters(formatters)

Adds new formatters that can be used in Dictionary Entries.

Input

parameter	type	description
formatters	TSLisan.Formatters	Object that contains formatter functions

Returns: this, returns the instance, so methods are chainable.

Usage

const { lisan } = require('lisan');

lisan.addFormatters({
  toFixed: num => num.toFixed(2),
  roundNumber: num => Math.round(num).toString(),
});

lisan.add({
  entries: {
    'rounded.number': ({ value }, { roundNumber, toFixed }) =>
      `${${toFixed(value)}} is rounded to ${roundNumber(value)}.`,
  },
});

const text = lisan.t('rounded.number', {
  value: 5.3123,
});

console.log(text);
// Outputs: "5.31 is rounded to 5."

lisan.t(key, placeholders?)

Input

parameter	type	description
key	string	Dictionary entry key
placeholder (Optional)	object	Key-value object used to interpolate entries

Returns: string, interpolated dictionary entry

Usage

const { lisan, t } = require('lisan');

lisan.add({
  entries: {
    helloWorld: 'Hello World',
    helloPerson: ({ name }) => `Hello ${name}`,
  },
});

t('helloWorld'); // Returns: "Hello World"
lisan.t('helloPerson', { name: 'John' }); // Returns: "Hello John"

Throws an exception if the key is a conditional group key.

Learn more about Dictionary.

lisan.c(key, value, placeholders?)

Input

parameter	type	description
key	string	Conditional group key
value	string | number	Value used to determine which conditional entry key will be used
placeholder (Optional)	object	Key-value object used to interpolate entries

Returns: string, interpolated dictionary entry

Usage

const { lisan, c } = require('lisan');

lisan.add({
  entries: {
    childGroup: {
      zero: 'none',
      one: 'child',
      other: 'children',
    },
  },
});

c('childGroup', 0); // Returns: "none"
c('childGroup', 1); // Returns: "child"
lisan.c('childGroup', 5); // Returns: "children"

Throws an exception if the key is not a conditional group key.

Learn more about Conditional Groups.

Loader Plugin

The methods below are introduced by using lisan-plugin-loader plugin.

You can find the setup instructions and available options here.

lisan.load(dictionaryName)

Input

parameter	type	description
dictionaryName	string	name of the dictionary file

Returns: Promise<string>, loaded script element id as string.

Usage

const { lisan } = require('lisan');
const { Loader } = require('lisan-plugin-loader');

lisan.use(
  Loader({
    localeUrlFn: ({ localeName }) =>
      `https://cdn.mydomain.com/static/locales/${localeName}.js`,
    dictionaryUrlFn: (dictionaryName, localeName) =>
      `https://cdn.mydomain.com/static/${localeName}/dictionaries/${dictionaryName}.js`,
  }),
);

lisan.loadLocale('tr-TR').then(() => {
  // Loaded https://cdn.mydomain.com/static/locales/tr-TR.js

  lisan.load('main').then(() => {
    // Loaded https://cdn.mydomain.com/static/tr-TR/dictionaries/main.js
    const translated = lisan.t('hello.person', {
      name: 'John Doe',
    });
    console.log(translated); // Merhaba John Doe
  });
});

lisan.loadLocale(localeName)

Input

parameter	type	description
localeName	string	name of the locale file

Returns: Promise<string>, loaded script element id as string.

Usage

const { lisan } = require('lisan');
const { Localization } = require('lisan-plugin-l10n');
const { Loader } = require('lisan-plugin-loader');

lisan.use(Localization);
lisan.use(
  Loader({
    localeUrlFn: localeName =>
      `https://unpkg.com/lisan-locales/dist/${localeName}.lisan.js`,
  }),
);

lisan.loadLocale('tr').then(() => {
  // Loaded https://unpkg.com/lisan-locales/dist/tr.lisan.js

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

Localization Plugin

The methods below are introduced by using lisan-plugin-l10n plugin.

You can find the setup instructions and available options here.

Hint

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

You can find the full list of Localization configs here.

lisan.setLocale(localeConfig)

Input

parameter	type	description
localeConfig	TSLisan.LocaleConfig	Locale config object

Returns: void

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ü

lisan.toNumber(number)

Returns the given number as formated in the locale format.

Input

parameter	type
number	Integer | Float

Returns: string

Usage

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

lisan.use(Localization);

lisan.setLocale(tr);

lisan.toNumber(123456.789); // Returns: 123.456,789

lisan.toCurrency(amount)

Returns the given amount as formated in the locale format.

Input

parameter	type
amount	Integer | Float

Returns: string

Usage

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

lisan.use(Localization);

lisan.setLocale(tr);

lisan.toCurrency(123456.789); // Returns: "₺123.456,79"

lisan.toOrdinal(number)

Returns number with ordinal postfix or prefix as a string in the locale format.

Input

parameter	type
number	Integer

Returns: string

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ü"

lisan.toDateTime(time)

Returns date as string formated in dateTime mask format.

Input

parameter	type
time	number | Date

time can be either Unix Time in Miliseconds or a Date object.

Returns: string

lisan.toDateFull(time)

Returns date as string formated in dateFull mask format.

Input

parameter	type
time	number | Date

time can be either Unix Time in Miliseconds or a Date object.

Returns: string

lisan.toDateLong(time)

Returns date as string formated in dateLong mask format.

Input

parameter	type
time	number | Date

time can be either Unix Time in Miliseconds or a Date object.

Returns: string

lisan.toDateMedium(time)

Returns date as string formated in dateMedium mask format.

Input

parameter	type
time	number | Date

time can be either Unix Time in Miliseconds or a Date object.

Returns: string

lisan.toDateShort(time)

Returns date as string formated in dateShort mask format.

Input

parameter	type
time	number | Date

time can be either Unix Time in Miliseconds or a Date object.

Returns: string

lisan.toTimeLong(time)

Returns date as string formated in timeLong mask format.

Input

parameter	type
time	number | Date

time can be either Unix Time in Miliseconds or a Date object.

Returns: string

lisan.toTimeMedium(time)

Returns date as string formated in timeMedium mask format.

Input

parameter	type
time	number | Date

time can be either Unix Time in Miliseconds or a Date object.

Returns: string

lisan.toTimeShort(time)

Returns date as string formated in timeShort mask format.

Input

parameter	type
time	number | Date

time can be either Unix Time in Miliseconds or a Date object.

Returns: string