Ilingo NPM | npm.io

Ilingo 💬

This is a lightweight library for translation and internationalization. It can be used for client- & server-side applications 🔥. A bundled version exists for formats such as ESM, CommonJS, AMD, and IIFE-style scripts ⭐.

The file-system access is only available on server-side applications but locale groups can also be hydrated by manipulating the cache.

Table of Contents

Installation

npm install ilingo --save

Important NOTE

The library provides sync and async methods to receive a (compiled) locale key string. The reason for this is that on server side application, the library interacts with the file system, and this can be done in blocking and non-blocking way for the event-loop ⭐. On client side applications, use the sync methods 🔥

Configuration

While full localization of an application is a complex subject, swapping out strings in your application for different supported languages/locales is simple.

Client

On the client side, no configuration is required. The different locale strings for translation are provided by interacting with the library class instance.

Server

Locale strings are stored in subdirectories as group for each supported language (locale) on the server side.

├── ...
└── language
    ├── de
    │   ├── app.{ts,js,json}      # app group
    │   └── forum.{ts,js,json}    # forum group
    └── en
        ├── app.{ts,js,json}      # app group
        └── forum.{ts,js,json}    # forum group

To get started, create a language directory somewhere in your project. Create a folder inside for each locale (e.g. en, de, ...), which should be supported.

The created folder represents a locale group. These groups do not have to follow any specific naming convention. You should name the file logically to describe the type of content it holds (e.g. app, forum, ...). For example, let’s say you want to create a file containing error messages. You might simply name it: error.{ts,js,json}.

Each file should return an object with a language key and a locale string.

app.{ts,js,json}

module.exports = {
    'key': 'The locale string to be shown.'
}

The object can also be (deeply) nested ⚡.

app.{ts,js,json}

module.exports = {
    'nested': {
        'key': 'The locale string to be shown.'
    }
}

It is also possible to use export default {...} instead of module.exports = {...} for script files.

Usage

Basic

The primary usage is just to create an instance of the Language class and either set one or more directories, which should be scanned on the server-side.

import { Language } from "ilingo";

const language = new Language({
    directory: [path.join(process.cwd(), 'language')],
    locale: 'en'
})

The other option for client-side applications, which can also be used in addition on server side, is manipulating the cache, on instance creation or afterward by a method call.

import { Language } from "ilingo";

const language = new Language({
    cache: {
        // locale: en
        en: {
            // group: app
            app: {
                key: 'The locale string to be shown.'
            }
        }
    },
    locale: 'en'
});

// The second parameter specifies,
// if the cache should be extended or overwritten.
language.setCache({
    // locale: de
    de: {
        // group: app
        app: {
            key: 'Der anzuzeigende string.'
        }
    }
}, true);

To retrieve text from any of the language files, simply pass the filename/group and the language key as the first parameter, separated by a period (.).

After that you can simply receive the locale string, like described in the following:

import { Language } from "ilingo";

const language = new Language({...});

console.log(language.getSync('app.key'));
// The locale string to be shown.

console.log(language.getSync('app.key', {}, 'de'));
// Der anzuzeigende string.

Singleton

The library also supports build in singleton support. There can exist multiple side-by-side instances, by providing a key as an additional parameter for the singleton method.

The default key is: default

The fist step, is to specify a configuration for the singleton instance if you do not want to use the default ones. Options are only passed to the class if it is not created yet!

import {useLanguage} from "ilingo";

useLanguage({
    /**
     * Default: path.join(process.cwd(), 'language')
     */
    directory: [path.join(process.cwd(), 'language')],
    /**
     * Default: en
     */
    locale: 'en'
}, 'default');

console.log(useLanguage().getSync('app.key'));
// The locale string to be shown.

console.log(
    useLanguage(undefined, 'default')
        .getSync('app.key')
);
// The locale string to be shown.

Helper

Besides, using the singleton instance, the library also provides helper functions for faster access.

The helper always refers to the default singleton instance and should therefore be used with caution if multiple singleton instances are used.

import { useLanguage } from "ilingo";

(async () => {
    console.log(await useLanguage().getSync('app.key'));

    // lang is a helper function for fast access ;)
    console.log(await lang('app.key'));
})();

Parameters

As a template delimiter a mustache like brackets {{}} interpolation is used. Data properties can be injected as second argument, e.g.

app.{ts,js,json}

module.exports = {
    'age': 'I am {{age}} years old.'
}

(async () => {
    const output = await lang('app.age', {age: 18});
    console.log(output);
    // I am 18 yeas old
});

Locales

The default locale, which is used by the singleton instance, can be globally overwritten after initialization:

import { useLanguage } from "ilingo";

(async () => {
    const language = useLanguage();

    let output = await language.get('app.age', {age: 18});
    console.log(output);
    // I am 18 yeas old

    language.setLocale('de');

    output = await lang('app.age', {age: 18});
    console.log(output);
    // Ich bin 18 Jahre alt
})();

Another option to temporary overwrite the default locale is to pass the locale as third argument to one of the helper or singleton methods:

import { useLanguage } from "ilingo";

(async () => {
    const language = useLanguage({
        locale: 'en'
    });

    let output = await language.get('app.age', {age: 18});
    console.log(output);
    // I am 18 yeas old

    output = await language.get('app.age', {age: 18}, 'fr');
    console.log(output);
    // J'ai 18 ans

    output = await lang('app.age', {age: 18}, 'de');
    console.log(output);
    // Ich bin 18 Jahre alt
})();

Async/Sync

Async

import { useLanguage } from "ilingo";

(async () => {
    console.log(await useLanguage().get('app.languageKey'));

    // lang is a helper function for fast access ;)
    console.log(await lang('app.languageKey'));
})();

Sync

import { useLanguage } from "ilingo";

console.log(useLanguage().getSync('app.languageKey'));

// lang is a helper function for fast access ;)
console.log(langSync('app.languageKey'));

Lazy

Another option is to either to not access the file system or add a few translations afterward.

import { useLanguage } from "ilingo";

(async () => {
    const language = useLanguage({
        locale: 'en'
    });

    language.set('foo.bar', 'baz {{param}}');
    language.set('foo.bar', 'boz {{param}}', 'de');

    let output = await language.get('foo.bar', {param: 'x'});
    console.log(output);
    // baz x

    output = await language.get('foo.bar', {param: 'y'}, 'de');
    console.log(output);
    // boz y
})();