Xxanderwp Translate Module

https://github.com/xxanderwp/langmodule
Admin
A lightweight, type-safe TypeScript module for managing multi-language translations with support for...
Tokens:1,770
Snippets:27
Trust Score:6.2
License:MIT
Update:4 months ago
Show doc for...
Tokens:
Raw
### Basic Setup and Translation

Source: https://github.com/xxanderwp/langmodule/blob/main/README.md

Initialize the LanguageCore with translations and a default language. Use the translate method to get localized strings with interpolation.

```typescript
import { LanguageCore } from "@xxanderwp/translate-module";

const translations = {
  en: {
    greeting: "Hello, {0}!",
    farewell: "Goodbye!",
  },
  es: {
    greeting: "¡Hola, {0}!",
    farewell: "¡Adiós!",
  },
};

const lang = new LanguageCore(translations, "en");

lang.translate("greeting", "Alice"); // "Hello, Alice!"
```

--------------------------------

### Install @xxanderwp/translate-module

Source: https://github.com/xxanderwp/langmodule/blob/main/README.md

Install the module using npm. This is the first step before using the translation functionalities.

```bash
npm install @xxanderwp/translate-module
```

--------------------------------

### Adding a New Language at Runtime

Source: https://github.com/xxanderwp/langmodule/blob/main/README.md

Install a new language dynamically after the module has been initialized. The new language data must contain exactly the same keys as existing languages.

```typescript
lang.InstallNewLanguage("fr", {
  greeting: "Bonjour, {0}!",
  farewell: "Au revoir!",
});

lang.currentLanguage = "fr";
lang.translate("greeting", "Alice"); // "Bonjour, Alice!"
```

--------------------------------

### currentLanguage Getter/Setter

Source: https://github.com/xxanderwp/langmodule/blob/main/README.md

Allows getting or setting the active language key. Setting an unsupported language key will result in an error.

```APIDOC
## `currentLanguage` *(getter / setter)*

### Description
Gets or sets the active language key. Setting an unsupported key throws an error.

### Parameters
#### Path Parameters
- **currentLanguage** (string) - Required - The language key to set.
```

--------------------------------

### Run Tests with Coverage

Source: https://github.com/xxanderwp/langmodule/blob/main/README.md

Run the test suite and generate a code coverage report.

```bash
npm run test:coverage
```

--------------------------------

### Run Tests

Source: https://github.com/xxanderwp/langmodule/blob/main/README.md

Execute the test suite to ensure the module functions as expected.

```bash
npm test
```

--------------------------------

### Build Project

Source: https://github.com/xxanderwp/langmodule/blob/main/README.md

Execute the build script to compile the TypeScript code into JavaScript.

```bash
npm run build
```

--------------------------------

### InstallNewLanguage Method

Source: https://github.com/xxanderwp/langmodule/blob/main/README.md

Adds a new language and its translations to the module at runtime. It enforces that the new language must have the exact same set of translation keys as existing languages and that the language key must be unique.

```APIDOC
## `InstallNewLanguage(langKey, langData)`

### Description
Adds a new language dictionary to the existing translations at runtime.

### Parameters
#### Path Parameters
- **langKey** (`string`) - Required - The language key to add (for example, `fr`).
- **langData** (`Record<string, string>`) - Required - Translation dictionary for the new language. Must match existing keys exactly.

### Throws
Throws if:
- `langKey` already exists.
- `langData` does not contain exactly the same translation keys as existing languages.
```

--------------------------------

### LanguageCore Constructor

Source: https://github.com/xxanderwp/langmodule/blob/main/README.md

Initializes a new instance of the LanguageCore class. It takes a translations object and an optional default language. It throws an error if the provided data is empty or the default language is invalid.

```APIDOC
## `new LanguageCore(data, defaultLanguage?)`

### Description
Initializes a new instance of the LanguageCore class.

### Parameters
#### Path Parameters
- **data** (T) - Required - An object mapping language keys to their translation dictionaries.
- **defaultLanguage** (keyof T) - Optional - The language to activate on construction. Defaults to the first key in `data`.

### Throws
Throws if `data` is empty or `defaultLanguage` is not a key of `data`.
```

--------------------------------

### langKeys Getter

Source: https://github.com/xxanderwp/langmodule/blob/main/README.md

Provides an array of all available language keys within the module.

```APIDOC
## `langKeys`

### Description
Returns an array of all available language keys.

### Returns
- `string[]` - An array of available language keys.
```

--------------------------------

### translate Method

Source: https://github.com/xxanderwp/langmodule/blob/main/README.md

Translates a given key to the current language, supporting interpolation with indexed placeholders.

```APIDOC
## `translate(key, ...args)`

### Description
Returns the translated string for `key` in the current language, with `{0}`, `{1}`, ... placeholders replaced by the provided `args`.

Returns the key itself as a string if the translation is missing.

### Parameters
#### Path Parameters
- **key** (string) - Required - The translation key to look up.
- **args** (...any) - Optional - Arguments to replace placeholders in the translation string.
```

--------------------------------

### Registering Language Change Listener

Source: https://github.com/xxanderwp/langmodule/blob/main/README.md

Set up a callback function to be executed whenever the current language is changed. Remember to call the returned unregister function to remove the listener when it's no longer needed.

```typescript
const unregister = lang.onChangeLanguage(() => {
  console.log("Language changed to:", lang.currentLanguage);
});

// Later, to stop listening:
unregister();
```

--------------------------------

### onChangeLanguage Method

Source: https://github.com/xxanderwp/langmodule/blob/main/README.md

Registers a callback function to be executed whenever the active language changes. It returns a function to unregister the listener.

```APIDOC
## `onChangeLanguage(cb)`

### Description
Registers a callback to be invoked whenever the active language changes. Returns an unregister function — call it to remove the listener.

### Parameters
#### Path Parameters
- **cb** (`() => void`) - Required - The callback function to execute when the language changes.

### Returns
- `() => void` - A function that can be called to unregister the listener.
```

--------------------------------

### Accessing Available Language Keys

Source: https://github.com/xxanderwp/langmodule/blob/main/README.md

Retrieve an array of all language keys that have been loaded into the module.

```typescript
lang.langKeys; // ["en", "es"]
```

--------------------------------

### currentLanguageData Getter

Source: https://github.com/xxanderwp/langmodule/blob/main/README.md

Returns the translation dictionary corresponding to the currently active language.

```APIDOC
## `currentLanguageData`

### Description
Returns the translation dictionary for the currently active language.

### Returns
- `Record<string, string>` - The translation dictionary for the current language.
```

--------------------------------

### languagesData Getter

Source: https://github.com/xxanderwp/langmodule/blob/main/README.md

Retrieves the complete translations object that was initially passed to the constructor.

```APIDOC
## `languagesData`

### Description
Returns the full translations object passed to the constructor.

### Returns
- `T` - The complete translations object.
```

--------------------------------

### Switching Current Language

Source: https://github.com/xxanderwp/langmodule/blob/main/README.md

Change the active language at runtime by setting the currentLanguage property. Translations will immediately reflect the new language.

```typescript
lang.currentLanguage = "es";
lang.translate("greeting", "Alice"); // "¡Hola, Alice!"
```
Tokens:
Raw