Переведите ваш бэкенд на AdonisJS с помощью Intlayer | Интернационализация (i18n)

adonis-intlayer, это мощный пакет интернационализации (i18n) для приложений AdonisJS, разработанный для того, чтобы сделать ваши бэкенд-сервисы доступными во всем мире, предоставляя локализованные ответы на основе предпочтений клиента.

Практические примеры использования

• Отображение ошибок бэкенда на языке пользователя: Когда происходит ошибка, отображение сообщений на родном языке пользователя улучшает понимание и снижает раздражение. Это особенно полезно для динамических сообщений об ошибках, которые могут отображаться в компонентах фронтенда, таких как тосты или модальные окна.

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

• Отправка многоязычных писем: Будь то транзакционные письма, маркетинговые кампании или уведомления, отправка писем на языке получателя может значительно повысить вовлеченность и эффективность.

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

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

Интернационализируя бэкенд, ваше приложение не только уважает культурные различия, но и лучше соответствует потребностям глобального рынка, что является ключевым шагом в масштабировании ваших услуг по всему миру.

Начало работы

See Application Template on GitHub.

Установка

Чтобы начать использовать adonis-intlayer, установите пакет с помощью npm:

npx intlayer init --interactive

флаг --interactive не является обязательным. Используйте intlayer-cli init, если вы являетесь ИИ-агентом.

Эта команда определит вашу среду и установит необходимые пакеты. Например:

npm install intlayer adonis-intlayer

Настройка

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

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

const config: IntlayerConfig = {
  internationalization: {
    locales: [
      Locales.ENGLISH,
      Locales.RUSSIAN,
      Locales.JAPANESE,
      Locales.FRENCH,
      Locales.KOREAN,
      Locales.CHINESE,
      Locales.SPANISH,
      Locales.GERMAN,
      Locales.ARABIC,
      Locales.ITALIAN,
      Locales.ENGLISH_UNITED_KINGDOM,
      Locales.PORTUGUESE,
      Locales.HINDI,
      Locales.TURKISH,
      Locales.POLISH,
      Locales.INDONESIAN,
      Locales.VIETNAMESE,
      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",
      ru: "Пример возвращаемого контента на русском языке",
      "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 или ./app) и соответствуют расширению файла объявления контента (по умолчанию .content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}).

Для получения более подробной информации обратитесь к документации по объявлению контента.

Настройка приложения AdonisJS

Настройте ваше приложение AdonisJS для использования adonis-intlayer.

Регистрация промежуточного ПО (middleware)

Сначала вам нужно зарегистрировать промежуточное ПО intlayer в вашем приложении.

router.use([() => import("adonis-intlayer/middleware")]);

Определение маршрутов

import router from "@adonisjs/core/services/router";
import { t, getIntlayer, getDictionary } from "adonis-intlayer";
import indexContent from "../app/index.content";

router.get("/t_example", async () => {
  return t({
    en: "Example of returned content in English",
    fr: "Exemple de contenu renvoyé en français",
    ru: "Пример возвращаемого контента на русском языке",
    "es-ES": "Ejemplo de contenido devuelto en español (España)",
    "es-MX": "Ejemplo de contenido devuelto en español (México)",
  });
});

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

router.get("/getDictionary_example", async () => {
  return getDictionary(indexContent).exampleOfContent;
});

Функции

adonis-intlayer экспортирует несколько функций для обработки интернационализации в вашем приложении:

• t(content, locale?): Базовая функция перевода.
• getIntlayer(key, locale?): Получение контента по ключу из ваших словарей.
• getDictionary(dictionary, locale?): Получение контента из конкретного объекта словаря.
• getLocale(): Получение текущей локали из контекста запроса.

Использование в контроллерах

import type { HttpContext } from "@adonisjs/core/http";
import { t } from "adonis-intlayer";

export default class ExampleController {
  async index({ response }: HttpContext) {
    return response.send(
      t({
        en: "Hello from controller",
        ru: "Привет из контроллера",
      })
    );
  }
}

Совместимость

adonis-intlayer полностью совместим с:

• react-intlayer для приложений React
• next-intlayer для приложений Next.js
• vite-intlayer для приложений Vite

Он также беспрепятственно работает с любым решением для интернационализации в различных средах, включая браузеры и API-запросы. Вы можете настроить промежуточное ПО для обнаружения локали через заголовки или куки:

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;

По умолчанию adonis-intlayer будет интерпретировать заголовок Accept-Language для определения предпочтительного языка клиента.

Для получения дополнительной информации о настройке и расширенных темах посетите нашу документацию.

Настройка TypeScript

adonis-intlayer использует широкие возможности TypeScript для улучшения процесса интернационализации. Статическая типизация TypeScript гарантирует, что каждый ключ перевода учитывается, снижая риск отсутствия переводов и улучшая поддерживаемость.

Убедитесь, что автоматически сгенерированные типы (по умолчанию в ./types/intlayer.d.ts) включены в ваш файл tsconfig.json.

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

Расширение VS Code

Чтобы улучшить ваш опыт разработки с Intlayer, вы можете установить официальное расширение Intlayer VS Code.

Установить из VS Code Marketplace

Это расширение предоставляет:

• Автодополнение для ключей перевода.
• Обнаружение ошибок в реальном времени для отсутствующих переводов.
• Встроенный предварительный просмотр переведенного контента.
• Быстрые действия для легкого создания и обновления переводов.

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

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

Рекомендуется игнорировать файлы, созданные Intlayer. Это позволяет избежать их фиксации в вашем Git-репозитории.

Для этого вы можете добавить следующие инструкции в ваш файл .gitignore:

# Игнорировать файлы, созданные Intlayer
.intlayer

Часто задаваемые вопросы