@yaebal/i18n 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 neverlane
+
+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,15 @@
+# @yaebal/i18n
+
+a plural form set keyed by `Intl.PluralRules` categories. `other` is required
+as the fallback; the rest are optional and selected per locale via
+`new Intl.PluralRules(locale).select(n)`.
+
+## install
+
+```sh
+pnpm add @yaebal/i18n
+```
+
+---
+
+part of [**yaebal**](https://github.com/neverlane/yaebal) — a type-safe, runtime-agnostic Telegram Bot API framework. MIT.

package/lib/index.d.ts

@@ -0,0 +1,44 @@
+import type { Context, Plugin } from "@yaebal/core";
+import { type StorageAdapter } from "@yaebal/session";
+/**
+ * a plural form set keyed by `Intl.PluralRules` categories. `other` is required
+ * as the fallback; the rest are optional and selected per locale via
+ * `new Intl.PluralRules(locale).select(n)`.
+ */
+export interface PluralDict {
+    zero?: string;
+    one?: string;
+    two?: string;
+    few?: string;
+    many?: string;
+    other: string;
+}
+/** a single translation value: a plain template or a set of plural forms. */
+export type DictValue = string | PluralDict;
+/**
+ * a translation table: key → template (with `{placeholder}` interpolation), or
+ * key → plural forms (selected by `{n}` via `Intl.PluralRules`).
+ */
+export type Dict = Record<string, DictValue>;
+export type TFn = (key: string, params?: Record<string, unknown>) => string;
+/** what the plugin adds to the context. powers morda/jsx `useTranslation`. */
+export interface I18nControls {
+    t: TFn;
+    locale: string;
+    changeLanguage(locale: string): Promise<void>;
+}
+export interface I18nOptions<L extends string> {
+    defaultLocale: L;
+    locales: Record<L, Dict>;
+    /** where to persist each chat's locale. defaults to in-memory. */
+    storage?: StorageAdapter<string>;
+    /** locale key for an update. default: per-chat (`ctx.chat.id`). */
+    getKey?: (ctx: Context) => string | undefined;
+}
+/**
+ * i18n plugin. adds `ctx.t` / `ctx.locale` / `ctx.changeLanguage`, with the
+ * active locale persisted per chat. missing keys fall back to the default
+ * locale, then to the key itself.
+ */
+export declare function i18n<L extends string>(options: I18nOptions<L>): Plugin<Context, I18nControls>;
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EAAiB,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAErE;;;;GAIG;AACH,MAAM,WAAW,UAAU;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACd;AAED,6EAA6E;AAC7E,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,UAAU,CAAC;AAE5C;;;GAGG;AACH,MAAM,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;AAE7C,MAAM,MAAM,GAAG,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,CAAC;AAE5E,8EAA8E;AAC9E,MAAM,WAAW,YAAY;IAC5B,CAAC,EAAE,GAAG,CAAC;IACP,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9C;AAED,MAAM,WAAW,WAAW,CAAC,CAAC,SAAS,MAAM;IAC5C,aAAa,EAAE,CAAC,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;IACzB,kEAAkE;IAClE,OAAO,CAAC,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;IACjC,mEAAmE;IACnE,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,MAAM,GAAG,SAAS,CAAC;CAC9C;AAED;;;;GAIG;AACH,wBAAgB,IAAI,CAAC,CAAC,SAAS,MAAM,EAAE,OAAO,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,OAAO,EAAE,YAAY,CAAC,CAyC7F"}

package/lib/index.js

@@ -0,0 +1,41 @@
+import { MemoryStorage } from "@yaebal/session";
+/**
+ * i18n plugin. adds `ctx.t` / `ctx.locale` / `ctx.changeLanguage`, with the
+ * active locale persisted per chat. missing keys fall back to the default
+ * locale, then to the key itself.
+ */
+export function i18n(options) {
+    const { defaultLocale, locales } = options;
+    const storage = options.storage ?? new MemoryStorage();
+    const getKey = options.getKey ?? ((ctx) => ctx.chat?.id?.toString());
+    return (composer) => composer.derive(async (ctx) => {
+        const key = getKey(ctx);
+        let locale = (key !== undefined ? await storage.get(key) : undefined) ?? defaultLocale;
+        const t = (k, params) => {
+            const def = locales[defaultLocale] ?? {};
+            const dict = locales[locale] ?? def;
+            const raw = dict[k] ?? def[k] ?? k;
+            let s;
+            if (typeof raw === "string") {
+                s = raw;
+            }
+            else {
+                const n = params?.n;
+                const category = typeof n === "number" ? new Intl.PluralRules(locale).select(n) : "other";
+                s = raw[category] ?? raw.other;
+            }
+            if (params) {
+                for (const [pk, pv] of Object.entries(params))
+                    s = s.replaceAll(`{${pk}}`, String(pv));
+            }
+            return s;
+        };
+        const changeLanguage = async (next) => {
+            locale = next;
+            if (key !== undefined)
+                await storage.set(key, next);
+        };
+        return { t, locale, changeLanguage };
+    });
+}
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAuB,MAAM,iBAAiB,CAAC;AA2CrE;;;;GAIG;AACH,MAAM,UAAU,IAAI,CAAmB,OAAuB;IAC7D,MAAM,EAAE,aAAa,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;IAE3C,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,IAAI,aAAa,EAAU,CAAC;IAC/D,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC,CAAC,GAAY,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC;IAE9E,OAAO,CAAC,QAAQ,EAAE,EAAE,CACnB,QAAQ,CAAC,MAAM,CAAC,KAAK,EAAE,GAAG,EAAyB,EAAE;QACpD,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QACxB,IAAI,MAAM,GACT,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,aAAa,CAAC;QAE3E,MAAM,CAAC,GAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE;YAC5B,MAAM,GAAG,GAAS,OAAO,CAAC,aAAa,CAAC,IAAI,EAAE,CAAC;YAC/C,MAAM,IAAI,GAAS,OAAO,CAAC,MAAW,CAAC,IAAI,GAAG,CAAC;YAC/C,MAAM,GAAG,GAAc,IAAI,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;YAE9C,IAAI,CAAS,CAAC;YACd,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;gBAC7B,CAAC,GAAG,GAAG,CAAC;YACT,CAAC;iBAAM,CAAC;gBACP,MAAM,CAAC,GAAG,MAAM,EAAE,CAAC,CAAC;gBACpB,MAAM,QAAQ,GAAG,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;gBAE1F,CAAC,GAAG,GAAG,CAAC,QAA4B,CAAC,IAAI,GAAG,CAAC,KAAK,CAAC;YACpD,CAAC;YAED,IAAI,MAAM,EAAE,CAAC;gBACZ,KAAK,MAAM,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC;oBAAE,CAAC,GAAG,CAAC,CAAC,UAAU,CAAC,IAAI,EAAE,GAAG,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC;YACxF,CAAC;YAED,OAAO,CAAC,CAAC;QACV,CAAC,CAAC;QAEF,MAAM,cAAc,GAAG,KAAK,EAAE,IAAY,EAAiB,EAAE;YAC5D,MAAM,GAAG,IAAI,CAAC;YACd,IAAI,GAAG,KAAK,SAAS;gBAAE,MAAM,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QACrD,CAAC,CAAC;QAEF,OAAO,EAAE,CAAC,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC;IACtC,CAAC,CAAC,CAAC;AACL,CAAC"}

package/lib/index.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.test.d.ts.map

package/lib/index.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.test.d.ts","sourceRoot":"","sources":["../src/index.test.ts"],"names":[],"mappings":""}

package/lib/index.test.js

@@ -0,0 +1,154 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { Composer, Context } from "@yaebal/core";
+import { MemoryStorage } from "@yaebal/session";
+import { i18n } from "./index.js";
+const noop = async () => { };
+const entry = (c) => c.toMiddleware();
+const api = {};
+const ctxFor = (chatId) => new Context({
+    api,
+    update: {
+        update_id: 1,
+        message: {
+            message_id: 1,
+            date: 0,
+            chat: { id: chatId, type: "private" },
+            from: { id: chatId, is_bot: false, first_name: "u" },
+            text: "hi",
+        },
+    },
+    updateType: "message",
+});
+const locales = {
+    en: {
+        hi: "Hello {name}",
+        bye: "Bye",
+        items: { one: "{n} item", other: "{n} items" },
+    },
+    ru: {
+        hi: "Привет {name}",
+        items: {
+            one: "{n} предмет",
+            few: "{n} предмета",
+            many: "{n} предметов",
+            other: "{n} предмета",
+        },
+    },
+};
+test("t interpolates params and falls back to the key", async () => {
+    let hi = "";
+    let missing = "";
+    const c = new Composer()
+        .install(i18n({ defaultLocale: "en", locales }))
+        .use((ctx, next) => {
+        hi = ctx.t("hi", { name: "Sam" });
+        missing = ctx.t("nope");
+        return next();
+    });
+    await entry(c)(ctxFor(1), noop);
+    assert.equal(hi, "Hello Sam");
+    assert.equal(missing, "nope");
+});
+test("changeLanguage switches the active locale within the handler", async () => {
+    let after = "";
+    const c = new Composer()
+        .install(i18n({ defaultLocale: "en", locales }))
+        .use(async (ctx, next) => {
+        await ctx.changeLanguage("ru");
+        after = ctx.t("hi", { name: "Х" });
+        return next();
+    });
+    await entry(c)(ctxFor(2), noop);
+    assert.equal(after, "Привет Х");
+});
+test("locale persists per chat across updates", async () => {
+    const storage = new MemoryStorage();
+    let seen = "";
+    const c = new Composer()
+        .install(i18n({ defaultLocale: "en", locales, storage }))
+        .use(async (ctx, next) => {
+        const x = ctx;
+        if (x.t("hi", { name: "a" }) === "Hello a")
+            await x.changeLanguage("ru");
+        seen = x.locale;
+        return next();
+    });
+    const mw = entry(c);
+    await mw(ctxFor(3), noop); // en → switches to ru
+    await mw(ctxFor(3), noop); // loads ru
+    assert.equal(seen, "ru");
+});
+test("plural selection follows the locale's Intl.PluralRules (en)", async () => {
+    let one = "";
+    let other = "";
+    const c = new Composer()
+        .install(i18n({ defaultLocale: "en", locales }))
+        .use((ctx, next) => {
+        const x = ctx;
+        one = x.t("items", { n: 1 });
+        other = x.t("items", { n: 2 });
+        return next();
+    });
+    await entry(c)(ctxFor(10), noop);
+    assert.equal(one, "1 item"); // en: 1 → one
+    assert.equal(other, "2 items"); // en: 2 → other
+});
+test("plural selection follows the locale's Intl.PluralRules (ru)", async () => {
+    let one = "";
+    let few = "";
+    let many = "";
+    const c = new Composer()
+        .install(i18n({ defaultLocale: "en", locales }))
+        .use(async (ctx, next) => {
+        const x = ctx;
+        await x.changeLanguage("ru");
+        one = x.t("items", { n: 1 });
+        few = x.t("items", { n: 2 });
+        many = x.t("items", { n: 5 });
+        return next();
+    });
+    await entry(c)(ctxFor(11), noop);
+    assert.equal(one, "1 предмет"); // ru: 1 → one
+    assert.equal(few, "2 предмета"); // ru: 2 → few
+    assert.equal(many, "5 предметов"); // ru: 5 → many
+});
+test("plain-string keys keep working alongside plural objects (regression)", async () => {
+    let hi = "";
+    let bye = "";
+    const c = new Composer()
+        .install(i18n({ defaultLocale: "en", locales }))
+        .use((ctx, next) => {
+        const x = ctx;
+        hi = x.t("hi", { name: "Sam" }); // interpolated plain string
+        bye = x.t("bye"); // bare plain string
+        return next();
+    });
+    await entry(c)(ctxFor(12), noop);
+    assert.equal(hi, "Hello Sam");
+    assert.equal(bye, "Bye");
+});
+test("interpolation works inside a chosen plural form", async () => {
+    let s = "";
+    const c = new Composer()
+        .install(i18n({ defaultLocale: "en", locales }))
+        .use((ctx, next) => {
+        s = ctx.t("items", { n: 42 });
+        return next();
+    });
+    await entry(c)(ctxFor(13), noop);
+    assert.equal(s, "42 items"); // 42 → other, {n} interpolated
+});
+test("missing key in a locale falls back to the default locale", async () => {
+    let bye = "";
+    const c = new Composer()
+        .install(i18n({ defaultLocale: "en", locales }))
+        .use(async (ctx, next) => {
+        await ctx.changeLanguage("ru"); // ru has no "bye"
+        bye = ctx.t("bye");
+        return next();
+    });
+    await entry(c)(ctxFor(4), noop);
+    assert.equal(bye, "Bye"); // fell back to en
+});
+//# sourceMappingURL=index.test.js.map

package/lib/index.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.test.js","sourceRoot":"","sources":["../src/index.test.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@yaebal/i18n",
+  "version": "0.0.1",
+  "description": "yaebal i18n plugin — per-chat locale, ctx.t / ctx.changeLanguage (powers useTranslation).",
+  "type": "module",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.js"
+    }
+  },
+  "files": [
+    "lib",
+    "src"
+  ],
+  "dependencies": {
+    "@yaebal/core": "0.0.1",
+    "@yaebal/session": "0.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "latest"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "telegram",
+    "telegram-bot",
+    "yaebal",
+    "i18n",
+    "localization"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/neverlane/yaebal",
+    "directory": "packages/i18n"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --test lib"
+  }
+}

