@xxanderwp/translate-module 1.0.0

package/.github/workflows/deploy.yml

@@ -0,0 +1,64 @@
+name: Publish npm Package
+
+on:
+  push:
+    branches: [main, beta]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: 20
+          registry-url: https://registry.npmjs.org/
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build package
+        run: npm run build
+
+      - name: Check if version exists on npm
+        id: check_version
+        run: |
+          PACKAGE_NAME=$(node -p "require('./package.json').name")
+          PACKAGE_VERSION=$(node -p "require('./package.json').version")
+          echo "Package: $PACKAGE_NAME"
+          echo "Version: $PACKAGE_VERSION"
+
+          # Проверяем, есть ли уже такая версия на npm
+          if npm view "$PACKAGE_NAME@$PACKAGE_VERSION" >/dev/null 2>&1; then
+            echo "Version $PACKAGE_VERSION already exists on npm"
+            echo "exists=true" >> $GITHUB_OUTPUT
+          else
+            echo "Version $PACKAGE_VERSION is new"
+            echo "exists=false" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Publish to npm (latest)
+        if: steps.check_version.outputs.exists == 'false' && github.ref == 'refs/heads/main'
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: |
+          npm publish --access=public
+
+      - name: Mark existing version as latest
+        if: steps.check_version.outputs.exists == 'true' && github.ref == 'refs/heads/main'
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: |
+          PACKAGE_NAME=$(node -p "require('./package.json').name")
+          PACKAGE_VERSION=$(node -p "require('./package.json').version")
+          npm dist-tag add "$PACKAGE_NAME@$PACKAGE_VERSION" latest
+    
+      - name: Publish to npm (beta)
+        if: steps.check_version.outputs.exists == 'false' && github.ref == 'refs/heads/beta'
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: |
+          npm publish --tag beta --access=public

package/.github/workflows/test.yml

