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]$'.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:

# 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>.