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

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

Обзор

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

Основные возможности

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

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

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

Параметры

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

Возвращает

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

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

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

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

import express, { type Express } from "express";
import { intlayer } from "express-intlayer";

const app: Express = express();

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

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

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

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

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

Простой пример

Обслуживание локализованного контента на разных языках:

app.get("/", (_req, res) => {
  res.send(
    t({
      en: "Welcome!",
      fr: "Bienvenue!",
      es: "¡Bienvenido!",
    })
  );
});

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

• Клиент с заголовком Accept-Language: fr получит Bienvenue!.
• Клиент с Accept-Language: es получит ¡Bienvenido!.
• Клиент с Accept-Language: de получит Welcome! (язык по умолчанию).

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

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

app.get("/error", (_req, res) => {
  res.status(500).send(
    t({
      en: "An unexpected error occurred.",
      fr: "Une erreur inattendue s'est produite.",
      es: "Ocurrió un error inesperado.",
    })
  );
});

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

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

app.get("/greet", (_req, res) => {
  res.send(
    t({
      en: "Hello!",
      "en-GB": "Hello, mate!",
      fr: "Bonjour!",
      "es-MX": "¡Hola, amigo!",
      "es-ES": "¡Hola!",
    })
  );
});

app.get("/greet", (_req, res) => {
  res.send(
    t({
      en: "Hello!",
      "en-GB": "Hello, mate!",
      fr: "Bonjour!",
      "es-MX": "¡Hola, amigo!",
      "es-ES": "¡Hola!",
    })
  );
});

app.get("/greet", (_req, res) => {
  res.send(
    t({
      en: "Hello!",
      "en-GB": "Hello, mate!",
      fr: "Bonjour!",
      "es-MX": "¡Hola, amigo!",
      "es-ES": "¡Hola!",
    })
  );
});

Продвинутые темы

Механизм резервного варианта

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

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

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

export default config;

Например:

• Если defaultLocale установлен в Locales.CHINESE, а клиент запрашивает Locales.DUTCH, возвращаемый перевод будет по умолчанию из Locales.CHINESE.
• Если defaultLocale не определён, функция t будет использовать значение по умолчанию из Locales.ENGLISH.

Принудительное соблюдение строгого режима

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

Пример конфигурации:

import { type IntlayerConfig } from "intlayer";

const config = {
  // ... Ваша существующая конфигурация
  internationalization: {
    // ... Ваша существующая конфигурация интернационализации
    strictMode: "strict", // Включить строгий режим
  },
} satisfies IntlayerConfig;

export default config;

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

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

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

const translations: LanguageContent<string> = {
  en: "Good morning!",
  fr: "Bonjour!",
  es: "¡Buenos días!",
};

app.get("/morning", (_req, res) => {
  res.send(t(translations));
});

Распространённые ошибки и их устранение

Советы по эффективному использованию

1. Централизуйте переводы: Используйте централизованный модуль или JSON-файлы для управления переводами, чтобы повысить удобство сопровождения.
2. Проверяйте переводы: Убедитесь, что для каждого языкового варианта существует соответствующий перевод, чтобы избежать ненужного возврата к запасному языку.
3. Интегрируйте с фронтенд i18n: Синхронизируйте с системой интернационализации на фронтенде для обеспечения бесшовного пользовательского опыта во всём приложении.
4. Оценивайте производительность: Тестируйте время отклика вашего приложения при добавлении переводов, чтобы гарантировать минимальное влияние на производительность.

Заключение

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