Перекладіть ваш бекенд на Nest за допомогою Intlayer | Інтернаціоналізація (i18n)

express-intlayer — це потужний middleware для інтернаціоналізації (i18n) для додатків на Express, призначений зробити ваші бекенд-сервіси доступними у всьому світі, надаючи локалізовані відповіді відповідно до уподобань клієнта. Оскільки NestJS побудований поверх Express, ви можете безшовно інтегрувати express-intlayer у свої додатки NestJS для ефективної роботи з багатомовним вмістом.

Типові випадки використання

• Відображення помилок бекенду мовою користувача: Коли виникає помилка, відображення повідомлень рідною мовою користувача покращує розуміння та зменшує фрустрацію. Це особливо корисно для динамічних повідомлень про помилки, які можуть відображатися у front-end компонентах, таких як toasts або modals.

• Отримання багатомовного контенту: Для застосунків, які дістають контент із бази даних, інтернаціоналізація гарантує можливість надавати цей контент кількома мовами. Це критично важливо для платформ, таких як e-commerce-сайти або системи керування контентом (CMS), яким потрібно відображати описи продуктів, статті та інший контент мовою, яку віддає перевагу користувач.

• Надсилання багатомовних електронних листів: Чи то транзакційні листи, маркетингові кампанії або сповіщення — надсилання листів мовою отримувача може значно підвищити залученість та ефективність.

• Багатомовні push-повідомлення: Для мобільних застосунків відправлення push-повідомлень мовою, яку віддає перевагу користувач, може підвищити взаємодію та утримання. Такий персональний підхід робить повідомлення більш релевантними та такими, що спонукають до дії.

• Інші комунікації: Будь-яка форма комунікації з бекенду, наприклад SMS-повідомлення, системні оповіщення або оновлення інтерфейсу користувача, виграє від того, що надсилається мовою користувача, що забезпечує зрозумілість і покращує загальний досвід користувача.

Інтернаціоналізуючи бекенд, ваш застосунок не лише поважає культурні відмінності, а й краще відповідає потребам глобального ринку, що робить це ключовим кроком для масштабування ваших сервісів у світі.

Початок роботи

Перегляньте шаблон застосунку на GitHub.

Створіть новий проект NestJS

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

Встановлення

Щоб почати використовувати express-intlayer, встановіть пакет за допомогою npm:

npm install intlayer express-intlayernpx intlayer init

Налаштуйте 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;

Оголосіть свій контент

Створюйте та керуйте деклараціями контенту для збереження перекладів:

import { t, type Dictionary } from "intlayer";const appContent: Dictionary = {  key: "app",  content: {    greet: t({      uk: "Привіт, світ!",      en: "Hello World!",      fr: "Bonjour le monde !",      es: "¡Hola Mundo!",    }),  },};export default appContent;

Оголошення вашого вмісту можна розміщувати будь-де у вашому додатку, якщо вони включені в директорію contentDir (за замовчуванням ./src). І відповідають розширенню файлу декларації вмісту (за замовчуванням .content.{json,ts,tsx,js,jsx,mjs,mjx,cjs,cjx}).

Для отримання додаткових відомостей зверніться до документації щодо оголошень контенту.

Налаштування middleware для Express

Інтегруйте middleware 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-запитами. Ви можете налаштувати middleware для визначення локалі через заголовки (headers) або cookie:

import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  // ... Other configuration options  middleware: {    headerName: "my-locale-header",    cookieName: "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 Extension.

Встановити з VS Code Marketplace

Це розширення надає:

• Автодоповнення для ключів перекладу.
• Виявлення помилок у реальному часі для відсутніх перекладів.
• Вбудовані попередні перегляди перекладеного вмісту.
• Швидкі дії для простого створення та оновлення перекладів.

Щоб дізнатися більше про використання розширення, зверніться до документації розширення Intlayer для VS Code.

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

Рекомендується ігнорувати файли, згенеровані Intlayer. Це дозволить уникнути їх додавання до вашого репозиторію Git.

Для цього ви можете додати такі інструкції у файл .gitignore:

# Ігнорувати файли, згенеровані Intlayer.intlayer