Интернационализация с помощью Fluent (fluent)

Fluent это система локализации, созданная Mozilla Foundation для создания естественных переводов. Она обладает очень мощным и элегантным синтаксисом, позволяющим любому человеку писать эффективные и полностью понятные переводы. Этот плагин использует преимущества этой удивительной системы локализации, чтобы сделать ботов, работающих на grammY, способными делать высококачественные переводы.

Не путать Не путайте это с i18n.

i18n это улучшенная версия этого плагина, которая работает как на Deno, так и на Node.js.

Инициализация Fluent

Первое, что вы делаете, - инициализируете Fluent:

import { Fluent } from "@moebius/fluent";

const fluent = new Fluent();

Затем нужно добавить хотя бы один перевод в экземпляр Fluent:

await fluent.addTranslation({
  // Укажите одну или несколько локалей, поддерживаемых вашим переводом:
  locales: "ru",

  // Вы можете напрямую указать контент перевода:
  source: "{СОДЕРЖАНИЕ ФАЙЛА ПЕРЕВОДА}",

  // Или файлы перевода:
  filePath: [
    `${__dirname}/feature-1/translation.ru.ftl`,
    `${__dirname}/feature-2/translation.ru.ftl`,
  ],

  // Все аспекты Fluent очень хорошо настраиваются:
  bundleOptions: {
    // Используйте этот параметр, чтобы избежать появления невидимых символов вокруг размещаемых объектов.
    useIsolating: false,
  },
});

Написание переведённх сообщений

Синтаксис Fluent должен быть прост в освоении. Вы можете начать с просмотра официальных примеров или с изучения полного руководства по синтаксису.

Давайте пока начнем с этого примера:

-bot-name = Apples Bot

welcome =
  Добро пожаловать, {$name}, это {-bot-name}!
  У вас { NUMBER($applesCount) ->
    [0] нет яблок
    [one] {$applesCount} яблоко
    *[other] {$applesCount} яблок(а)
  }.

Он демонстрирует три важные особенности Fluent, а именно: термины, замена переменных (она же замещаемые) и плюрализация.

Переменная welcome — это идентификатор сообщения, который будет использоваться для ссылки на это сообщение при его отправке.

Переменная -bot-name = Apples Bot определяет переменную с именем bot-name и значением Apples Bot. Конструкция {-bot-name} ссылается на ранее определенную переменную и при отправке сообщения будет заменена его значением.

Переменная {$name} будет заменена значением переменной name, которой вам нужно будет передать функции перевода самостоятельно.

И последнее Переменная (строки с 5 по 9) определяет селектор (очень похоже на оператор switch), который принимает результат специальной функции NUMBER, примененной к переменной applesCount, и выбирает одно из трех возможных сообщений для отображения на основе совпавшего значения. Функция NUMBER возвращает категорию CLDR plural category, основанную на предоставленном значении и используемоем переводе. Это эффективно реализует плюрализацию.

Конфигурация grammY

Теперь давайте посмотрим, как это сообщение может быть отображено ботом. Но сначала нам нужно настроить grammY на использование плагина.

Прежде всего, вам нужно настроить бота на использование контекстного расширителя Fluent. Если вы не знакомы с этой концепцией, вам следует прочитать официальную документацию по Расширители контекста.

import { Context } from "grammy";
import { FluentContextFlavor } from "@grammyjs/fluent";

// Расширьте тип контекста вашего приложения с помощью предоставляемого расширителя контекста
export type MyAppContext = Context & FluentContextFlavor;

Чтобы использовать дополненный тип контекста, вам нужно создать экземпляр бота следующим образом:

const bot = new Bot<MyAppContext>("");

И последним шагом будет регистрация самого плагина Fluent в grammY:

bot.use(
  useFluent({
    fluent,
  }),
);

Обязательно передайте ранее созданный экземпляр Fluent.

Передача локализованных сообщений

Отлично, теперь у нас есть все необходимое для вывода наших сообщений! Давайте сделаем это, определив тестовую команду в нашем боте:

bot.command("i18n_test", async (ctx) => {
  // Вызовите помощник "translate" или "t" для отображения
  // сообщения, указав идентификатор перевода и дополнительные параметры:
  await ctx.reply(
    ctx.t("welcome", {
      name: ctx.from.first_name,
      applesCount: 1,
    }),
  );
});

Теперь вы можете запустить бота и использовать команду /i18n_test. Должно появиться следующее сообщение:

Добро пожаловать, Slava, это Apples Bot!
У вас 1 яблоко.

Конечно, вместо “Slava” вы увидите свое собственное имя. Попробуйте изменить значение переменной applesCount и посмотрите, как изменится отображаемое сообщение!

Имейте в виду, что теперь вы можете использовать функцию перевода везде, где доступен Context. Библиотека автоматически определит язык для каждого пользователя, который будет взаимодействовать с вашим ботом, основываясь на его установленном языке в настройках Telegram. Вам нужно будет только создать несколько файлов перевода и убедиться, что все переводы правильно синхронизированы.

Следующие шаги

• Завершите чтение документации по Fluent, особенно руководства по синтаксису.
• Мигрируйте с плагина i18n.
• Ознакомьтесь с @moebius/fluent.

Краткая информация о плагине

• Название: fluent
• Исходник