@mikionatsu/t9n 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MikioNatsu
+
+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,99 @@
+# @mikionatsu/t9n
+
+Tiny translation toolkit for Node/JS + React.
+
+✅ Nested keys (`common.hello`)  
+✅ Interpolation (`"Salom, {name}!"`)  
+✅ Fallback locale  
+✅ Plural (`Intl.PluralRules`)  
+✅ React Provider + hooks (`@mikionatsu/t9n/react`)
+
+---
+
+## Install
+
+```bash
+npm i @mikionatsu/t9n
+```
+
+## Core usage (Node/JS)
+
+import { createT9n } from "@mikionatsu/t9n";
+
+const t9n = createT9n({
+locale: "uz",
+fallbackLocale: "en",
+resources: {
+uz: { common: { hello: "Salom, {name}!" } },
+en: { common: { hello: "Hello, {name}!" } }
+}
+});
+
+console.log(t9n.t("common.hello", { name: "Natsu" })); // Salom, Natsu!
+
+## Plural
+
+const t9n = createT9n({
+  locale: "en",
+  resources: {
+    en: { items: { one: "{count} item", other: "{count} items" } }
+  }
+});
+
+t9n.t("items", { count: 1 }); // 1 item
+t9n.t("items", { count: 5 }); // 5 items
+
+## React usage
+
+import { createT9n } from "@mikionatsu/t9n";
+
+export const t9n = createT9n({
+  locale: "uz",
+  fallbackLocale: "en",
+  resources: {
+    uz: {
+      common: { hello: "Salom, {name}!" }
+    },
+    en: {
+      common: { hello: "Hello, {name}!" }
+    }
+  }
+});
+
+## Provider 
+
+import React from "react";
+import ReactDOM from "react-dom/client";
+import App from "./App";
+import { T9nProvider } from "@mikionatsu/t9n/react";
+import { t9n } from "./i18n";
+
+ReactDOM.createRoot(document.getElementById("root")!).render(
+  <React.StrictMode>
+    <T9nProvider t9n={t9n} initialLocale="uz">
+      <App />
+    </T9nProvider>
+  </React.StrictMode>
+);
+
+
+## Hooks
+
+import React from "react";
+import { useT, useLocale } from "@mikionatsu/t9n/react";
+
+export function Header() {
+  const t = useT();
+  const { locale, setLocale } = useLocale();
+
+  return (
+    <div>
+      <h1>{t("common.hello", { name: "Natsu" })}</h1>
+
+      <select value={locale} onChange={(e) => setLocale(e.target.value)}>
+        <option value="uz">uz</option>
+        <option value="en">en</option>
+      </select>
+    </div>
+  );
+}

package/dist/index.cjs

@@ -0,0 +1,78 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  createT9n: () => createT9n
+});
+module.exports = __toCommonJS(index_exports);
+function getByPath(obj, path) {
+  return path.split(".").reduce((acc, k) => acc == null ? void 0 : acc[k], obj);
+}
+function interpolate(s, vars) {
+  return s.replace(/\{(\w+)\}/g, (_, k) => {
+    const v = vars[k];
+    return v === void 0 || v === null ? "" : String(v);
+  });
+}
+function deepMerge(a, b) {
+  if (Array.isArray(a) || Array.isArray(b)) return b;
+  if (!a || typeof a !== "object") return b;
+  if (!b || typeof b !== "object") return b;
+  const out = { ...a };
+  for (const k of Object.keys(b)) {
+    out[k] = k in out ? deepMerge(out[k], b[k]) : b[k];
+  }
+  return out;
+}
+function pickPluralKey(locale, count) {
+  return new Intl.PluralRules(locale).select(count);
+}
+function createT9n(opts) {
+  let locale = opts.locale;
+  const fallbackLocale = opts.fallbackLocale ?? "en";
+  const resources = { ...opts.resources ?? {} };
+  function setLocale(l) {
+    locale = l;
+  }
+  function getLocale() {
+    return locale;
+  }
+  function addResources(l, dict) {
+    resources[l] = resources[l] ? deepMerge(resources[l], dict) : dict;
+  }
+  function t(key, vars = {}) {
+    let val = getByPath(resources[locale], key);
+    if (val === void 0) val = getByPath(resources[fallbackLocale], key);
+    if (val === void 0) return key;
+    if (typeof val === "object" && val && typeof vars.count === "number") {
+      const pk = pickPluralKey(locale, vars.count);
+      const msg = val[pk] ?? val.other;
+      if (typeof msg === "string") return interpolate(msg, vars);
+    }
+    if (typeof val === "string") return interpolate(val, vars);
+    return String(val);
+  }
+  return { t, setLocale, getLocale, addResources };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createT9n
+});

package/dist/index.d.cts

