@grully/i18n-nunjucks

Nunjucks template plugin for @grully/i18n – write your translation files with Nunjucks, the powerful templating engine inspired by Jinja2.

Use filters, macros, includes, template inheritance, and custom extensions to create clean, dynamic bot responses – all fully integrated with @grully/i18n.

Features

• 🧩 Seamless integration with @grully/i18n
• 📁 Translation files end with .njk
• 🎨 Full Nunjucks syntax support: variables, filters, blocks, includes, macros, conditionals, loops
• 🔧 Custom filters, globals, and extensions can be added via plugin options
• ⚡ Loads templates from a folder using Nunjucks’ FileSystemLoader

Installation

npm install @grully/i18n-nunjucks

Example

import { env } from "bun"
import { Bot, session, type Context, type SessionFlavor } from "grammy"
import i18n, { type GrullyI18nFlavor, type GrullyI18nSessionData } from '@grully/i18n'
import i18nNjk from '@grully/i18n-nunjucks'

type BotContext = Context & GrullyI18nFlavor & SessionFlavor<GrullyI18nSessionData>
type MyBot = Bot<BotContext>

const TOKEN = env.TOKEN!

const bot: MyBot = new Bot(
    TOKEN
)

bot.use(session({
    initial: () => {
        return {
            languageCode: 'en'
        }
    }
}))
bot.use(i18n({
    folder: 'locales',
    defaultLocale: 'en',
    plugin: i18nNjk()
}))

bot.command(
    'start',
    async ctx => {
        const result = ctx.t(
            'start/start',
            {
                name: ctx.from?.first_name
            }
        )

        await ctx.reply(result)
    }
)

bot.command(
    'locales',
    async ctx => {
        const result = ctx.t(
            'locales',
            {
                locales: ctx.i18n.locales
            }
        )

        await ctx.reply(result)
    }
)

bot.command(
    'set_lang',
    async ctx => {
        const key = ctx.match
        const lang = key ?? 'ru'

        ctx.session.languageCode = lang
        await ctx.reply(ctx.t('set_lang', { lang: lang }))
    }
)

bot.api.config.use(
    async (prev, method, payload, abort) => {
        return prev(
            method,
            {
                ...payload,
                parse_mode: 'HTML'
            },
            abort
        )
    }
)

bot.start({
    onStart: info => {
        console.log(info)
    }
})

Template Example (locales/en/start/start.njk)

Hello, {{ name }}! Welcome to the bot.

Plugin Options

You can pass a configuration object to i18nNjk() to customize the Nunjucks environment.

i18nNjk({
  // Standard Nunjucks ConfigureOptions
  autoescape: false,
  // Custom filters
  filters: {
    uppercase: (str) => str.toUpperCase(),
  },
  // Global variables available in all templates
  globals: {
    botName: 'MySuperBot',
  },
  // Custom extensions (classes implementing the Extension interface)
  extensions: {
    MyExtension: new MyExtension(),
  },
})

All standard Nunjucks ConfigureOptions are forwarded to the Environment constructor, as well as to the FileSystemLoader. Use them to tweak caching, tags, or autoescaping behaviour.

How It Works

1. The plugin registers itself for files with the .njk extension.
2. On first render it creates a Nunjucks Environment backed by a FileSystemLoader pointing to your locale’s root folder.
3. Every ctx.t(key, vars) call loads the corresponding .njk file and renders it with the provided variables, and with the custom filters, globals, and extensions you supplied.
4. Template results are cached in memory for subsequent calls when needCache is enabled (default behaviour of @grully/i18n).

Because the full Nunjucks toolkit is available, you can build sophisticated translation files with includes, template inheritance, and any custom logic you need – all while keeping your code clean and maintainable.