ilingo 💬

Ilingo is a lightweight library for translation and internationalization.

Table of Contents

• Installation
• Configuration
• Usage
  • Basic
  • Singleton
  • Parameters
  • Locales
  • Lazy
• Store
  • Memory
  • FileSystem
• License

Installation

npm install ilingo --save

Configuration

While full localization of an application is a complex subject, swapping out strings in your application for different supported languages/locales is simple. The different locale strings for translation are provided by interacting with the library class instance.

Usage

Basic

Create an instance and set the default locale.

import { Ilingo } from 'ilingo';

const ilingo = new Ilingo({
    locale: 'en'
})

The default (memory-) store can be initialized with some default data.

import { Ilingo } from 'ilingo';

const store = new MemoryStore({
    data: {
        // locale: de
        de: {
            // group: app
            app: {
                key: 'Hallo mein Name ist {{name}}'
            }
        },
        // locale: en
        en: {
            app: {
                key: 'Hello my name is {{name}}'
            }
        },
    }
});

const ilingo = new Ilingo({
    store,
    locale: 'en'
});

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

After that you can simply access the locale string, as described in the following:

import { Ilingo } from 'ilingo';

const ilingo = new Ilingo({
    // ...
});

await ilingo.get({
    group: 'app',
    key: 'key'
});
// Hello my name is {{name}}

await ilingo.get({
    group: 'app',
    key: 'key',
    data: {
        name: 'Peter'
    }
});
// Hello my name is Peter

await ilingo.get({
    group: 'app',
    key: 'key',
    data: {
        name: 'Peter'
    },
    locale: 'de'
});
// Hallo mein Name ist Peter

Parameters

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

import { Ilingo, MemoryStore } from 'ilingo';

const ilingo = new Ilingo({
    store: new MemoryStore({
        data: {
            en: {
                app: {
                    age: 'I am {{age}} years old.'
                }
            }
        }
    })
});

await ilingo.get({
    group: 'app',
    key: 'age',
    data: {
        age: 18
    }
});
// I am 18 yeas old

Locales

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

import { Ilingo } from 'ilingo';

const ilingo = new Ilingo({
    // ...
});

await ilingo.get({
    group: 'app',
    key: 'age',
    data: {
        age: 18
    }
});
// I am 18 yeas old

ilingo.setLocale('de');

await ilingo.get({
    group: 'app',
    key: 'age',
    data: {
        age: 18
    }
});
// Ich bin 18 Jahre alt

It also can be temporarily overwritten, by passing the locale as the third argument to one of the helper or supported singleton methods:

import { Ilingo } from 'ilingo';

const ilingo = new Ilingo({
    // ...
});

await ilingo.get({
    group: 'app',
    key: 'age',
    data: {
        age: 18
    }
});
// I am 18 yeas old

await ilingo.get({
    group: 'app',
    key: 'age',
    data: {
        age: 18
    },
    locale: 'fr'
});
// J'ai 18 ans

await ilingo.get({
    group: 'app',
    key: 'age',
    data: {
        age: 18
    },
    locale: 'de'
});
// Ich bin 18 Jahre alt

Lazy

Another option is to add translations on the fly and access them afterwards.

import { Ilingo, MemoryStore } from 'ilingo';

const ilingo = new Ilingo({
    store: new MemoryStore({
        data: {
            en: {
                foo: {
                    bar: 'baz {{param}}'
                }
            },
            de: {
                foo: {
                    bar: 'boz {{param}}'
                }
            }
        }
    })
});

await ilingo.get({
    group: 'foo',
    key: 'bar',
    data: {
        param: 'x'
    }
});
// baz x

await ilingo.get({
    group: 'foo',
    key: 'bar',
    data: {
        param: 'y'
    },
    locale: 'de'
});
// boz y

Store

Memory Store

The Memory Store is the default store and is set if no other Store is specified manually.

FS Store

The FSStore is a Store which access the FileSystem for locating group files of different locales.

License

Made with 💚

Published under MIT License.