@@ -0,0 +1,16 @@
+type Dict = Record<string, any>;
+type CreateT9nOptions = {
+    locale: string;
+    fallbackLocale?: string;
+    resources?: Record<string, Dict>;
+};
+type T9n = ReturnType<typeof createT9n>;
+type Vars = Record<string, any>;
+declare function createT9n(opts: CreateT9nOptions): {
+    t: (key: string, vars?: Vars) => string;
+    setLocale: (l: string) => void;
+    getLocale: () => string;
+    addResources: (l: string, dict: Dict) => void;
+};
+
+export { type CreateT9nOptions, type Dict, type T9n, createT9n };

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+type Dict = Record<string, any>;
+type CreateT9nOptions = {
+    locale: string;
+    fallbackLocale?: string;
+    resources?: Record<string, Dict>;
+};
+type T9n = ReturnType<typeof createT9n>;
+type Vars = Record<string, any>;
+declare function createT9n(opts: CreateT9nOptions): {
+    t: (key: string, vars?: Vars) => string;
+    setLocale: (l: string) => void;
+    getLocale: () => string;
+    addResources: (l: string, dict: Dict) => void;
+};
+
+export { type CreateT9nOptions, type Dict, type T9n, createT9n };

package/dist/index.js

@@ -0,0 +1,53 @@
+// src/index.ts
+function getByPath(obj, path) {
+  return path.split(".").reduce((acc, k) => acc == null ? void 0 : acc[k], obj);
+}
+function interpolate(s, vars) {
+  return s.replace(/\{(\w+)\}/g, (_, k) => {
+    const v = vars[k];
+    return v === void 0 || v === null ? "" : String(v);
+  });
+}
+function deepMerge(a, b) {
+  if (Array.isArray(a) || Array.isArray(b)) return b;
+  if (!a || typeof a !== "object") return b;
+  if (!b || typeof b !== "object") return b;
+  const out = { ...a };
+  for (const k of Object.keys(b)) {
+    out[k] = k in out ? deepMerge(out[k], b[k]) : b[k];
+  }
+  return out;
+}
+function pickPluralKey(locale, count) {
+  return new Intl.PluralRules(locale).select(count);
+}
+function createT9n(opts) {
+  let locale = opts.locale;
+  const fallbackLocale = opts.fallbackLocale ?? "en";
+  const resources = { ...opts.resources ?? {} };
+  function setLocale(l) {
+    locale = l;
+  }
+  function getLocale() {
+    return locale;
+  }
+  function addResources(l, dict) {
+    resources[l] = resources[l] ? deepMerge(resources[l], dict) : dict;
+  }
+  function t(key, vars = {}) {
+    let val = getByPath(resources[locale], key);
+    if (val === void 0) val = getByPath(resources[fallbackLocale], key);
+    if (val === void 0) return key;
+    if (typeof val === "object" && val && typeof vars.count === "number") {
+      const pk = pickPluralKey(locale, vars.count);
+      const msg = val[pk] ?? val.other;
+      if (typeof msg === "string") return interpolate(msg, vars);
+    }
+    if (typeof val === "string") return interpolate(val, vars);
+    return String(val);
+  }
+  return { t, setLocale, getLocale, addResources };
+}
+export {
+  createT9n
+};

package/dist/react.cjs

@@ -0,0 +1,77 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/react.tsx
+var react_exports = {};
+__export(react_exports, {
+  T9nProvider: () => T9nProvider,
+  useLocale: () => useLocale,
+  useT: () => useT,
+  useT9n: () => useT9n
+});
+module.exports = __toCommonJS(react_exports);
+var import_react = require("react");
+var import_jsx_runtime = require("react/jsx-runtime");
+var T9nContext = (0, import_react.createContext)(null);
+function T9nProvider(props) {
+  const { t9n } = props;
+  const [locale, _setLocale] = (0, import_react.useState)(() => props.initialLocale ?? t9n.getLocale());
+  const setLocale = (0, import_react.useCallback)(
+    (l) => {
+      t9n.setLocale(l);
+      _setLocale(l);
+    },
+    [t9n]
+  );
+  const addResources = (0, import_react.useCallback)(
+    (l, dict) => {
+      t9n.addResources(l, dict);
+      _setLocale((x) => x);
+    },
+    [t9n]
+  );
+  const t = (0, import_react.useCallback)((key, vars) => t9n.t(key, vars), [t9n]);
+  const value = (0, import_react.useMemo)(
+    () => ({ t9n, locale, setLocale, t, addResources }),
+    [t9n, locale, setLocale, t, addResources]
+  );
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(T9nContext.Provider, { value, children: props.children });
+}
+function useT() {
+  const ctx = (0, import_react.useContext)(T9nContext);
+  if (!ctx) throw new Error("useT must be used inside <T9nProvider />");
+  return ctx.t;
+}
+function useLocale() {
+  const ctx = (0, import_react.useContext)(T9nContext);
+  if (!ctx) throw new Error("useLocale must be used inside <T9nProvider />");
+  return { locale: ctx.locale, setLocale: ctx.setLocale };
+}
+function useT9n() {
+  const ctx = (0, import_react.useContext)(T9nContext);
+  if (!ctx) throw new Error("useT9n must be used inside <T9nProvider />");
+  return ctx;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  T9nProvider,
+  useLocale,
+  useT,
+  useT9n
+});

