Edit

Lisan Compiler

Here you can find all supported options and methods provided by lisan-compiler library.

Methods

• parseLisanLiteral(lisanLiteral)
• parse(json, parseOptions)
• generate(parsedDictionary, generateOptions)

parseLisanLiteral(lisanLiteral, options?)

Parses a single Lisan Literal string.

Input

parameter	type	description
lisanLiteral	string	A valid lisan literal string
options (optional)	string	Changes parsing behaviour

Returns: object - returns ParsedLisanLiteral object that has the following type signature:

interface ParsedLisanLiteral {
  input: string;
  output: string;
  variables: string[];
  functions: string[];
  conditionalGroupKeys: string[];
  entryKeys: string[];
}

Throws: exception if the given entry is not valid.

Usage

import { parseLisanLiteral } from 'lisan-compiler';

const lisanLiteral =
  "Some text ${c('conditionKey1', value1)} ${t('entryKey1', value4)} dateLong(value5) ${c('conditionKey2', value3, {value2})}";

const options = {};
const parsedEntry = parseLisanLiteral(lisanLiteral);

console.log(parsedEntry);

{
  "input": "Some text ${c('conditionKey1', value1)} ${t('entryKey1', value4)} dateLong(value5) ${c('conditionKey2', value3, {value2})}",
  "output": "({ value1, value4, value5, value3, value2 }, { c, t, dateLong }) => `Some text ${c('conditionKey1', value1)}  ${t('entryKey1', {value4})} ${dateLong(value5)} ${c('conditionKey2', value3, {value2})}`",
  "variables": ["value1", "value4", "value5", "value3", "value2"],
  "functions": ["c", "t", "dateLong"],
  "conditionalGroupKeys": ["conditionKey1", "conditionKey2"],
  "entryKeys": ["entryKey1"]
}

ParseLisanLiteral Options

returnArray

Type: boolean
CLI: --returnArray
Default: false,

Instead of interpolating the output as a string, it returns HTML elements in an array to make it compatible with JSX syntax.

All elements of array can be also rendered by Array.join .

parse(json, parseOptions?)

Parses a Translation JSON object into a parsedDictionary object that has following type signature:

interface ParsedEntry {
  input: string;
  output: string;
  variables: string[];
  functions: string[];
  entryKeys: string[];
  conditionalGroupKeys: string[];
  key: string;
  groupKey?: string;
}

interface ParsedDictionary {
  locale: string;
  entries: ParsedEntry[];
}

parse function also does a lot of semantic checks. That's why please always use this function to generate your dictionaries.

Input

parameter	type	description
json	object	A valid Translation JSON Object
parseOptions	object (optional)	Parse Options

Returns: string - returns the source code for the dictionary file.

Throws: exception if the given JSON contains errors.

Usage

import { parse } from 'lisan-compiler';

const source = fs.readFileSync('main.json', 'utf-8');
const json = JSON.parse(source);

const parsedDictionary = parse(json);

console.log(parsedDictionary);

Parse Options

returnArray

Type: boolean
CLI: --returnArray
Default: false,

Instead of interpolating the output as a string, it returns HTML elements in an array to make it compatible with JSX syntax.

All elements of array can be also rendered by Array.join .

allowNonExistingKeys

Type: boolean
CLI: --allowNonExistingKeys
Default: false,

When set to false, compiler validates all the key usages in the dictionary. If Lisan Literal has t() or c() functions that are calling a non-existing entry, compiler throws exception.

You may want to set it to true, if you split your dictionaries into seperate chunks and use a key that was created in another dictionary file. However, in that case, dictionary containing the entry must be loaded before!

autoTrimValues

Type: boolean
CLI: --autoTrimValues
Default: true

AUtomatically trims the whitespace characters from both sides for every Lisan Literal entry.

sortEntryKeys

Type: boolean
CLI: --sortEntryKeys
Default: true

Sorts dictionary keys by alphabetical order.

generate(parsedDictionary, generateOptions?)

Generate function always renders a Javascript ES2015 (ES6) code.
If you wish to have ES5 code, you can use lisan-cli

Input

parameter	type	description
parsedDictionary	object	A valid Parsed Dictionary Object
parseOptions	object (optional)	Compile Options

Returns: string - returns the source code for the dictionary file.

Throws: exception if the given options are not valid.

Usage

import { parse, generate } from 'lisan-compiler';

const source = fs.readFileSync('main.json', 'utf-8');
const json = JSON.parse(source);

const parsedDictionary = parse(json);
const dictionarySource = generate(parsedDictionary, {
  module: 'cjs',
});

fs.writeFileSync('main.js', dictionarySource, 'utf-8');

Generate Options

module

Type: string
CLI: --module <moduleType>
Default: "lisan"

Specifies the module format of the generated bundle. One of the following:

• none – returns plain dictionary object as a string.
• cjs – CommonJS, suitable for Node and other bundlers.
• esm – Keep the bundle as an ES module file, suitable for other bundlers and inclusion as a <script type=module> tag in modern browsers.
• lisan - extends CommonJS module definition with an iife so that the module can be used with lisan-plugin-loader.

lisan module looks like below:

(function(module) {
  // exports the dictionary object
  module.exports = {
    locale: 'en-US',
    entries: {
      // entries
    },
  };
})(
  typeof module === 'object' && module.exports
    ? module
    : window.lisanLoaderListener,
);