@gramio/i18n

i18n plugin for GramIO.

This plugin provide internationalization for your bots with Fluent syntax.

You can setup type-safety for it.

Usage

Create locales folder with en.ftl file

# Simple things are simple.
hello-user = Hello, {$userName}!

# Complex things are possible.
shared-photos =
    {$userName} {$photoCount ->
        [one] added a new photo
       *[other] added {$photoCount} new photos
    } to {$userGender ->
        [male] his stream
        [female] her stream
       *[other] their stream
    }.

[!IMPORTANT] Fluent language support extensions for VSCode and WebStorm

Use plugin

// src/index.ts
import { Bot } from "gramio";
import { i18n } from "@gramio/i18n";

const bot = new Bot(process.env.TOKEN as string)
    .extend(i18n())
    .command("start", async (context) => {
        return context.send(
            context.t("shared-photos", {
                userName: "Anna",
                userGender: "female",
                photoCount: 3,
            })
        );
    })
    .onError(console.error)
    .onStart(console.log);

bot.start();

Options

Key	Type	Default	Description
defaultLocale?	string	"en"	Default locale
directory?	string	"locales"	The path to the folder with *.ftl files

Methods

t

Using this method, you can get the text in your chosen language.

For example:

hello-user = Hello, {$userName}!

context.t("hello-user", { userName: "Anna" }); // Hello, Anna!

i18n.setLocale

You can set user locale by setLocale method.

[!WARNING] At the moment, there is no integration with sessions, and therefore, after the message, the language will again become the one that defaultLocale

bot.command("start", async (context) => {
    context.i18n.setLocale("ru");

    return context.send(
        context.t("shared-photos", {
            userName: "Anna",
            userGender: "female",
            photoCount: 3,
        })
    );
});

i18n.locale

Get current user locale.

bot.command("lang", async (context) => {
    return context.send(context.i18n.locale);
});

Type-safety

You can use this plugin with fluent2ts which code-generates typescript types from your .ftl files. See usage.

Npm:

npx fluent2ts

Bun:

bunx fluent2ts

Yarn:

yarn dlx fluent2ts

Pnpm:

pnpm exec fluent2ts

And so we have a generated locales.types.ts file in src folder that exports the TypedFluentBundle interface. We set this type as a generic for the i18n plugin. And now we have type-safety!

import type { TypedFluentBundle } from "./locales.types";
import { Bot } from "gramio";
import { i18n } from "@gramio/i18n";

const bot = new Bot(process.env.TOKEN as string)
    .extend(i18n<TypedFluentBundle>())
    .command("start", async (context) => {
        return context.send(
            context.t("shared-photos", {
                userName: "Anna",
                userGender: "female",
                photoCount: 3,
            })
        );
    })
    .onError(console.error)
    .onStart(console.log);

bot.start();