Creation:2024-12-02Last update:2025-06-29

    Документація: функція t у hono-intlayer

    Функція t у пакеті hono-intlayer є основним інструментом для надання локалізованих відповідей у вашому додатку Hono. Вона спрощує інтернаціоналізацію (i18n), динамічно вибираючи вміст на основі бажаної мови користувача.

    Огляд

    Функція t використовується для визначення та отримання перекладів для заданого набору мов. Вона автоматично визначає відповідну мову для повернення на основі налаштувань запиту клієнта, таких як заголовок Accept-Language. Якщо бажана мова недоступна, вона плавно повертається до мови за замовчуванням, указаної у вашій конфігурації.

    Ключові особливості

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

    Сигнатура функції

    typescript
    t(translations: Record<string, string>): string;

    Параметри

    • translations: об'єкт, де ключі, це коди локалей (наприклад, en, fr, uk), а значення, відповідні перекладені рядки.

    Повертає

    • Рядок, що представляє вміст бажаною мовою клієнта.

    Завантаження обробника запитів інтернаціоналізації

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

    Розмістіть проміжне ПЗ app.use("*", intlayer()) перед будь-якими маршрутами у вашому додатку, щоб усі маршрути могли скористатися перевагами інтернаціоналізації:

    src/index.ts
    import { Hono } from "hono";
import { intlayer } from "hono-intlayer";

const app = new Hono();

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

// Визначайте свої маршрути після завантаження проміжного ПЗ
app.get("/", (c) => {
  return c.text(
    t({
      en: "Hello, World!",
      fr: "Bonjour le monde!",
      es: "¡Hola, Mundo!",
      uk: "Привіт, світе!",
    })
  );
});

    Чому це потрібно

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

    Приклади використання

    Базовий приклад

    Надавайте локалізований вміст різними мовами:

    src/index.ts
    app.get("/", (c) => {  return c.text(    t({      en: "Welcome!",      fr: "Bienvenue!",      uk: "Ласкаво просимо!",    })  );});

    Запити клієнтів:

    • Клієнт із Accept-Language: fr отримає Bienvenue!.
    • Клієнт із Accept-Language: uk отримає Ласкаво просимо!.
    • Клієнт із Accept-Language: de отримає Welcome! (локаль за замовчуванням).

    Обробка помилок

    Надавайте повідомлення про помилки кількома мовами:

    src/index.ts
    app.get("/error", (c) => {  return c.text(    t({      en: "An unexpected error occurred.",      fr: "Une erreur inattendue s'est produite.",      uk: "Сталася неочікувана помилка.",    }),    500  );});

    Використання варіантів локалі

    Укажіть переклади для конкретних варіантів локалей:

    src/index.ts
    app.get("/greet", (c) => {  return c.text(    t({      en: "Hello!",      "en-GB": "Hello, mate!",      fr: "Bonjour!",      uk: "Привіт!",    })  );});

    Розширені теми

    Механізм повернення (Fallback)

    Якщо бажана локаль недоступна, функція t повернеться до локалі за замовчуванням, визначеної в конфігурації:

    intlayer.config.ts
    import { Locales, type IntlayerConfig } from "intlayer";const config = {  internationalization: {    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.UKRAINIAN],    defaultLocale: Locales.ENGLISH,  },} satisfies IntlayerConfig;export default config;

    Примусове використання суворого режиму

    Налаштуйте функцію t для забезпечення суворого дотримання оголошених локалей:

    Режим Поведінка
    strict Для всіх оголошених локалей мають бути надані переклади. Відсутність локалей призведе до помилок.
    inclusive Оголошені локалі повинні мати переклади. Відсутність локалей викликає попередження, але вони приймаються.
    loose Приймається будь-яка існуюча локаль, навіть якщо вона не оголошена.

    Інтеграція з TypeScript

    Функція t є типобезпечною при використанні з TypeScript. Визначте типобезпечний об'єкт перекладів:

    src/index.ts
    import { type LanguageContent } from "hono-intlayer";const translations: LanguageContent<string> = {  en: "Good morning!",  fr: "Bonjour!",  uk: "Доброго ранку!",};app.get("/morning", (c) => {  return c.text(t(translations));});

    Поширені помилки та усунення несправностей

    Проблема Причина Рішення
    Функція t не працює Проміжне ПЗ не завантажено Переконайтеся, що app.use("*", intlayer()) додано перед маршрутами.
    Помилка відсутності перекладів Увімкнено суворий режим без усіх мов Надайте всі необхідні переклади.

    Висновок

    Функція t, це потужний інструмент для інтернаціоналізації бекенда. Ефективно використовуючи її, ви можете створити більш інклюзивний та зручний додаток для глобальної аудиторії. Для отримання інформації про розширене використання та детальні параметри конфігурації зверніться до документації.

    Чому Intlayer?