@@ -0,0 +1,46 @@
+name: Tests
+
+on:
+  push:
+    branches: [develop]
+  pull_request:
+    branches: [main, beta, develop]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [16.x, 18.x, 20.x, 22.x]
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v3
+        with:
+          node-version: ${{ matrix.node-version }}
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run linter
+        run: npm run lint
+
+      - name: Run tests
+        run: npm test
+
+      - name: Run coverage
+        run: npm run test:coverage
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v3
+        if: matrix.node-version == '22.x'
+        with:
+          file: ./coverage/lcov.info
+          flags: unittests
+          name: codecov-umbrella
+
+      - name: Build
+        run: npm run build

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 XXanderWP
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,129 @@
+<div align="center">
+  <img src="./logo.png" alt="translate-module logo" width="320" />
+
+  [![npm version](https://img.shields.io/npm/v/@xxanderwp/translate-module?style=flat-square&color=4f46e5)](https://www.npmjs.com/package/@xxanderwp/translate-module)
+  [![npm downloads](https://img.shields.io/npm/dw/@xxanderwp/translate-module?style=flat-square&color=7c3aed)](https://www.npmjs.com/package/@xxanderwp/translate-module)
+  [![Publish npm Package](https://img.shields.io/github/actions/workflow/status/XXanderWP/LangModule/deploy.yml?branch=main&style=flat-square&label=publish&logo=github)](https://github.com/XXanderWP/LangModule/actions/workflows/deploy.yml)
+  [![License: MIT](https://img.shields.io/npm/l/@xxanderwp/translate-module?style=flat-square)](LICENSE)
+  [![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178c6?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+</div>
+
+# @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}`, ...)
+- Zero runtime dependencies
+
+## Installation
+
+```bash
+npm install @xxanderwp/translate-module
+```
+
+## Usage
+
+### Basic setup
+
+```ts
+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
+
+```ts
+lang.currentLanguage = "es";
+lang.translate("greeting", "Alice"); // "¡Hola, Alice!"
+```
+
+### Accessing available languages
+
+```ts
+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 `null` if the key does not exist or no language is set.
+
+---
+
+### `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, or `null` if none is set.
+
+## Development
+
+**Build**
+
+```bash
+npm run build
+```
+
+**Run tests**
+
+```bash
+npm test
+```
+
+**Run tests with coverage**
+
+```bash
+npm run test:coverage
+```
+
+## License
+
+[MIT](LICENSE)

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export declare class LanguageCore<T extends Record<string, Record<string, string>>, LangKey extends keyof T = keyof T> {
+    private readonly _languages_data;
+    private _currentLanguage;
+    constructor(data: T, defaultLanguage?: keyof T);
+    get languagesData(): T;
+    get currentLanguage(): LangKey | null;
+    set currentLanguage(lang: LangKey);
+    get langKeys(): LangKey[];
+    get currentLanguageData(): T[LangKey] | null;
+    translate<K extends keyof T[LangKey]>(key: K, ...args: (string | number)[]): string | null;
+}

package/dist/index.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LanguageCore = void 0;
+class LanguageCore {
+    constructor(data, defaultLanguage) {
+        this._currentLanguage = null;
+        if (Object.keys(data).length === 0) {
+            throw new Error("Languages data cannot be empty.");
+        }
+        this._languages_data = data;
+        if (defaultLanguage) {
+            if (!this.langKeys.includes(defaultLanguage)) {
+                throw new Error(`Default language ${String(defaultLanguage)} is not supported.`);
+            }
+            this._currentLanguage = defaultLanguage;
+        }
+        else {
+            this._currentLanguage = Object.keys(data)[0];
+        }
+    }
+    get languagesData() {
+        return this._languages_data;
+    }
+    get currentLanguage() {
+        return this._currentLanguage;
+    }
+    set currentLanguage(lang) {
+        if (!this.langKeys.includes(lang)) {
+            throw new Error(`Language ${String(lang)} is not supported.`);
+        }
+        this._currentLanguage = lang;
+    }
+    get langKeys() {
+        return Object.keys(this._languages_data);
+    }
+    get currentLanguageData() {
+        if (!this._currentLanguage)
+            return null;
+        return this._languages_data[this._currentLanguage];
+    }
+    translate(key, ...args) {
+        if (!this._currentLanguage)
+            return null;
+        const langData = this._languages_data[this._currentLanguage];
+        let res = langData[key];
+        args.forEach((arg, index) => {
+            res = res.replace(new RegExp(`\\{${index}\\}`, "g"), String(arg));
+        });
+        return res || null;
+    }
+}
+exports.LanguageCore = LanguageCore;

package/jest.config.js

@@ -0,0 +1,30 @@
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  roots: ['<rootDir>/src', '<rootDir>/tests'],
+  testMatch: ['**/__tests__/**/*.ts', '**/?(*.)+(spec|test).ts'],
+  testTimeout: 10000,
+  collectCoverageFrom: [
+    'src/**/*.ts',
+    '!src/**/*.d.ts',
+    '!src/**/*.test.ts',
+    '!src/**/*.spec.ts',
+  ],
+  coverageThreshold: {
+    global: {
+      branches: 50,
+      functions: 50,
+      lines: 50,
+      statements: 50,
+    },
+  },
+  moduleFileExtensions: ['ts', 'js', 'json'],
+  transform: {
+    '^.+\\.ts$': [
+      'ts-jest',
+      {
+        tsconfig: 'tsconfig.test.json',
+      },
+    ],
+  },
+};

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@xxanderwp/translate-module",
+  "version": "1.0.0",
+  "description": "",
+  "main": "dist/index.js",
+  "directories": {
+    "test": "tests"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test:coverage": "jest --coverage",
+    "test": "jest"
+  },
+  "author": "XXanderWP",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/XXanderWP/LangModule.git"
+  },
+  "bugs": {
+    "url": "https://github.com/XXanderWP/LangModule/issues"
+  },
+  "homepage": "https://github.com/XXanderWP/LangModule#readme",
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "jest": "^30.4.2",
+    "ts-jest": "^29.4.11",
+    "ts-loader": "^9.6.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,64 @@
+export class LanguageCore<
+  T extends Record<string, Record<string, string>>,
+  LangKey extends keyof T = keyof T
+> {
+  private readonly _languages_data: T;
+  private _currentLanguage: LangKey | null = null;
+
+  constructor(data: T, defaultLanguage?: keyof T) {
+    if (Object.keys(data).length === 0) {
+      throw new Error("Languages data cannot be empty.");
+    }
+
+    this._languages_data = data;
+    if(defaultLanguage) {
+        if (!this.langKeys.includes(defaultLanguage as LangKey)) {
+            throw new Error(`Default language ${String(defaultLanguage)} is not supported.`);
+        }
+        this._currentLanguage = defaultLanguage as LangKey;
+    } else {
+        this._currentLanguage = Object.keys(data)[0] as LangKey;
+    }
+  }
+
+  get languagesData(): T {
+    return this._languages_data;
+  }
+
+  get currentLanguage(): LangKey | null {
+    return this._currentLanguage;
+  }
+
+  set currentLanguage(lang: LangKey) {
+    if (!this.langKeys.includes(lang)) {
+      throw new Error(`Language ${String(lang)} is not supported.`);
+    }
+    this._currentLanguage = lang;
+  }
+
+  get langKeys(): LangKey[] {
+    return Object.keys(this._languages_data) as LangKey[];
+  }
+
+  get currentLanguageData(): T[LangKey] | null {
+    if (!this._currentLanguage) return null;
+    return this._languages_data[this._currentLanguage];
+  }
+
+  translate<K extends keyof T[LangKey]>(
+  key: K,
+  ...args: (string | number)[]
+): string | null {
+    if (!this._currentLanguage) return null;
+
+    const langData = this._languages_data[this._currentLanguage];
+    let res = langData[key] as string;
+
+    args.forEach((arg, index) => {
+      res = res.replace(new RegExp(`\\{${index}\\}`, "g"), String(arg));
+    });
+
+    return res || null;
+  }
+}
+

package/tests/index.test.ts

@@ -0,0 +1,79 @@
+import { describe, it, expect } from "@jest/globals";
+import { LanguageCore } from "../src/index";
+
+describe("LangModule", () => {
+  it("should initialize with valid data and default language", () => {
+    const data = {
+      en: { greeting: "Hello" },
+      es: { greeting: "Hola" },
+    };
+    const langModule = new LanguageCore(data, "es");
+    expect(langModule.languagesData).toEqual(data);
+    expect(langModule.currentLanguage).toBe("es");
+  });
+
+  it("should throw an error if initialized with empty data", () => {
+    expect(() => new LanguageCore({})).toThrow("Languages data cannot be empty.");
+  });
+
+  it("should throw an error if default language is not supported", () => {
+    const data = {
+      en: { greeting: "Hello" },
+      es: { greeting: "Hola" },
+    };
+    // @ts-ignore
+    expect(() => new LanguageCore(data, "fr")).toThrow("Default language fr is not supported.");
+  });
+
+  it("should return the correct translation for the current language", () => {
+    const data = {
+      en: { greeting: "Hello, {0}!" },
+      es: { greeting: "¡Hola, {0}!" },
+    };
+    const langModule = new LanguageCore(data, "en");
+    expect(langModule.translate("greeting", "John")).toBe("Hello, John!");
+    langModule.currentLanguage = "es";
+    expect(langModule.translate("greeting", "John")).toBe("¡Hola, John!");
+  });
+
+  it("should throw an error when setting an unsupported language", () => {
+    const data = {
+      en: { greeting: "Hello" },
+      es: { greeting: "Hola" },
+    };
+    const langModule = new LanguageCore(data);
+    // @ts-ignore
+    expect(() => (langModule.currentLanguage = "fr")).toThrow("Language fr is not supported.");
+  });
+
+  it("should return null for translation if current language is not set", () => {
+    const data = {
+      en: { greeting: "Hello" },
+      es: { greeting: "Hola" },
+    };
+    const langModule = new LanguageCore(data);
+    // @ts-ignore
+    expect(() => (langModule.currentLanguage = null)).toThrow("Language null is not supported.");
+  });
+
+  it("should return null for translation if key does not exist", () => {
+    const data = {
+      en: { greeting: "Hello" },
+      es: { greeting: "Hola" },
+    };
+    const langModule = new LanguageCore(data);
+    // @ts-ignore
+    expect(langModule.translate("farewell")).toBeNull();
+  });
+
+  it("should return the correct language keys", () => {
+    const data = {
+      en: { greeting: "Hello" },
+      es: { greeting: "Hola" },
+    };
+    const langModule = new LanguageCore(data);
+    expect(langModule.langKeys).toEqual(["en", "es"]);
+  });
+
+
+});

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "declaration": true,
+    "target": "ES2020",
+    "module": "CommonJS",
+    "lib": ["ES2020", "DOM"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "types": ["node"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/tsconfig.test.json

@@ -0,0 +1,11 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist-tests",
+    "rootDir": ".",
+    "noEmit": true,
+    "types": ["node", "jest"]
+  },
+  "include": ["src/**/*", "tests/**/*"],
+  "exclude": ["node_modules", "dist"]
+}