nestjs-telegraf-i18n v1.1.6

Nestjs Telegraf I18n

Seamless integration of nestjs-telegraf and nestjs-i18n. A middleware that merges both contexts.

handle_start_command(ctx: TelegrafI18nContext) { 
    // Translates the message into the user specific language automatically
    const internationalized_message = ctx.t("i18n.menus.hello.message");
    await ctx.reply(internationalized_message);
}

Install nestjs-telegraf-i18n

npm i nestjs-telegraf-i18n

Prerequisites

Make sure you have nestjs-telegraf, nestjs-i18n installed

npm i nestjs-telegraf nestjs-i18n

Set up

Nestjs-i18n Module

Initialize your I18nModule as you would usually do. The official documentation provides good tutorials how to do it

@Module({
    imports: [
        I18nModule.forRoot({
            ...
        })
    ],
})
export class AppModule {}

Nestjs-Telegraf Module

• Add TelegrafI18nModule to the imports
• Only async setups for the TelegrafModule are possible. Use TelegrafModule.forRootAsync(...)
• Inject the TelegrafI18nMiddlewareProvider
• Provide to the Telegraf Module the TelegrafI18nContext
• Add the telegrafI18nMiddleware to the middleware array

import { Module } from '@nestjs/common';
import { TelegrafModule } from 'nestjs-telegraf';
import { TelegrafI18nModule, TelegrafI18nMiddlewareProvider, TelegrafI18nContext } from 'nestjs-telegraf-i18n';

@Module({
    imports: [
        TelegrafI18nModule,
        TelegrafModule.forRootAsync({
            inject: [TelegrafI18nMiddlewareProvider],
            useFactory: (telegrafI18nMiddlewareProvider: TelegrafI18nMiddlewareProvider) => ({
                token: "<your_bot_token>",
                options: {
                    contextType: TelegrafI18nContext,
                },
                middlewares: [
                    telegrafI18nMiddlewareProvider.telegrafI18nMiddleware,
                ],
            }),
        }),
    ],
})
export class TelegramModule {}

Usage

The middleware injects the i18n object into the Telegraf context with the context-specific language configuration.

In your function make the ctx type aware that it has the i18n object by providing the type TelegrafI18nContext

Use ctx.t("<your_i18n_key>") or ctx.translate("<your_i18n_key>") for the translations.

import { Ctx, Start, Update } from 'nestjs-telegraf';
import { TelegrafI18nContext } from 'nestjs-telegraf-i18n';

@Update()
export class BotUpdate {
    @Start()
    async start_command(@Ctx() ctx: TelegrafI18nContext) {
        const internationalized_message = ctx.t("i18n.menus.hello.message");
        await ctx.reply(internationalized_message);
    }
}

If you have multiple Telegraf context types that you want to use, chain them with &.

import { Command, Ctx, Update } from 'nestjs-telegraf';
import { Scenes } from "telegraf";
import { TelegrafI18nContext } from 'nestjs-telegraf-i18n';

@Update()
export class BotUpdate {
    @Command('hello')
    async helloCommand(@Ctx() ctx: Scenes.WizardContext & TelegrafI18nContext) {
        // You have access to both the WizardContext and TelegrafI18nContext internals
        const internationalized_message = ctx.t("i18n.menus.hello.message");
        await ctx.reply(internationalized_message);
        await ctx.scene.enter('some_scene');
    }
}

Bot injection

If you need to use the native bot instance, you can still benefit from the injected i18n instance by providing the correct context.

import { Telegraf } from "telegraf";
import { InjectBot, Update } from 'nestjs-telegraf';
import { TelegrafI18nContext } from 'nestjs-telegraf-i18n';

@Update()
export class BotUpdate {
    constructor(
        @InjectBot() private readonly bot: Telegraf<TelegrafI18nContext>
    ) {
        this.bot.help((ctx) => {
                const message = ctx.t("i18n.menus.help.message");
                ctx.reply(message)
            }
        )
    }
}

Type Safety

You can use the built in type safety features from nestjs-i18n Follow their instructions to generate the translation types, and you can pass them to the extended context.

@Update()
export class BotUpdate {
    @Start()
    async start_command(@Ctx() ctx: TelegrafI18nContext<I18nTranslations>) {
        const internationalized_message = ctx.t("i18n.menus.hello.message");
        await ctx.reply(internationalized_message);
    }
}

The same applies to native bot injection.

@Update()
export class BotUpdate {
    constructor(
        @InjectBot() private readonly bot: Telegraf<TelegrafI18nContext<I18nTranslations>>
    ) {
        this.bot.help((ctx) => {
                const message = ctx.t("i18n.menus.help.message");
                ctx.reply(message)
            }
        )
    }
}

Using nestjs-telegraf-i18n with other telegraf middlewares

If you want to have the access to i18n in your other telegraf middlewares you can easily do that by providing the I18nContext. Make sure you initialize the i18n middleware (put it first in the array) before the middleware where you want to use it.

E.g. your custom middleware

import { Middleware } from 'telegraf';
import { TelegrafI18nContext } from 'nestjs-telegraf-i18n';

const WHITELISTED_USERS: number[] = [123456789, 987654321];

export const whitelistMiddleware: Middleware<TelegrafI18nContext> = async (ctx: TelegrafI18nContext, next) => {
    if (!ctx.from) {
        return;
    }

    if (WHITELISTED_USERS.includes(ctx.from.id)) {
        await next();
    } else {
        await ctx.reply(ctx.t('errors.userNotWhitedMessage'));
    }
};

Make sure to put the telegrafI18nMiddleware before the custom middleware

@Module({
  imports: [
    TelegrafI18nModule,
    TelegrafModule.forRootAsync({
      inject: [TelegrafI18nMiddlewareProvider],
      useFactory: (telegrafI18nMiddlewareProvider: TelegrafI18nMiddlewareProvider) => ({
        token: "<your_bot_token>",
        options: {
          contextType: TelegrafI18nContext,
        },
        middlewares: [
          telegrafI18nMiddlewareProvider.telegrafI18nMiddleware,
          whitelistMiddleware
        ],
      }),
    }),
  ],
})
export class TelegramModule {}

I18nContext

If you need the I18nContext object you can use the getter

    async somefuntion(ctx: TelegrafI18nContext) {
        const i18nContext = ctx.i18n();
    }