package/dist/react.d.cts

@@ -0,0 +1,24 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import { T9n, Dict } from './index.cjs';
+
+type T9nContextValue = {
+    t9n: T9n;
+    locale: string;
+    setLocale: (locale: string) => void;
+    t: (key: string, vars?: Record<string, any>) => string;
+    addResources: (locale: string, dict: Dict) => void;
+};
+declare function T9nProvider(props: {
+    t9n: T9n;
+    initialLocale?: string;
+    children: ReactNode;
+}): react_jsx_runtime.JSX.Element;
+declare function useT(): (key: string, vars?: Record<string, any>) => string;
+declare function useLocale(): {
+    locale: string;
+    setLocale: (locale: string) => void;
+};
+declare function useT9n(): T9nContextValue;
+
+export { T9nProvider, useLocale, useT, useT9n };

package/dist/react.d.ts

@@ -0,0 +1,24 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import { T9n, Dict } from './index.js';
+
+type T9nContextValue = {
+    t9n: T9n;
+    locale: string;
+    setLocale: (locale: string) => void;
+    t: (key: string, vars?: Record<string, any>) => string;
+    addResources: (locale: string, dict: Dict) => void;
+};
+declare function T9nProvider(props: {
+    t9n: T9n;
+    initialLocale?: string;
+    children: ReactNode;
+}): react_jsx_runtime.JSX.Element;
+declare function useT(): (key: string, vars?: Record<string, any>) => string;
+declare function useLocale(): {
+    locale: string;
+    setLocale: (locale: string) => void;
+};
+declare function useT9n(): T9nContextValue;
+
+export { T9nProvider, useLocale, useT, useT9n };

package/dist/react.js

@@ -0,0 +1,49 @@
+// src/react.tsx
+import { createContext, useCallback, useContext, useMemo, useState } from "react";
+import { jsx } from "react/jsx-runtime";
+var T9nContext = createContext(null);
+function T9nProvider(props) {
+  const { t9n } = props;
+  const [locale, _setLocale] = useState(() => props.initialLocale ?? t9n.getLocale());
+  const setLocale = useCallback(
+    (l) => {
+      t9n.setLocale(l);
+      _setLocale(l);
+    },
+    [t9n]
+  );
+  const addResources = useCallback(
+    (l, dict) => {
+      t9n.addResources(l, dict);
+      _setLocale((x) => x);
+    },
+    [t9n]
+  );
+  const t = useCallback((key, vars) => t9n.t(key, vars), [t9n]);
+  const value = useMemo(
+    () => ({ t9n, locale, setLocale, t, addResources }),
+    [t9n, locale, setLocale, t, addResources]
+  );
+  return /* @__PURE__ */ jsx(T9nContext.Provider, { value, children: props.children });
+}
+function useT() {
+  const ctx = useContext(T9nContext);
+  if (!ctx) throw new Error("useT must be used inside <T9nProvider />");
+  return ctx.t;
+}
+function useLocale() {
+  const ctx = useContext(T9nContext);
+  if (!ctx) throw new Error("useLocale must be used inside <T9nProvider />");
+  return { locale: ctx.locale, setLocale: ctx.setLocale };
+}
+function useT9n() {
+  const ctx = useContext(T9nContext);
+  if (!ctx) throw new Error("useT9n must be used inside <T9nProvider />");
+  return ctx;
+}
+export {
+  T9nProvider,
+  useLocale,
+  useT,
+  useT9n
+};

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@mikionatsu/t9n",
+  "version": "0.1.0",
+  "description": "Tiny translation toolkit (nested keys, interpolation, plural, React hooks).",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js",
+      "require": "./dist/react.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "build": "tsup src/index.ts src/react.tsx --format esm,cjs --dts --clean",
+    "prepublishOnly": "npm run build && vitest run"
+  },
+  "peerDependencies": {
+    "react": ">=17",
+    "react-dom": ">=17"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^4.0.0"
+  },
+  "keywords": [
+    "t9n",
+    "i18n",
+    "translation",
+    "locale",
+    "react"
+  ],
+  "license": "MIT"
+}