super-simple-i18n

Simple, lightweight, and easy to use, i18n translation for Node.js for non-production purposes. It supports replacement variables and pluralization.

Key features

• Default Locale - using the default locale as a fallback
• Fallback - returning specified string in case of any critical error
• Pluralization - plural key selection, based on Intl.PluralRules
• Replacement Parameters - supporting replaceable text through named parameters and consistent replacement
• Non-throwing errors - non-disruptive compilation errors
• Silent mode - hiding any warning and errors in the console
• Functions or Classes - choose any style of using you need or like

Getting started

Install the package: npm i super-simple-i18n

// Functions
import { t } from "super-simple-i18n"
// or
import { translate } from "super-simple-i18n"

// Classes
import { T } from "super-simple-i18n"
// or
import { Translate } from "super-simple-i18n"

Options

• locale : string - an active locale, required
• defaultLocale : string - fallback for the active locale
• content : { [propName: string]: any } - dictionaries with translations, required
• plural : string | number | undefined - a pluralisaiton option
• replacements : string[] | { [propName: string]: string } | undefined - replacement options
• fallback : string | undefined - a string returned in case of errors
• silent : boolean - hiding alerts in the console

Functions

// Full set of options

t("project.key", {
    locale: 'fr-FR',
    defaultLocale: 'en-EN',
    content: {
        'en-EN': {
            'project.key': 'Hello world!'
        },
        'fr-FR': {
            'project.key': 'Bonjour le monde !'
        }
    },
    plural: undefined,
    replacements: undefined,
    fallback: 'Hello world!',
    silent: false
})
// -> 'Bonjour le monde !'

// Minimum set of options

t("project.key", {
    locale: 'fr-FR',
    content: {
        'en-EN': {
            'project.key': 'Hello world!'
        },
        'fr-FR': {
            'project.key': 'Bonjour le monde !'
        }
    }
})
// -> 'Bonjour le monde !'

Classes

// Full set of options

let TClass = T("project.key", {
    locale: 'fr-FR',
    defaultLocale: 'en-EN',
    content: {
        'en-EN': {
            'project.key': 'Hello world!'
        },
        'fr-FR': {
            'project.key': 'Bonjour le monde !'
        }
    },
    plural: undefined,
    replacements: undefined,
    fallback: 'Hello world!',
    silent: false
}) // Translation class ititilization

TClass.format() 
// The format() method returns the translated string 
// -> 'Bonjour le monde !'

// Minimum set of options

t("project.key", {
    locale: 'fr-FR',
    content: {
        'en-EN': {
            'project.key': 'Hello world!'
        },
        'fr-FR': {
            'project.key': 'Bonjour le monde !'
        }
    }
}).format()
// -> 'Bonjour le monde !'

Examples

const settings = {
    locale: "en-EN",
    defaultLocale: "en-EN",
    content: {
        "en-EN": {
            string: "Hello world!",
            nested: {
                string: "Hello world!",
                plural: {
                    regular: {
                        one: "Apple!",
                        other: "Apples!",
                    },
                    replace: {
                        array: {
                            one: "Hello %@!",
                            other: "Hello %@ and %@!",
                        },
                        template: {
                            one: "Hello {{name_1}}!",
                            other: "Hello {{name_2}} and {{name_1}}!",
                        }
                    },
                },
                replace: {
                    array: "Hello %d and %d!",
                    template: "Hello {{name_2}} and {{name_1}}!"
                },
            },
        },
        "fr-FR": {
            greetings: "Bonjour!"
        }
    },
}



// Basic

t("string", { ...settings })
// -> 'Hello world!'

t("nested.string", { ...settings })
// -> 'Hello world!'



// Pluralization and replacement

t("nested.plural.regular", {
    ...settings,
    plural: 2
}),
// -> 'Apples!'

t("nested.plural.replace.array", {
    ...settings,
    plural: 2,
    replacements: ["James", "Kate"]
})
// -> 'Hello James and Kate!'

t("nested.plural.replace.template", {
    ...settings,
    plural: 2,
    replacements: {
        name_1: "James",
        name_2: "Kate"
    }
})
// -> 'Hello Kate and James!'

t("nested.replace.array", {
    ...settings,
    replacements: ["James", "Kate"]
})
// -> 'Hello James and Kate!'

t("nested.replace.template", {
    ...settings,
    replacements: {
        name_1: "James",
        name_2: "Kate"
    }
})
// -> 'Hello Kate and James!'


// Fallbacks

t("string", {
    locale: "fr-FR",
    defaultLocale: "en-EN",
    content: settings.content
})
// -> 'Hello world!'

t("something", {
    locale: "fr-FR",
    defaultLocale: "en-EN",
    content: settings.content,
    fallback: "ERR"
})
// -> 'ERR'

Changelog

• 1.0.3: Class usage
• 1.0.2: Refactoring and fixes
• 1.0.1: DefaultLocale as fallback bugfix
• 1.0.0: Initial stable release