@gramio/i18n

i18n plugin for GramIO.

This plugin provide internationalization for your bots with Fluent syntax.

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	first loaded language	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"); // if ru not found fallback to defaultLocale
    // context.i18n.setLocale("ru", true); if ru not found throw error

    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);
});

i18n.locales

Get loaded locales

bot.command("languages", async (context) => {
    return context.send(context.i18n.locales.join(", "));
});

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();

gramiojs/i18n