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

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

Подивитися реалізацію пакета на GitHub.

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

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

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

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

Подивитися шаблон додатка на GitHub.

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

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

npx intlayer init --interactive

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

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

npm install intlayer fastify-intlayer

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

Налаштуйте параметри інтернаціоналізації, створивши файл 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({
      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}).

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

Налаштування додатка Fastify

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

import Fastify from "fastify";
import { intlayer, t, getDictionary, getIntlayer } from "fastify-intlayer";
import dictionaryExample from "./index.content";

const fastify = Fastify({ logger: true });

// Завантажити плагін інтернаціоналізації
await fastify.register(intlayer);

// Маршрути
fastify.get("/t_example", async (_req, reply) => {
  return t({
    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)",
  });
});

fastify.get("/getIntlayer_example", async (_req, reply) => {
  return getIntlayer("index").exampleOfContent;
});

fastify.get("/getDictionary_example", async (_req, reply) => {
  return getDictionary(dictionaryExample).exampleOfContent;
});

// Запуск сервера
const start = async () => {
  try {
    await fastify.listen({ port: 3000 });
  } catch (err) {
    fastify.log.error(err);
    process.exit(1);
  }
};

start();

Сумісність

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

• react-intlayer для React-додатків
• next-intlayer для Next.js-додатків
• vite-intlayer для Vite-додатків

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

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;

За замовчуванням fastify-intlayer інтерпретуватиме заголовок Accept-Language для визначення вподобаної мови клієнта.

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

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

fastify-intlayer використовує потужні можливості TypeScript для покращення процесу інтернаціоналізації. Статична типізація TypeScript гарантує, що кожен ключ перекладу врахований, знижуючи ризик відсутності перекладів та покращуючи підтримуваність.

Переконайтеся, що автоматично згенеровані типи (за замовчуванням у ./types/intlayer.d.ts) включені у ваш файл tsconfig.json.

{
  // ... Ваші існуючі конфігурації TypeScript
  "include": [
    // ... Ваші існуючі конфігурації TypeScript
    ".intlayer/**/*.ts", // Включити автоматично згенеровані типи
  ],
}

Розширення VS Code

Щоб покращити ваш досвід розробки з Intlayer, ви можете встановити офіційне розширення Intlayer VS Code Extension.

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

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

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

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

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

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

# Ігнорувати файли, що генеруються Intlayer
.intlayer

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