lstrings v4.1.1

lstrings

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

Usage

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:

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!":

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.