locini

A simple localization library using ini files with string formatting.

Usage

Consider a locale/en.ini file:

[greeting]
hello = Hello, $name    ; You can use placeholders to insert data into strings
hi = Hi, $name

An index.js file:

const locini = require('locini');

locini.loadFromSync(`${__dirname}/locale`);

console.log(
    locini.use('en').greeting.hello.format({ name: 'John' })
);
// Expected output: Hello, John

Placeholders

Placeholder format:
$key
$[key]
$key[alt]
$[key][alt]

Where:
key is an object property key.
alt is an alternative text used if key does not exists.

If alt is not specified and key does not exists, the placeholder will be replaced with an empty string.

Placeholder/format examples

'Name: $name'.format({ name: 'John' })      //-> Name: John
'Name: $name[Anonymous]'.format()           //-> Name: Anonymous
'Values: $0, $1'.format('first', 'second')  //-> Values: first, second
'Item cost: $[cost]
Locale ID
Locale id is a unique key to distinct locales.
By default it is set to locale's filename.
You can override it in your locale file as follows:
# Overriding locale id
[locini]
id = overridden_id
API
format(string, first, ...rest)
String.prototype.format(first, ...rest)
Replace placeholders in the string with property values from the key object.
The key object:
If first is an object: { ...first, ...[first, ...rest] }
Else: [first, ...rest] 
Returns formatted string.
define(id, locale)
Define locale using id locale id and locale ini string.
async load(filename, options = 'utf8')
Load locale file by it's filename.
options: File reading options.
loadSync(filename, options = 'utf8')
Synchronously load locale by it's filename.
options: File reading options.
async loadFrom(dirname, filter, options = 'utf8')
Load locale files from specified directory dirname.
filter: Directory file filter (filename => boolean).
options: File reading options.
loadFromSync(dirname, filter, options = 'utf8')
Synchronously load locale files from specified directory dirname.
filter: Directory file filter (filename => boolean).
options: File reading options.
use(locale)
Get locale object by id locale.
locales()
Get all stored locales as Map<string, object>.
.format({ cost: 10 })  //-> Item cost: 10$

Locale ID

Locale id is a unique key to distinct locales. By default it is set to locale's filename. You can override it in your locale file as follows:

__CODE_BLOCK_3__

API

format(string, first, ...rest)

String.prototype.format(first, ...rest)

Replace placeholders in the string with property values from the key object.
The key object:
If first is an object: __INLINE_CODE_11__
Else: __INLINE_CODE_12__

Returns formatted string.

define(id, locale)

Define locale using __INLINE_CODE_13__ locale id and __INLINE_CODE_14__ ini string.

async load(filename, options = 'utf8')

Load locale file by it's __INLINE_CODE_15__.

__INLINE_CODE_16__: File reading options.

loadSync(filename, options = 'utf8')

Synchronously load locale by it's __INLINE_CODE_17__.

__INLINE_CODE_18__: File reading options.

async loadFrom(dirname, filter, options = 'utf8')

Load locale files from specified directory __INLINE_CODE_19__.

__INLINE_CODE_20__: Directory file filter (__INLINE_CODE_21__).
__INLINE_CODE_22__: File reading options.

loadFromSync(dirname, filter, options = 'utf8')

Synchronously load locale files from specified directory __INLINE_CODE_23__.

__INLINE_CODE_24__: Directory file filter (__INLINE_CODE_25__).
__INLINE_CODE_26__: File reading options.

use(locale)

Get locale object by id __INLINE_CODE_27__.

locales()

Get all stored locales as __INLINE_CODE_28__.