npm package: @novigi/i18n
Description: A versatile library for seamless string translation utilizing custom language files.
Author: Novigi
Latest version: 1.0.0-1

![npm (scoped)](https://img.shields.io/npm/v/@novigi/i18n) ![NPM](https://img.shields.io/npm/l/@novigi/i18n) ![Statements](https://img.shields.io/badge/statements-100%25-brightgreen.svg?style=flat) ![Branches](https://img.shields.io/badge/branches-100%25-brightgreen.svg?style=flat) ![Functions](https://img.shields.io/badge/functions-100%25-brightgreen.svg?style=flat) ![Lines](https://img.shields.io/badge/lines-100%25-brightgreen.svg?style=flat)
# @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

<a name="module_i18n"></a>

## 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* ) :

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

Translation can be implemented as follows:

```js
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](#module_i18n)
    * [~I18n](#module_i18n..I18n)
        * [new I18n(filePath, [options])](#new_module_i18n..I18n_new)
        * [.translate](#module_i18n..I18n+translate) ⇒ <code>string</code>
        * [.translateBySentence](#module_i18n..I18n+translateBySentence) ⇒ <code>string</code>

<a name="module_i18n..I18n"></a>

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

**Kind**: inner class of [<code>i18n</code>](#module_i18n)  

* [~I18n](#module_i18n..I18n)
    * [new I18n(filePath, [options])](#new_module_i18n..I18n_new)
    * [.translate](#module_i18n..I18n+translate) ⇒ <code>string</code>
    * [.translateBySentence](#module_i18n..I18n+translateBySentence) ⇒ <code>string</code>

<a name="new_module_i18n..I18n_new"></a>

#### new I18n(filePath, [options])
Constructs a new instance of the I18n class.

**Returns**: <code>I18n</code> - A new instance of the `I18n` object.  
**Throws**:

- <code>I18nParameterError</code> - When the filePath is not provided or an empty string.
- <code>I18nParameterError</code> - When the filePath is not an absolute path.


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

**Example**  
```js
// 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)
```
<a name="module_i18n..I18n+translate"></a>

#### i18n.translate ⇒ <code>string</code>
Translates the given text using the specified translation options.

**Kind**: instance property of [<code>I18n</code>](#module_i18n..I18n)  
**Returns**: <code>string</code> - The translated text.  
**Throws**:

- <code>I18nTranslateError</code> - If the text is not a string.


| Param | Type | Default | Description |
| --- | --- | --- | --- |
| text | <code>string</code> |  | The text to be translated. |
| [translateOptions] | <code>object</code> | <code>{removeUnavailable: false,removePunctuation: false,skip: []}</code> | 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] | <code>boolean</code> | <code>false</code> | Determines whether to remove or keep words that don't have a translation in the language file. |
| [options.removePunctuation] | <code>boolean</code> | <code>false</code> | Determines whether to remove or keep punctuation marks. Punctuation marks include: ! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { | } ~ |
| [options.skip] | <code>Array.&lt;string&gt;</code> | <code>[]</code> | An array of words that should be skipped during translation. |

**Example**  
```js
// Translate a string
const translatedText = i18n.translate('Hello')

// Translate a string with optional parameter options
const translatedText = i18n.translate('Hello', options)
```
<a name="module_i18n..I18n+translateBySentence"></a>

#### i18n.translateBySentence ⇒ <code>string</code>
Translates a sentence using the provided translation dictionary.

**Kind**: instance property of [<code>I18n</code>](#module_i18n..I18n)  
**Returns**: <code>string</code> - The translated sentence if available in the dictionary, otherwise returns
the original sentence or an empty string if the sentence is falsy.  
**Throws**:

- <code>I18nTranslateError</code> When the sentence is not a string.


| Param | Type | Description |
| --- | --- | --- |
| sentence | <code>string</code> | The sentence to translate. |

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

_This is an auto generated file. Please don't make changes manually_