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

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

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

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

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

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

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

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

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

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

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

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

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

npx intlayer init --interactive

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

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

npm install intlayer hono-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,
      Locales.UKRAINIAN,
    ],
    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",
      uk: "Приклад контенту, що повертається українською мовою",
    }),
  },
} satisfies Dictionary;

export default indexContent;

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

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

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

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

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

const app = new Hono();

// Завантаження обробника запитів інтернаціоналізації
app.use("*", intlayer());

// Маршрути
app.get("/t_example", (c) => {
  return c.text(
    t({
      en: "Example of returned content in English",
      fr: "Exemple de contenu renvoyé en français",
      uk: "Приклад контенту, що повертається українською мовою",
    })
  );
});

app.get("/getIntlayer_example", (c) => {
  return c.json(getIntlayer("index").exampleOfContent);
});

app.get("/getDictionary_example", (c) => {
  return c.json(getDictionary(dictionaryExample).exampleOfContent);
});

export default app;

Сумісність

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

Він також безперешкодно працює з будь-яким рішенням для інтернаціоналізації в різних середовищах, включаючи браузери та API-запити. Ви можете налаштувати проміжне ПЗ для виявлення локалі через заголовки або файли 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;

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

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

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

hono-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

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