@gruvjs/i18n 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Saiteja Madha
+
+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,61 @@
+<div align="center">
+  <br />
+  <p>
+    <a href="https://github.com/gruvjs/gruvjs"><img src="https://raw.githubusercontent.com/gruvjs/gruvjs/main/assets/logo.svg" width="546" alt="gruvjs" /></a>
+  </p>
+  <br />
+  <p>
+    <a href="https://www.npmjs.com/package/@gruvjs/i18n"><img src="https://img.shields.io/npm/v/@gruvjs/i18n.svg?maxAge=3600" alt="npm version" /></a>
+    <a href="https://www.npmjs.com/package/@gruvjs/i18n"><img src="https://img.shields.io/npm/dt/@gruvjs/i18n.svg?maxAge=3600" alt="npm downloads" /></a>
+  </p>
+</div>
+
+## About
+
+`@gruvjs/i18n` is a lightweight i18n engine with dot-notation keys, interpolation, pluralization and fallback locale.
+
+Node.js 18.0.0 or newer is required.
+
+## Installation
+
+```sh
+npm install @gruvjs/i18n
+yarn add @gruvjs/i18n
+pnpm add @gruvjs/i18n
+```
+
+## Examples
+
+```js
+const { I18n, createT } = require("@gruvjs/i18n");
+
+const i18n = new I18n({ fallback: "en" });
+
+i18n.load("en", {
+  greet: "Hello, {{name}}!",
+  items: { one: "{{n}} item", other: "{{n}} items" },
+  commands: { ping: { reply: "Pong! Latency: {{ms}}ms" } },
+});
+
+i18n.load("pt", {
+  greet: "Olá, {{name}}!",
+  commands: { ping: { reply: "Pong! Latência: {{ms}}ms" } },
+});
+
+i18n.t("greet", "pt", { name: "Mundo" });          // → "Olá, Mundo!"
+i18n.t("commands.ping.reply", "pt", { ms: 42 });   // → "Pong! Latência: 42ms"
+i18n.t("items", "en", { n: 5 });                   // → "5 items"
+i18n.t("greet", "es", { name: "Mundo" });          // → "Hello, Mundo!" (fallback)
+
+// Pre-bound translator
+const t = createT(i18n, "pt");
+t("greet", { name: "Mundo" }); // → "Olá, Mundo!"
+```
+
+See the [docs](./docs) folder for detailed usage.
+
+## Links
+
+- [npm](https://www.npmjs.com/package/@gruvjs/i18n)
+- [GitHub](https://github.com/gruvjs/gruvjs/tree/main/packages/i18n)
+- [gruvjs monorepo](https://github.com/gruvjs/gruvjs)

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@gruvjs/i18n",
+  "version": "1.0.0",
+  "description": "Lightweight i18n engine with dot-notation keys, interpolation, pluralization and fallback locale.",
+  "main": "src/index.js",
+  "author": "gruvjs",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "i18n",
+    "internationalization",
+    "locale",
+    "translation",
+    "bot",
+    "zero-dependency"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gruvjs/gruvjs.git",
+    "directory": "packages/i18n"
+  },
+  "bugs": {
+    "url": "https://github.com/gruvjs/gruvjs/issues"
+  },
+  "homepage": "https://github.com/gruvjs/gruvjs/tree/main/packages/i18n#readme",
+  "files": [
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {},
+  "scripts": {
+    "test": "node tests/run.js"
+  }
+}

package/src/core/I18n.js

@@ -0,0 +1,66 @@
+/**
+ * I18n — Core translation engine.
+ * Handles locale loading, dot-notation key resolution, interpolation and pluralization.
+ */
+class I18n {
+  constructor(options = {}) {
+    this._fallback   = options.fallback ?? "en";
+    this._missingTpl = options.missing  ?? "__MISSING__{{key}}__";
+    this._locales    = new Map();
+  }
+
+  load(locale, messages) {
+    if (!locale || typeof locale !== "string") throw new TypeError("locale must be a non-empty string");
+    if (!messages || typeof messages !== "object") throw new TypeError("messages must be a plain object");
+    this._locales.set(locale, this._merge(this._locales.get(locale) ?? {}, messages));
+    return this;
+  }
+
+  t(key, locale, vars = {}) {
+    const raw = this._resolve(key, locale) ?? this._resolve(key, this._fallback);
+    if (raw === undefined) return this._interpolate(this._missingTpl, { key, ...vars });
+    return this._interpolate(this._pluralize(raw, vars), vars);
+  }
+
+  has(key, locale) {
+    return this._resolve(key, locale) !== undefined || this._resolve(key, this._fallback) !== undefined;
+  }
+
+  locales() { return [...this._locales.keys()]; }
+
+  _resolve(key, locale) {
+    const messages = this._locales.get(locale);
+    if (!messages) return undefined;
+    let node = messages;
+    for (const part of key.split(".")) {
+      if (node === null || typeof node !== "object" || !(part in node)) return undefined;
+      node = node[part];
+    }
+    return node;
+  }
+
+  _pluralize(raw, vars) {
+    if (typeof raw !== "object" || raw === null) return String(raw);
+    const n = Number(vars.n ?? vars.count ?? 1);
+    if (n === 0 && "zero" in raw) return raw.zero;
+    if (n === 1 && "one"  in raw) return raw.one;
+    return raw.other ?? raw.one ?? JSON.stringify(raw);
+  }
+
+  _interpolate(str, vars) {
+    if (!vars || typeof str !== "string") return str;
+    return str.replace(/\{\{(\w+)\}\}/g, (_, k) => (k in vars ? String(vars[k]) : `{{${k}}}`));
+  }
+
+  _merge(target, source) {
+    const out = { ...target };
+    for (const [k, v] of Object.entries(source)) {
+      out[k] = (v && typeof v === "object" && !Array.isArray(v) && typeof out[k] === "object")
+        ? this._merge(out[k], v)
+        : v;
+    }
+    return out;
+  }
+}
+
+module.exports = { I18n };

package/src/helpers/createT.js

@@ -0,0 +1,16 @@
+/**
+ * Creates a pre-bound translate function for a fixed locale.
+ *
+ * @param {import("../core/I18n").I18n} i18n
+ * @param {string} locale
+ * @returns {(key: string, vars?: object) => string}
+ *
+ * @example
+ *   const t = createT(i18n, "pt");
+ *   t("greet", { name: "Mundo" }); // → "Olá, Mundo!"
+ */
+function createT(i18n, locale) {
+  return (key, vars) => i18n.t(key, locale, vars);
+}
+
+module.exports = { createT };

package/src/index.js

@@ -0,0 +1,7 @@
+// Core
+const { I18n }    = require("./core/I18n");
+
+// Helpers
+const { createT } = require("./helpers/createT");
+
+module.exports = { I18n, createT };