Переведите ваш Nest backend с Intlayer | Интернационализация (i18n)

express-intlayer, это мощный middleware для интернационализации (i18n) в приложениях на Express, разработанный для того, чтобы сделать ваши бэкенд-сервисы доступными по всему миру, предоставляя локализованные ответы в зависимости от предпочтений клиента. Поскольку NestJS построен поверх Express, вы можете без проблем интегрировать express-intlayer в ваши приложения на NestJS для эффективной работы с многоязычным контентом.

тические сценарии использования

• Отображение ошибок бэкенда на языке пользователя: Когда возникает ошибка, отображение сообщений на родном языке пользователя улучшает понимание и снижает разочарование. Это особенно полезно для динамических сообщений об ошибках, которые могут отображаться в компонентах фронтенда, таких как toast-уведомления или модальные окна.

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

• Отправка многоязычных писем: Отправка писем (будь то транзакционные письма, маркетинговые кампании или уведомления) на языке получателя может значительно повысить engagement и эффективность.

• Многоязычные Push-уведомления: Для мобильных приложений отправка push-уведомлений на предпочитаемом пользователем языке может повысить взаимодействие и удержание пользователей. Такой личный подход может сделать уведомления более релевантными и полезными.

• Прочие коммуникации: Любая форма коммуникации из backend-части, такая как SMS-сообщения, системные оповещения или обновления пользовательского интерфейса, выигрывает от использования языка пользователя, обеспечивая ясность и повышая общее удовлетворение пользователя.

Интернационализируя backend, ваше приложение не только учитывает культурные различия, но и лучше соответствует потребностям глобального рынка, что является ключевым шагом в расширении ваших услуг по всему миру.

Начало работы

Создание нового проекта NestJS

npm install -g @nestjs/cli
nest new my-nest-app

Установка

Чтобы начать использовать express-intlayer, установите пакет с помощью npm:

npx intlayer init --interactive

флаг --interactive не является обязательным. Используйте intlayer-cli init, если вы являетесь ИИ-агентом.

Эта команда определит вашу среду и установит необходимые пакеты. Например:

npm install intlayer express-intlayer

Настройка tsconfig.json

Чтобы использовать Intlayer с TypeScript, убедитесь, что ваш файл tsconfig.json настроен для поддержки ES-модулей. Для этого установите параметры module и moduleResolution в значение nodenext.

{
  compilerOptions: {
    module: "nodenext",
    moduleResolution: "nodenext",
    // ... другие параметры
  },
}

Настройка

Настройте параметры интернационализации, создав файл intlayer.config.ts в корне вашего проекта:

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

const config: IntlayerConfig = {
  internationalization: {
    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH], // поддерживаемые локали
    defaultLocale: Locales.ENGLISH, // локаль по умолчанию
  },
};

export default config;

Объявление вашего контента

Создайте и управляйте объявлениями контента для хранения переводов:

Ваши объявления контента могут быть определены в любом месте вашего приложения, при условии, что они включены в директорию contentDir (по умолчанию, ./src). И соответствуют расширению файла объявления контента (по умолчанию, .content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}).

Для получения дополнительной информации обратитесь к документации по объявлениям контента.

Настройка промежуточного ПО Express

Интегрируйте промежуточное ПО express-intlayer в ваше приложение NestJS для обработки интернационализации:

import { MiddlewareConsumer, Module, NestModule } from "@nestjs/common";
import { AppController } from "./app.controller";
import { AppService } from "./app.service";
import { intlayer } from "express-intlayer";

@Module({
  imports: [],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule implements NestModule {
  configure(consumer: MiddlewareConsumer) {
    consumer.apply(intlayer()).forRoutes("*"); // Применить ко всем маршрутам
  }
}

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

Теперь вы можете использовать функцию getIntlayer для доступа к переводам в ваших сервисах или контроллерах:

import { Injectable } from "@nestjs/common";
import { getIntlayer } from "express-intlayer";

@Injectable()
export class AppService {
  getHello(): string {
    return getIntlayer("app").greet; // Получить приветствие из переводов
  }
}

Совместимость

express-intlayer полностью совместим с:

• react-intlayer для приложений на React
• next-intlayer для приложений на Next.js
• vite-intlayer для приложений на Vite

Он также без проблем работает с любыми решениями для интернационализации в различных средах, включая браузеры и API-запросы. Вы можете настроить промежуточное ПО для определения локали через заголовки или куки:

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

const config: IntlayerConfig = {
  // ... Другие параметры конфигурации
  routing: {
    storage: [
      { type: "header", name: "my-locale-header" },
      { type: "cookie", name: "my-locale-cookie" },
    ],
  },
};

export default config;

По умолчанию express-intlayer будет интерпретировать заголовок Accept-Language для определения предпочтительного языка клиента.

Для получения дополнительной информации о конфигурации и продвинутых темах посетите нашу документацию.

Настройка TypeScript

express-intlayer использует мощные возможности TypeScript для улучшения процесса интернационализации. Статическая типизация TypeScript гарантирует, что каждый ключ перевода учтен, снижая риск отсутствия переводов и повышая удобство сопровождения.

Убедитесь, что автогенерируемые типы (по умолчанию в ./types/intlayer.d.ts) включены в ваш файл tsconfig.json.

{
  // ... Ваши существующие настройки TypeScript
  include: [
    // ... Ваши существующие настройки TypeScript
    ".intlayer/**/*.ts", // Включить автогенерируемые типы
  ],
}

Расширение VS Code

Для улучшения вашего опыта разработки с Intlayer вы можете установить официальное расширение Intlayer для VS Code.

Установить из VS Code Marketplace

Это расширение предоставляет:

• Автозаполнение ключей перевода.
• Обнаружение ошибок в реальном времени для отсутствующих переводов.
• Встроенный просмотр переведенного содержимого.
• Быстрые действия для удобного создания и обновления переводов.

Для получения дополнительной информации о том, как использовать расширение, обратитесь к документации расширения Intlayer для VS Code.

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

Рекомендуется игнорировать файлы, сгенерированные Intlayer. Это позволит избежать их коммита в ваш репозиторий Git.

Чтобы сделать это, вы можете добавить следующие инструкции в ваш файл .gitignore:

# Игнорировать файлы, сгенерированные Intlayer
.intlayer