Skip to main content

i18n plugin for GramIO. This plugin provide internationalization for your bots with Fluent syntax.

Works with
This package works with Bun
It is unknown whether this package works with Cloudflare Workers
This package works with Node.js
This package works with Deno
It is unknown whether this package works with Browsers
JSR Score
100%
Published
a week ago (0.0.3)

@gramio/i18n

npm JSR JSR Score

i18n plugin for GramIO.

This plugin provide internationalization for your bots with Fluent syntax.

example

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();
Built and signed on
GitHub Actions
View transparency log

Add Package

deno add @gramio/i18n

Import symbol

import * as mod from "@gramio/i18n";

Add Package

npx jsr add @gramio/i18n

Import symbol

import * as mod from "@gramio/i18n";

Add Package

yarn dlx jsr add @gramio/i18n

Import symbol

import * as mod from "@gramio/i18n";

Add Package

pnpm dlx jsr add @gramio/i18n

Import symbol

import * as mod from "@gramio/i18n";

Add Package

bunx jsr add @gramio/i18n

Import symbol

import * as mod from "@gramio/i18n";