Dictionary · Lisan

Introduction

A Lisan Dictionary is a Javascript Object that contains string or function entries. It can also contain Conditional Groups

A dictionary can be used after being registered to lisan instance via lisan.add() method.

Info

You can automatically generate dictionaries from Translations by using Lisan CLI.

For full list of options and commands, see: Lisan CLI API.

Type Signature

interface Dictionary {
  locale?: string;
  entries: {
    [EntryKey: string]: DictionaryEntry | ConditionalGroup;
  };
}

Dictionary Entry

Dictionary Entry is a string or a function that returns a string.

Conditional Group

If a Dictionary Entry is an object, it is considered as a Conditional Group.

In that case Entry Key is also called Conditional Group Key.

Example

const lisan = require('lisan');

lisan.add({
  locale: 'en-US',
  entries: {
    'hello.world': 'Hello World!',
    'hello.person': ({ name }) => `Hello ${name}`,
  },
});

const text1 = lisan.t('hello.person', { name: 'John' });
console.log(text1);
// Outputs: "Hello John"

Hint

To minimize loading time or main bundle size, you can split your entries into several dictionaries.

Dictionary Object

locale (Optional)

locale is a string and a valid BCP 47 language tag.

It is optional. However, when defined it might change lisan.add() method's behaviour.

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

Example:

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

lisan.setLocaleName('tr');

lisan.add({
  locale: 'en-US',
  entries: {
    'hello.world': 'Hello World!',
    'hello.person': ({ name }) => `Hello ${name}`,
  },
}); // Throws: 'Dictionary locale "en-US" is different than selected locale "tr"'

Warning

Please note that in the example above, the dictionary WILL NOT BE REGISTERED,
because its locale is different than selected locale's name tr.name which is "tr".

entries

entries is a key-value map and have the following type definition:

Entry Key is a string and a unique identifier for the Dictionary Entry,
Dictionary Entry is a string or a function that returns a string or a Conditional Group

Warning

When the Lisan Dictionary was registered, duplicate entries will be overwritten. So make sure, dictionaries do not share same Entry Keys.