Документация: функция t в hono-intlayer

Функция t в пакете hono-intlayer является основным инструментом для предоставления локализованных ответов в вашем приложении Hono. Она упрощает интернационализацию (i18n), динамически выбирая контент на основе предпочтительного языка пользователя.

Обзор

Функция t используется для определения и получения переводов для заданного набора языков. Она автоматически определяет соответствующий язык для возврата на основе настроек запроса клиента, таких как заголовок Accept-Language. Если предпочтительный язык недоступен, она плавно переключается на локаль по умолчанию, указанную в вашей конфигурации.

Ключевые особенности

• Динамическая локализация: автоматически выбирает наиболее подходящий перевод для клиента.
• Возврат к локали по умолчанию: переключается на локаль по умолчанию, если предпочтительный язык клиента недоступен, обеспечивая непрерывность пользовательского опыта.
• Легкость и скорость: разработана для высокопроизводительных приложений с минимальными накладными расходами.
• Поддержка строгого режима: обеспечивает строгое соблюдение объявленных локалей для надежной работы.

Сигнатура функции

t(translations: Record<string, string>): string;

Параметры

• translations: объект, в котором ключи, коды локалей (например, en, fr, ru), а значения, соответствующие переведенные строки.

Возвращаемое значение

• Строка, представляющая контент на предпочтительном языке клиента.

Загрузка обработчика запросов интернационализации

Чтобы обеспечить корректную работу функций интернационализации, предоставляемых hono-intlayer, вы должны загрузить промежуточное ПО (middleware) интернационализации в начале вашего приложения Hono. Это активирует функцию t и обеспечит правильную обработку определения локали и перевода.

Разместите промежуточное ПО app.use("*", intlayer()) перед любыми маршрутами в вашем приложении, чтобы все маршруты могли использовать преимущества интернационализации:

import { Hono } from "hono";
import { intlayer } from "hono-intlayer";

const app = new Hono();

// Загрузка обработчика запросов интернационализации
app.use("*", intlayer());

// Определяйте свои маршруты после загрузки промежуточного ПО
app.get("/", (c) => {
  return c.text(
    t({
      en: "Hello, World!",
      fr: "Bonjour le monde!",
      es: "¡Hola, Mundo!",
      ru: "Привет, мир!",
    })
  );
});

Почему это необходимо

• Определение локали: промежуточное ПО intlayer обрабатывает входящие запросы для определения предпочтительной локали пользователя на основе заголовков, файлов cookie или других настроенных методов.
• Контекст перевода: настраивает необходимый контекст для правильной работы функции t, гарантируя, что переводы возвращаются на правильном языке.
• Предотвращение ошибок: без этого промежуточного ПО использование функции t приведет к ошибкам во время выполнения, так как необходимая информация о локали будет недоступна.

Примеры использования

Базовый пример

Предоставление локализованного контента на разных языках:

app.get("/", (c) => {
  return c.text(
    t({
      en: "Welcome!",
      fr: "Bienvenue!",
      ru: "Добро пожаловать!",
    })
  );
});

Запросы клиентов:

• Клиент с Accept-Language: fr получит Bienvenue!.
• Клиент с Accept-Language: ru получит Добро пожаловать!.
• Клиент с Accept-Language: de получит Welcome! (локаль по умолчанию).

Обработка ошибок

Предоставление сообщений об ошибках на нескольких языках:

app.get("/error", (c) => {
  return c.text(
    t({
      en: "An unexpected error occurred.",
      fr: "Une erreur inattendue s'est produite.",
      ru: "Произошла непредвиденная ошибка.",
    }),
    500
  );
});

Использование вариантов локали

Укажите переводы для конкретных вариантов локалей:

app.get("/greet", (c) => {
  return c.text(
    t({
      en: "Hello!",
      "en-GB": "Hello, mate!",
      fr: "Bonjour!",
      ru: "Привет!",
    })
  );
});

Расширенные темы

Механизм возврата (Fallback)

Если предпочтительная локаль недоступна, функция t вернется к локали по умолчанию, определенной в конфигурации:

import { Locales, type IntlayerConfig } from "intlayer";

const config = {
  internationalization: {
    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.RUSSIAN],
    defaultLocale: Locales.ENGLISH,
  },
} satisfies IntlayerConfig;

export default config;

Принудительное использование строгого режима

Настройте функцию t для обеспечения строгого соблюдения объявленных локалей:

Интеграция с TypeScript

Функция t является типобезопасной при использовании с TypeScript. Определите типобезопасный объект переводов:

import { type LanguageContent } from "hono-intlayer";

const translations: LanguageContent<string> = {
  en: "Good morning!",
  fr: "Bonjour!",
  ru: "Доброе утро!",
};

app.get("/morning", (c) => {
  return c.text(t(translations));
});

Общие ошибки и устранение неполадок

Заключение

Функция t, мощный инструмент для интернационализации бэкенда. Эффективно используя ее, вы можете создать более инклюзивное и удобное приложение для глобальной аудитории. Для получения информации о расширенном использовании и детальных параметрах конфигурации обратитесь к документации.