Содержимое этой страницы было переведено с помощью ИИ.

Смотреть последнюю версию оригинального контента на английском

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

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

Обзор

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

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

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

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

typescript

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

Параметры

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

Возвращает

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

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

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

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

src/index.ts

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 приведет к ошибкам во время выполнения, так как необходимая информация о локали будет недоступна.

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

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

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

src/index.ts

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! (язык по умолчанию).

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

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

src/index.ts

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.",    })  );});

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

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

src/index.ts

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

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

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

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

intlayer.config.ts

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 для строгого соблюдения объявленных локалей:

Режим	Поведение
strict	Для всех объявленных локалей должны быть предоставлены переводы. Отсутствие перевода вызовет ошибку.
inclusive	Объявленные локали должны иметь переводы. Отсутствующие локали вызывают предупреждения, но принимаются.
loose	Принимается любая существующая локаль, даже если она не объявлена.

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

intlayer.config.ts

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

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

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

src/index.ts

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

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

Проблема	Причина	Решение
Функция t не работает	Middleware не подключен	Убедитесь, что app.use(intlayer()) добавлен до маршрутов.
Ошибка отсутствующих переводов	Включён строгий режим без всех локалей	Предоставьте все необходимые переводы.

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

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

Заключение

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

История документации

5.5.10 - 2025-06-29: Инициализация истории

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

Ссылка на документацию GitHub

Начать