@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