package/src/index.test.ts

@@ -0,0 +1,199 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { Composer, Context, type Middleware } from "@yaebal/core";
+import { MemoryStorage } from "@yaebal/session";
+import { type I18nControls, i18n } from "./index.js";
+
+const noop = async () => {};
+const entry = <C extends Context>(c: Composer<C>) =>
+	c.toMiddleware() as unknown as Middleware<Context>;
+
+const api = {} as never;
+const ctxFor = (chatId: number) =>
+	new Context({
+		api,
+		update: {
+			update_id: 1,
+			message: {
+				message_id: 1,
+				date: 0,
+				chat: { id: chatId, type: "private" },
+				from: { id: chatId, is_bot: false, first_name: "u" },
+				text: "hi",
+			},
+		} as never,
+		updateType: "message",
+	});
+
+const locales = {
+	en: {
+		hi: "Hello {name}",
+		bye: "Bye",
+		items: { one: "{n} item", other: "{n} items" },
+	},
+	ru: {
+		hi: "Привет {name}",
+		items: {
+			one: "{n} предмет",
+			few: "{n} предмета",
+			many: "{n} предметов",
+			other: "{n} предмета",
+		},
+	},
+};
+
+type Ctx = Context & I18nControls;
+
+test("t interpolates params and falls back to the key", async () => {
+	let hi = "";
+	let missing = "";
+
+	const c = new Composer<Context>()
+		.install(i18n({ defaultLocale: "en", locales }))
+		.use((ctx, next) => {
+			hi = (ctx as Ctx).t("hi", { name: "Sam" });
+			missing = (ctx as Ctx).t("nope");
+
+			return next();
+		});
+
+	await entry(c)(ctxFor(1), noop);
+
+	assert.equal(hi, "Hello Sam");
+	assert.equal(missing, "nope");
+});
+
+test("changeLanguage switches the active locale within the handler", async () => {
+	let after = "";
+
+	const c = new Composer<Context>()
+		.install(i18n({ defaultLocale: "en", locales }))
+		.use(async (ctx, next) => {
+			await (ctx as Ctx).changeLanguage("ru");
+
+			after = (ctx as Ctx).t("hi", { name: "Х" });
+			return next();
+		});
+
+	await entry(c)(ctxFor(2), noop);
+
+	assert.equal(after, "Привет Х");
+});
+
+test("locale persists per chat across updates", async () => {
+	const storage = new MemoryStorage<string>();
+
+	let seen = "";
+
+	const c = new Composer<Context>()
+		.install(i18n({ defaultLocale: "en", locales, storage }))
+		.use(async (ctx, next) => {
+			const x = ctx as Ctx;
+
+			if (x.t("hi", { name: "a" }) === "Hello a") await x.changeLanguage("ru");
+
+			seen = x.locale;
+			return next();
+		});
+
+	const mw = entry(c);
+	await mw(ctxFor(3), noop); // en → switches to ru
+	await mw(ctxFor(3), noop); // loads ru
+
+	assert.equal(seen, "ru");
+});
+
+test("plural selection follows the locale's Intl.PluralRules (en)", async () => {
+	let one = "";
+	let other = "";
+
+	const c = new Composer<Context>()
+		.install(i18n({ defaultLocale: "en", locales }))
+		.use((ctx, next) => {
+			const x = ctx as Ctx;
+
+			one = x.t("items", { n: 1 });
+			other = x.t("items", { n: 2 });
+
+			return next();
+		});
+
+	await entry(c)(ctxFor(10), noop);
+	assert.equal(one, "1 item"); // en: 1 → one
+	assert.equal(other, "2 items"); // en: 2 → other
+});
+
+test("plural selection follows the locale's Intl.PluralRules (ru)", async () => {
+	let one = "";
+	let few = "";
+	let many = "";
+	const c = new Composer<Context>()
+		.install(i18n({ defaultLocale: "en", locales }))
+		.use(async (ctx, next) => {
+			const x = ctx as Ctx;
+			await x.changeLanguage("ru");
+
+			one = x.t("items", { n: 1 });
+			few = x.t("items", { n: 2 });
+			many = x.t("items", { n: 5 });
+
+			return next();
+		});
+	
+	await entry(c)(ctxFor(11), noop);
+
+	assert.equal(one, "1 предмет"); // ru: 1 → one
+	assert.equal(few, "2 предмета"); // ru: 2 → few
+	assert.equal(many, "5 предметов"); // ru: 5 → many
+});
+
+test("plain-string keys keep working alongside plural objects (regression)", async () => {
+	let hi = "";
+	let bye = "";
+
+	const c = new Composer<Context>()
+		.install(i18n({ defaultLocale: "en", locales }))
+		.use((ctx, next) => {
+			const x = ctx as Ctx;
+
+			hi = x.t("hi", { name: "Sam" }); // interpolated plain string
+			bye = x.t("bye"); // bare plain string
+
+			return next();
+		});
+	
+	await entry(c)(ctxFor(12), noop);
+	assert.equal(hi, "Hello Sam");
+	assert.equal(bye, "Bye");
+});
+
+test("interpolation works inside a chosen plural form", async () => {
+	let s = "";
+
+	const c = new Composer<Context>()
+		.install(i18n({ defaultLocale: "en", locales }))
+		.use((ctx, next) => {
+			s = (ctx as Ctx).t("items", { n: 42 });
+
+			return next();
+		});
+
+	await entry(c)(ctxFor(13), noop);
+	assert.equal(s, "42 items"); // 42 → other, {n} interpolated
+});
+
+test("missing key in a locale falls back to the default locale", async () => {
+	let bye = "";
+	const c = new Composer<Context>()
+		.install(i18n({ defaultLocale: "en", locales }))
+		.use(async (ctx, next) => {
+			await (ctx as Ctx).changeLanguage("ru"); // ru has no "bye"
+
+			bye = (ctx as Ctx).t("bye");
+
+			return next();
+		});
+		
+	await entry(c)(ctxFor(4), noop);
+	assert.equal(bye, "Bye"); // fell back to en
+});

