localizationservice v1.1.0

localizationservice

The simple localization service

Also there is localizationkeys-webpack that generates typescript class of localization keys. See https://github.com/ripenko/localizationkeys-webpack.

Installation

npm install --save localizationservice

Usage

Simple usage

method localize

import LocalizationService from "localizationservice";

const defaultLanguage = {
    "Key1": "Value 1",
    "Key2": {
        "Key21": "Value 21"
    }
};

const service = new LocalizationService({
    importedLanguages: {
        [LocalizationService.DEFAULT_CULTURE_NAME]: defaultLanguage
    },
    currentLanguage: defaultLanguage
});

const localized: string = service.localize("Key2.Key21");
console.log(localized);  // "Value 21"

Example. The facade pattern with event bus integration

The events bus is eventservice. See https://github.com/ripenko/eventservice

There are two localization files default.jsonc and de-de.json. To generate localization keys from default.jsonc file we can use webpack plugin https://github.com/ripenko/localizationkeys-webpack.

The Localization.ts file in your app.

import LocalizationService from "localizationservice";
import EventService from "eventservice";

export default class Localization {
       
    private static service: LocalizationService | null = null;

    public static localize<T = string>(key: string, ...formatArgs: string[]): T {
        if (Localization.service == null) initService();
        return Localization.service.localize(key, formatArgs);
    }

    private static initService(): void {
        const defaultLanguage = require("localization/default.jsonc");
        const germanLanguage = require("localization/de-de.jsonc");
        Localization.service = new LocalizationService({
            importedLanguages: {
                [LocalizationService.DEFAULT_CULTURE_NAME]: defaultLanguage,
                "de-de": germanLanguage
            },
            onLanguageChanged: (languageName: string, language: ILocalizationLanguage): Promise<void> => {
                // we can notify subscribers that the current language has been changed.
                // if we use momentjs then we can change locale by `moment.locale(languageName);`
                // or numeraljs, etc...
                return EventService.fire("Events.Localization.LanguageChanged", { name: languageName, langauge: language });
            },
            onLanguageImported: (languageName: string, language: ILocalizationLanguage): Promise<void> => {
                // we can load language from api or some another place async to import it by `service.importLanguage` method
                // when new language will be imported we can update UI by refreshing a list of available languages
                return EventService.fire("Events.Localization.LanguageImported", { name: languageName, langauge: language });
            },
            onLocalizationMissing: (key: string, _languageName: string, _language: ILocalizationLanguage | null, _formatArgs: string[]): string => {
                // When localization has been not found in current language we return just key. 
                // The testers could find easy such unlocalizated places.
                // Or we can notify insights about missing values.
                // Or we can try to get value from default language.
                // Or write in the console, etc...
                return key;
            }
        });
    }

}

Return localized object instead of certain string

Method localize. By default return type of method localize<T = string> is string. If we pass a localization key that point doesn't point to string, but it points to the parent nested object, then localized result will be object. Typically usecases:

• dynamic key. if localization key is computed
• localized object should be passed to some component. (Example: Globalization, or localization of some Telerik control)

import LocalizationService from "localizationservice";

interface IFeatureString {
    Title: string;
    Description: string;
}

const defaultLanguage = {
    "Feature": {
        "Title": "Some Title",
        "Description": "Some Description"
    }
};

const service = new LocalizationService({
    importedLanguages: {
        [LocalizationService.DEFAULT_CULTURE_NAME]: defaultLanguage
    },
    currentLanguage: defaultLanguage
});

const result: IFeatureString = service.localize<IFeatureString>("Feature");
console.log(result); // -> { Title: "Some Title", Description: "Some Description" }

Changing the current language

method changeLanguage

import LocalizationService from "localizationservice";

const defaultLanguage = {
    "Key1": "Value 1",
    "Key2": {
        "Key21": "Value 21"
    }
};

const germanLanguage = {
    "Key1": "Wert 1",
    "Key2": {
        "Key21": "Wert 21"
    }
}

const service = new LocalizationService({
    importedLanguages: {
        [LocalizationService.DEFAULT_CULTURE_NAME]: defaultLanguage,
        "de-de": germanLanguage
    },
    currentLanguage: defaultLanguage
});

await service.changeLanguage("de-DE"); // language name case will be lowered => de-de

const localized: string = service.localize("Key2.Key21");
console.log(localized);  // "Wert 21"

Using onChangeLanguage handler. When the current language has been changed

method changeLanguage and constructor options property onChangeLanguage.

import LocalizationService from "localizationservice";

const defaultLanguage = {
    "Key1": "Value 1",
    "Key2": {
        "Key21": "Value 21"
    }
};

