# lstrings

> Localization for block

Latest version **4.1.1** (published 2021-07-26) · MPL-2.0 license · 0 weekly downloads

## Install

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

## Health

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

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types.

Negative: insecure dependencies; abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 4.1.1 |
| Published | 2021-07-26 |
| First published | 2021-07-26 |
| Weekly downloads | 0 |
| License | MPL-2.0 |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 23.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Belcar Santiago Cuentas-Zavala Infante |
| Maintainers | belcar-s |

## Links

- npm: https://www.npmjs.com/package/lstrings
- Repository: https://github.com/blockcito/lstrings
- Homepage: https://github.com/blockcito/lstrings#readme
- Issues: https://github.com/blockcito/lstrings/issues
- npm.io page: https://npm.io/package/lstrings

## Dependencies (1)

- [own-location](https://npm.io/package/own-location.md) git+https://github.com/blockcito/own-location.git

## Recent versions

- 4.1.1 (latest) — 2021-07-26

## README

# lstrings

lstrings is a module created to facilitate the localization of block and its command applications.

## Usage

```javascript
import Localize from "lstrings";
import { getScriptDir } from "own-location";

const localize = new Localize(getScriptDir(import.meta.url), {
	locale: "en-US",
	fallbackLocale: "en-US",
});

async () => {
	console.log(await localize.find("welcome", ["Santiago"]));
	// If certain characteristics of the file system are satisfied:
	// → Thanks for installing this program, Santiago!
};
```

The `Localize` constructor has two parameters: `lstringsDir`, the directory lstrings will be searched in; and `options`, an object that defines _the locale_ and _the fallback locale_.

The `find` method of `Localize` instances has two parameters: `lstringIdentifier` and `substitutes`.

Upon calls to the `find` method of `Localize` instances, it is checked whether a file whose name begins with _the locale_, and ends with `.lstrings.js`, exists.

If it exists, it is executed, and a property whose name is `lstringIdentifier` is looked for in **the default export.**

- If the property is a function, `subtitutes`, **which is to be an array or other iterable**, is passed as its arguments. Then, a Promise is returned that resolves to that function's return value.
- If the property is not a function, a Promise is returned that resolves to the property.

If it does not exist, _the locale_ is removed all characters that come after its hyphen. It is then checked whether a file whose name begins with the resulting string, and ends with `.lstrings.js`, exists. If it does, it is subject of an execution of the process described above.

If it does not exist, it is checked whether a file whose name begins with _the fallback locale_, and ends with `.lstrings.js`, exists. If it does, it is subject of an execution of the process described above.

### Order

- lstrings file of the locale requested
- lstrings file whose name is indicative of being in the same language as that requested
- lstrings file of the `fallbackLocale`

### Examples

If, for example, the lstrings directory contains these files:

```
.
├── en-US.lstrings.js
├── en-GB.lstrings.js
├── es.lstrings.js
└── script.js
```

Of which `en-US.lstrings.js` is of these contents:

```javascript
export default {
	welcome: (name) => `Thanks for installing this program, ${name}!`,
};
```

And the locale provided is en-US, the following call of `find` would return a promise that resolves to `"Thanks for installing this program, Santiago!"`:

```javascript
localize.find("welcome", ["Santiago"]);
```

The second argument is an array of values passed to the property whose name is the first argument.

If `welcome` weren't a function, this array would have been ignored.

Note that the directory lstrings will be searched in is determined by the first argument of the `Localize` constructor.

#### Fallbacks

If the requested locale is not available, one which matches its language will be used:

```
.
├── zh-CN.lstrings.js
├── en-GB.lstrings.js
├── es.lstrings.js
└── script.js
```

en-GB strings will be provided if en-US ones are requested.

If no available locale is of the requested one's language, the locale corresponding to the `fallbackLocale` property of the object provided to the `Localize` constructor is accessed.

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