telegraf-i18nx

Modern internationalization (i18n) middleware for Telegraf bots with full TypeScript support.

✨ Features

• 🎯 Full TypeScript support with type definitions
• 📦 ES6 modules (ESM)
• 🔄 Dynamic language switching
• 💾 Session-based language persistence
• 🔧 Variable interpolation with {{variable}}
• 🌍 Multiple locale files support
• 🎨 Customizable locale storage
• 🛡️ Type-safe context extensions

📦 Installation

npm install telegraf-i18nx

🚀 Quick Start

TypeScript

import { Telegraf, session } from 'telegraf';
import { createI18nxMiddleware, I18nxContext } from 'telegraf-i18nx';

const bot = new Telegraf<I18nxContext>(process.env.BOT_TOKEN!);

bot.use(session());
bot.use(createI18nxMiddleware({
  defaultLocale: 'en',
  directory: './locales'
}));

bot.start((ctx) => {
  ctx.reply(ctx.i18nx.t('welcome', { name: ctx.from?.first_name }));
});

bot.launch();

JavaScript

import { Telegraf, session } from 'telegraf';
import { createI18nxMiddleware } from 'telegraf-i18nx';

const bot = new Telegraf(process.env.BOT_TOKEN);

bot.use(session());
bot.use(createI18nxMiddleware({
  defaultLocale: 'en',
  directory: './locales'
}));

bot.start((ctx) => {
  ctx.reply(ctx.i18nx.t('welcome', { name: ctx.from.first_name }));
});

bot.launch();

📖 API Reference

createI18nxMiddleware(options)

Creates the i18n middleware.

interface I18nxOptions {
  defaultLocale?: string;        // Default: 'en'
  directory?: string;             // Default: './locales'
  getLocale?: (ctx: Context) => string | undefined;
  setLocale?: (ctx: Context, lang: string) => void;
}

ctx.i18nx

The middleware extends context with i18nx object:

ctx.i18nx.t(key: string, vars?: Record<string, string | number>): string
ctx.i18nx.changeLanguage(lang: string): void
ctx.i18nx.getLanguage(): string

🎯 TypeScript Usage

Type-safe context

import { I18nxContext } from 'telegraf-i18nx';

bot.command('settings', (ctx: I18nxContext) => {
  // Full autocomplete and type checking
  const currentLang = ctx.i18nx.getLanguage();
  ctx.reply(ctx.i18nx.t('settings.title'));
});

Custom context types

import { Context } from 'telegraf';
import { I18nxContext } from 'telegraf-i18nx';

interface MyContext extends I18nxContext {
  myCustomProperty: string;
}

const bot = new Telegraf<MyContext>(token);

📁 Project Structure

my-bot/
├── locales/
│   ├── en.json
│   ├── uz.json
│   └── ru.json
├── src/
│   └── index.ts
├── package.json
└── tsconfig.json

📝 License

MIT © Raxmatov Eldorbek