# locini

> A simple localization library using ini files.

Latest version **1.0.6** (published 2019-01-14) · MIT license · 0 weekly downloads

## Install

```sh
npm install locini
pnpm add locini
yarn add locini
bun add locini
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.6 |
| Published | 2019-01-14 |
| First published | 2019-01-07 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 1 |
| Unpacked size | 5.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | 4erem6a |
| Maintainers | 4erem6a |
| Keywords | localization, ini |

## Links

- npm: https://www.npmjs.com/package/locini
- npm.io page: https://npm.io/package/locini

## Dependencies (1)

- [ini](https://npm.io/package/ini.md) ^1.3.5

## Recent versions

- 1.0.6 (latest) — 2019-01-14
- 1.0.5 — 2019-01-07
- 1.0.4 — 2019-01-07
- 1.0.3 — 2019-01-07
- 1.0.2 — 2019-01-07
- 1.0.1 — 2019-01-07
- 1.0.0 — 2019-01-07

## README

A simple localization library using ini files with string formatting.

## Usage

Consider a `locale/en.ini` file:
```ini
[greeting]
hello = Hello, $name    ; You can use placeholders to insert data into strings
hi = Hi, $name
```

An `index.js` file:
```js
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

```js
'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:

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

---
_Source: https://npm.io/package/locini · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._