const germanLanguage = {
    "Key1": "Wert 1",
    "Key2": {
        "Key21": "Wert 21"
    }
}

const service = new LocalizationService({
    importedLanguages: {
        [LocalizationService.DEFAULT_CULTURE_NAME]: defaultLanguage,
        "de-de": germanLanguage
    },
    currentLanguage: defaultLanguage,
    onChangeLanguage: async (languageName: string, language: ILocalizationLanguage | null): Promise<void> => {
        console.info(languageName, language);
    }
});

await service.changeLanguage("de-DE"); // language name case will be lowered => de-de
// -> de-de { Key1: "Wert 1", Key2: { Key21: "Wert 21" } }

Importing new language using language property __cultureName__

method importLanguage.

import LocalizationService from "localizationservice";

const defaultLanguage = {
    "Key1": "Value 1",
    "Key2": {
        "Key21": "Value 21"
    }
};

const germanLanguage = {
    __cultureName__: "de-de",
    "Key1": "Wert 1",
    "Key2": {
        "Key21": "Wert 21"
    }
}

const service = new LocalizationService({
    importedLanguages: {
        [LocalizationService.DEFAULT_CULTURE_NAME]: defaultLanguage
    },
    currentLanguage: defaultLanguage
});

// `__cultureName__` of `germanLanguage` will be used to definde language name
// The method doesn't change the current language. See `changeLanguage`.
// The language name detection priority is language property `__cultureName__`, 
// if there is no, then parameter `name`. If the parameter `name` is undefined,
// then `LocalizationService.DEFAULT_CULTURE_NAME`
await service.importLanguage(germanLanguage);

const localized: string = service.localize("Key2.Key21");
console.log(localized);  // "Value 21"

Importing new language using optional method parameter name

method importLanguage.

import LocalizationService from "localizationservice";

const defaultLanguage = {
    "Key1": "Value 1",
    "Key2": {
        "Key21": "Value 21"
    }
};

const germanLanguage = {
    "Key1": "Wert 1",
    "Key2": {
        "Key21": "Wert 21"
    }
}

const service = new LocalizationService({
    importedLanguages: {
        [LocalizationService.DEFAULT_CULTURE_NAME]: defaultLanguage
    },
    currentLanguage: defaultLanguage
});

// There is no `__cultureName__` of `germanLanguage`, 
// then parameter `name` will be used to definde language name `de-de` (case will be lowered).
// The method doesn't change the current language. See `changeLanguage`.
await service.importLanguage(germanLanguage, "de-DE");

const localized: string = service.localize("Key2.Key21");
console.log(localized);  // "Value 21"

Importing new default language

method importLanguage.

import LocalizationService from "localizationservice";

const defaultLanguage = {
    "Key1": "Value 1",
    "Key2": {
        "Key21": "Value 21"
    }
};

const germanLanguage = {
    "Key1": "Wert 1",
    "Key2": {
        "Key21": "Wert 21"
    }
}

const service = new LocalizationService({
    importedLanguages: {
        [LocalizationService.DEFAULT_CULTURE_NAME]: defaultLanguage
    },
    currentLanguage: defaultLanguage
});

// `__cultureName__` of `germanLanguage` will be used to definde language name
// The method doesn't change the current language. See `changeLanguage`.
await service.importLanguage(germanLanguage);

// To apply updated language you have to refresh current language
await service.changeLanguage();

const localized: string = service.localize("Key2.Key21");
console.log(localized);  // "Wert 21"

Using on onLanguageImported handler. When the language has been imported.

constructor option onLanguageImported or property onLanguageImported.

import LocalizationService from "localizationservice";

const defaultLanguage = {
    "Key1": "Value 1",
    "Key2": {
        "Key21": "Value 21"
    }
};

const service = new LocalizationService({
    onLanguageImported: async (name: string, language: ILocalizationLanguage): Promise<void> => {
        console.log(name, language);
    }
});

// `__cultureName__` of `defaultLanguage` will be used to definde language name
// The method doesn't change the current language. See `changeLanguage`.
await service.importLanguage(defaultLanguage);
// -> "" { Key1: "Value 1", Key2: { Key21: "Value 21" } }

Using on onLocalizationMissing handler. When localization string has been not found

constructor option onLocalizationMissing or property onLocalizationMissing.

import LocalizationService from "localizationservice";

const service = new LocalizationService({
    // name will be `LocalizationService.DEFAULT_CULTURE_NAME`, language is `{}`
    onLocalizationMissing: (key: string, name: string, language: ILocalizationLanguage): string => {
        return `Missed '${key}' for default language`;
    }
});

const result: string = service.localize("SomeKey");
console.log(result); // -> "Missed 'SomeKey' for default language"

Credits

Alexey Ripenko, GitHub

License

MIT