Перекладіть свій Elysia backend веб-сайт за допомогою Intlayer | Інтернаціоналізація (i18n)

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

Див. реалізацію пакету на GitHub: https://github.com/aymericzip/intlayer/tree/main/packages/elysia-intlayer

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

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

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

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

Див. Application Template на GitHub.

Установка

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

npx intlayer init --interactive

прапорець --interactive є опціональним. Використовуйте intlayer-cli init, якщо ви є AI-агентом.

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

npm install intlayer elysia-intlayer

Elysia орієнтований на runtime Bun. elysia-intlayer спирається на AsyncLocalStorage (замість бібліотеки cls-hooked, яку використовують плагіни Intlayer на базі Node) саме тому, що Bun не реалізує async_hooks.createHook.

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

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

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

const config: IntlayerConfig = {
  internationalization: {
    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
    /**
     * Локаль за замовчуванням, яка використовується як fallback, якщо запитану локаль не знайдено.
     */
    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: "Ejemplo de contenido devuelto en español",
    }),
  },
} satisfies Dictionary;

export default indexContent;

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

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

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

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

import { Elysia } from "elysia";
import { intlayer } from "elysia-intlayer";

const app = new Elysia()
  // Завантажте плагін інтернаціоналізації
  .use(intlayer())
  // Маршрути
  .get("/", ({ intlayer }) => ({
    // Мова, яка використовується для цього запиту, узгоджена `Accept-Language` або прочитана з сховища
    locale: intlayer!.locale,
    greeting: intlayer!.t({
      uk: "Привіт",
      en: "Hello",
      fr: "Bonjour",
      es: "Hola",
    }),
    content: intlayer!.getIntlayer("index").exampleOfContent,
  }))
  .listen(3000);

console.log(
  `🦊 Elysia is running at ${app.server?.hostname}:${app.server?.port}`
);

Плагін реєструє свій контекст через глобальний derive, який Elysia типізує як Partial<{ intlayer: IntlayerContext }>. Під час виконання значення завжди присутнє для маршрутів, зареєстрованих після .use(intlayer()), тож використовуйте non-null assertion (intlayer!.locale) — або optional chaining — щоб задовольнити TypeScript у режимі strict.

Контекст маршруту надає:

Ті самі helpers також експортуються як standalone. Вони отримують поточний запит через AsyncLocalStorage, тож ви можете викликати їх без деструктуризації контексту:

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

const app = new Elysia()
  .use(intlayer())
  .get("/t_example", () =>
    t({
      uk: "Приклад повернутого вмісту українською мовою",
      en: "Example of returned content in English",
      fr: "Exemple de contenu renvoyé en français",
      es: "Ejemplo de contenido devuelto en español",
    })
  )
  .get("/getIntlayer_example", () => getIntlayer("index").exampleOfContent)
  .get(
    "/getDictionary_example",
    () => getDictionary(dictionaryExample).exampleOfContent
  )
  .listen(3000);

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

Запуск вашого застосунку

Додайте скрипти Intlayer до вашого package.json. intlayer build компілює ваші декларації контенту в директорію .intlayer і генерує типи TypeScript:

{
  "scripts": {
    "dev": "intlayer build && bun run --watch src/index.ts",
    "build": "intlayer build",
    "start": "bun run src/index.ts",
    "i18n:fill": "intlayer fill",
    "i18n:test": "intlayer test"
  }
}

Потім запустіть сервер:

bun run dev

Перевірте узгодження локалі за допомогою Accept-Language:

curl -H "Accept-Language: fr" http://localhost:3000/
# {"locale":"fr","greeting":"Bonjour","content":"Exemple de contenu renvoyé en français"}

curl -H "Accept-Language: es" http://localhost:3000/
# {"locale":"es","greeting":"Hola","content":"Ejemplo de contenido devuelto en español"}

intlayer build не є суворо обов'язковим перед bun run src/index.ts: плагін також готує словники під час старту застосунку Elysia. Запуск наперед тримає згенеровані типи актуальними для вашого редактора та усуває вартість збірки під час першого запиту.

Сумісність

elysia-intlayer повністю сумісна з:

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

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

За замовчуванням плагін визначає локаль у такому порядку:

1. Cookie INTLAYER_LOCALE.
2. Заголовок x-intlayer-locale.
3. Узгодження через заголовок Accept-Language.

Ви можете налаштувати cookie та заголовок, які використовуються для визначення локалі:

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;

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

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

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

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

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

VS Code Extension

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

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

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

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

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

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

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

Щоб це зробити, ви можете додати наступні інструкції до вашого файлу .gitignore:

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