@novigi/i18n

A versatile library for seamless string translation utilizing custom language files.

🐿 Features

• Translate a string word by word, providing a more granular level of translation.
• Translate a string as a whole sentence, preserving the sentence structure and context during translation.
• Flexibility to customize the translation process by providing customizable options.

📦 Getting Started

1. Install the dependency

npm install @novigi/i18n

2. Import the library

const lib = require('@novigi/i18n');

📖 Documentation

i18n

Represents an internationalization (i18n) module.

This library provides methods for translating a string using a JSON file that contains translated versions of words or sentences.

The language file should be a flat JSON file.

The content of the sample file used in the following usage example is as follows ( si-LK.json ) :

{
 "hello": "හෙලෝ",
 "world": "ලෝකය",
 "Hello World":"හෙලෝ ලෝකය"
}

Translation can be implemented as follows:

const I18n = require('@novigi/i18n')


const i18n = new I18n('/path/to/si-LK.json')

const translatedText = i18n.translate('Hello World')

console.log(translatedText);

const translatedSentence = i18n.translateBySentence('Hello World')

console.log(translatedSentence);

//"හෙලෝ ලෝකය"

//"හෙලෝ ලෝකය"

• i18n
  • ~I18n
    • new I18n(filePath, [options])
    • .translate ⇒ string
    • .translateBySentence ⇒ string

i18n~I18n

Represents an Internationalization (i18n) utility class for translating strings.

Kind: inner class of i18n

• ~I18n
  • new I18n(filePath, [options])
  • .translate ⇒ string
  • .translateBySentence ⇒ string

new I18n(filePath, [options])

Constructs a new instance of the I18n class.

Returns: I18n - A new instance of the I18n object.
Throws:

• I18nParameterError - When the filePath is not provided or an empty string.
• I18nParameterError - When the filePath is not an absolute path.

Param	Type	Default	Description
filePath	string		The file path of the translation source file.
[options]	object	{ removeUnavailable: false,removePunctuation: false,skip: [],defaultValue: null }	Optional parameters for customizing the translation.
[options.removeUnavailable]	boolean	false	Determines whether to remove or keep words that don't have a translation in the language file.
[options.removePunctuation]	boolean	false	Determines whether to remove or keep punctuation marks. Punctuation marks include: ! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` {
[options.skip]	Array.<string>	[]	An array of words that should be skipped during translation.
[options.defaultValue]	string	"''"	The default value to be returned when there is no mapping for a word.

Example

// Create an instance of I18n with the absolute source file path
const i18n = new I18n('/path/to/language-file.json')

// Create an instance of I18n with the absolute source file path and optional parameter options
const i18n = new I18n('/path/to/language-file.json', options)

i18n.translate ⇒ string

Translates the given text using the specified translation options.

Kind: instance property of I18n
Returns: string - The translated text.
Throws:

• I18nTranslateError - If the text is not a string.

Param	Type	Default	Description
text	string		The text to be translated.
[translateOptions]	object	{removeUnavailable: false,removePunctuation: false,skip: []}	The translation options specify the configuration settings for the translation process. These options are similar to the class-level options, but they are scoped to the functional level, providing flexibility for individual translation operations.
[options.removeUnavailable]	boolean	false	Determines whether to remove or keep words that don't have a translation in the language file.
[options.removePunctuation]	boolean	false	Determines whether to remove or keep punctuation marks. Punctuation marks include: ! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` {
[options.skip]	Array.<string>	[]	An array of words that should be skipped during translation.

Example

// Translate a string
const translatedText = i18n.translate('Hello')

// Translate a string with optional parameter options
const translatedText = i18n.translate('Hello', options)

i18n.translateBySentence ⇒ string

Translates a sentence using the provided translation dictionary.

Kind: instance property of I18n
Returns: string - The translated sentence if available in the dictionary, otherwise returns the original sentence or an empty string if the sentence is falsy.
Throws:

• I18nTranslateError When the sentence is not a string.

Param	Type	Description
sentence	string	The sentence to translate.

Example

// Translate a sentence
const translatedSentence = i18n.translateBySentence("Hello, how are you?");

This is an auto generated file. Please don't make changes manually