Internationalization (I18n)

I18n workflow

Localize bot replies by detecting locale, loading dictionaries, and keeping translations close to handlers.

Locale detection

Resolve language from user, chat, or explicit middleware configuration.

Learn more

Translation helper

Use `ctx.i18n` from handlers after middleware registration.

Learn more

Fallback behavior

Keep a default locale so missing translations do not break replies.

Learn more

Built-in i18n middleware for multi-language bot responses.

Quick Start

import { Bot, I18n } from 'vibegram';

const bot = new Bot('YOUR_BOT_TOKEN');

const i18n = new I18n('en'); // default locale

// Load locale dictionaries
i18n.loadLocale('en', {
    welcome: 'Welcome {name}!',
    help: 'Available commands: /start, /help',
    bye: 'Goodbye!',
});

i18n.loadLocale('id', {
    welcome: 'Selamat datang {name}!',
    help: 'Perintah tersedia: /start, /help',
    bye: 'Sampai jumpa!',
});

i18n.loadLocale('es', {
    welcome: '¡Bienvenido {name}!',
    help: 'Comandos disponibles: /start, /help',
    bye: '¡Adiós!',
});

bot.use(i18n.middleware());

Using Translations

bot.command('start', async ctx => {
    const text = ctx.i18n!.t('welcome', { name: ctx.from?.first_name || 'Guest' });
    await ctx.reply(text);
});

Template Variables

Use {variable} placeholders:

i18n.loadLocale('en', {
    order_confirmed: 'Order #{id} confirmed. Total: ${amount}.',
});

ctx.i18n!.t('order_confirmed', { id: '1234', amount: '99.99' });
// → "Order #1234 confirmed. Total: $99.99."

How Language Detection Works

The middleware automatically reads ctx.from?.language_code from Telegram's client settings. If the locale isn't loaded, it falls back to the default locale.