package/src/index.ts

@@ -0,0 +1,91 @@
+import type { Context, Plugin } from "@yaebal/core";
+import { MemoryStorage, type StorageAdapter } from "@yaebal/session";
+
+/**
+ * a plural form set keyed by `Intl.PluralRules` categories. `other` is required
+ * as the fallback; the rest are optional and selected per locale via
+ * `new Intl.PluralRules(locale).select(n)`.
+ */
+export interface PluralDict {
+	zero?: string;
+	one?: string;
+	two?: string;
+	few?: string;
+	many?: string;
+	other: string;
+}
+
+/** a single translation value: a plain template or a set of plural forms. */
+export type DictValue = string | PluralDict;
+
+/**
+ * a translation table: key → template (with `{placeholder}` interpolation), or
+ * key → plural forms (selected by `{n}` via `Intl.PluralRules`).
+ */
+export type Dict = Record<string, DictValue>;
+
+export type TFn = (key: string, params?: Record<string, unknown>) => string;
+
+/** what the plugin adds to the context. powers morda/jsx `useTranslation`. */
+export interface I18nControls {
+	t: TFn;
+	locale: string;
+	changeLanguage(locale: string): Promise<void>;
+}
+
+export interface I18nOptions<L extends string> {
+	defaultLocale: L;
+	locales: Record<L, Dict>;
+	/** where to persist each chat's locale. defaults to in-memory. */
+	storage?: StorageAdapter<string>;
+	/** locale key for an update. default: per-chat (`ctx.chat.id`). */
+	getKey?: (ctx: Context) => string | undefined;
+}
+
+/**
+ * i18n plugin. adds `ctx.t` / `ctx.locale` / `ctx.changeLanguage`, with the
+ * active locale persisted per chat. missing keys fall back to the default
+ * locale, then to the key itself.
+ */
+export function i18n<L extends string>(options: I18nOptions<L>): Plugin<Context, I18nControls> {
+	const { defaultLocale, locales } = options;
+
+	const storage = options.storage ?? new MemoryStorage<string>();
+	const getKey = options.getKey ?? ((ctx: Context) => ctx.chat?.id?.toString());
+
+	return (composer) =>
+		composer.derive(async (ctx): Promise<I18nControls> => {
+			const key = getKey(ctx);
+			let locale: string =
+				(key !== undefined ? await storage.get(key) : undefined) ?? defaultLocale;
+
+			const t: TFn = (k, params) => {
+				const def: Dict = locales[defaultLocale] ?? {};
+				const dict: Dict = locales[locale as L] ?? def;
+				const raw: DictValue = dict[k] ?? def[k] ?? k;
+
+				let s: string;
+				if (typeof raw === "string") {
+					s = raw;
+				} else {
+					const n = params?.n;
+					const category = typeof n === "number" ? new Intl.PluralRules(locale).select(n) : "other";
+
+					s = raw[category as keyof PluralDict] ?? raw.other;
+				}
+
+				if (params) {
+					for (const [pk, pv] of Object.entries(params)) s = s.replaceAll(`{${pk}}`, String(pv));
+				}
+				
+				return s;
+			};
+
+			const changeLanguage = async (next: string): Promise<void> => {
+				locale = next;
+				if (key !== undefined) await storage.set(key, next);
+			};
+
+			return { t, locale, changeLanguage };
+		});
+}