@xxanderwp/translate-module

A lightweight, type-safe TypeScript module for managing multi-language translations with support for interpolation placeholders.

Features

• Full TypeScript generic type safety — language keys and translation keys are statically inferred
• Runtime language switching via a simple setter
• String interpolation with indexed placeholders ({0}, {1}, ...)
• Language change listeners with automatic unregister support
• Zero runtime dependencies

Installation

npm install @xxanderwp/translate-module

Usage

Basic setup

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!"

Switching language

lang.currentLanguage = "es";
lang.translate("greeting", "Alice"); // "¡Hola, Alice!"

Accessing available languages

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

API

new LanguageCore(data, defaultLanguage?)

Parameter	Type	Description
data	T	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 if data is empty or defaultLanguage is not a key of data.

---

translate(key, ...args)

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.

---

currentLanguage (getter / setter)

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

---

langKeys

Returns an array of all available language keys.

---

languagesData

Returns the full translations object passed to the constructor.

---

currentLanguageData

Returns the translation dictionary for the currently active language.

---

onChangeLanguage(cb)

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

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

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

Development

Build

npm run build

Run tests

npm test

Run tests with coverage

npm run test:coverage

License

MIT