Перекладіть свій бекенд на Express за допомогою Intlayer

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

Практичні сценарії використання

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

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

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

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

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

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

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

Дивіться Application Template на GitHub.

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

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

npx intlayer init --interactive

прапорець --interactive не є обов'язковим. Використовуйте intlayer-cli init, якщо ви є ШІ-агентом.

Ця команда виявить ваше середовище та встановить необхідні пакети. Наприклад:

npm install intlayer express-intlayer

Налаштування

Налаштуйте параметри internationalization, створивши intlayer.config.ts у корені проєкту:

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

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

export default config;

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

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

import { t, type Dictionary } from "intlayer";

const indexContent = {
  key: "index",
  content: {
    exampleOfContent: t({
      uk: "Приклад поверненого вмісту українською",
      en: "Example of returned content in English",
      fr: "Exemple de contenu renvoyé en français",
      "es-ES": "Ejemplo de contenido devuelto en español (España)",
      "es-MX": "Ejemplo de contenido devuelto en español (México)",
    }),
  },
} satisfies Dictionary;

export default indexContent;

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

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

Налаштування Express-застосунку

Налаштуйте ваш Express-застосунок для використання express-intlayer:

import express, { type Express } from "express";
import { intlayer, t, getDictionary, getIntlayer } from "express-intlayer";
import dictionaryExample from "./index.content";

const app: Express = express();

// Підключення обробника інтернаціоналізації запитів
app.use(intlayer());

// Маршрути
app.get("/t_example", (_req, res) => {
  res.send(
    t({
      uk: "Приклад поверненого вмісту українською",
      en: "Example of returned content in English",
      fr: "Exemple de contenu renvoyé en français",
      "es-ES": "Ejemplo de contenido devuelto en español (España)",
      "es-MX": "Ejemplo de contenido devuelto en español (México)",
    })
  );
});

app.get("/getIntlayer_example", (_req, res) => {
  res.send(getIntlayer("index").exampleOfContent);
});

app.get("/getDictionary_example", (_req, res) => {
  res.send(getDictionary(dictionaryExample).exampleOfContent);
});

// Запуск сервера
app.listen(3000, () => console.log(`Сервер запущено на порту 3000`));

Сумісність

express-intlayer повністю сумісний з:

Воно також безшовно працює з будь-яким рішенням для інтернаціоналізації в різних середовищах, включно з браузерами та API-запитами. Ви можете налаштувати middleware для визначення локалі через headers або cookies:

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.

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

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

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

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

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

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

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

Часто задавані запитання