Быстрый старт для AdonisJS

Как настроить компилятор Lingo.dev для AdonisJS

Введение

Lingo.dev Compiler — это инструмент на базе ИИ, который позволяет локализовать приложения на React без внесения изменений в существующие компоненты. Вам нужно лишь настроить несколько параметров, обернуть приложение в провайдер контекста — и всё, ваше приложение локализовано.

В этом руководстве объясняется, как настроить Lingo.dev Compiler с AdonisJS — полнофункциональным веб-фреймворком для Node.js, предназначенным для создания серверных приложений.

Предварительные требования

  • Ваш проект на AdonisJS использует Inertia.js.

Чему вы научитесь

  • Как инициализировать Lingo.dev Compiler в проекте на AdonisJS
  • Как настроить компилятор для совместимости с AdonisJS
  • Как настроить переключатель локалей для смены языков

Шаг 1. Настройка API-ключа

Lingo.dev Compiler использует большие языковые модели (LLM) для локализации приложений с помощью ИИ. Чтобы использовать одну из этих моделей, вам нужен API-ключ от поддерживаемого провайдера.

Чтобы начать как можно быстрее, мы рекомендуем использовать Lingo.dev Engine — нашу собственную платформу, которая предоставляет 10 000 токенов бесплатного ежемесячного использования.

Для настройки API-ключа:

  1. Войдите в Lingo.dev Engine.

  2. Перейдите на страницу Projects.

  3. Нажмите API key > Copy.

  4. Сохраните API-ключ в переменной окружения:

    export LINGODOTDEV_API_KEY="<your_api_key>"

Альтернатива: Пользовательские провайдеры LLM

Вы не обязаны использовать Lingo.dev Engine. Вы можете настроить компилятор для интеграции с рядом пользовательских провайдеров LLM, включая:

  • Groq
  • Google
  • Mistral
  • Ollama
  • OpenRouter

Шаг 2. Установка пакета

Lingo.dev Compiler распространяется как часть npm-пакета lingo.dev. Чтобы установить его, используйте предпочитаемый менеджер пакетов:

npm install lingo.dev

Шаг 3. Инициализация компилятора

Компилятор Lingo.dev интегрируется с Vite и запускается во время сборки. Чтобы подключить его к процессу сборки Vite, внесите следующие изменения в файл vite.config.ts:

  1. Импортируйте компилятор:

    import lingoCompiler from "lingo.dev/compiler";

  2. Инициализируйте компилятор с помощью метода vite:

    const withLingo = lingoCompiler.vite({
  sourceRoot: "inertia",
  lingoDir: "lingo",
  sourceLocale: "en",
  targetLocales: ["es"],
  rsc: false,
  useDirective: false,
  debug: false,
  models: "lingo.dev",
});

    Для совместимости с AdonisJS убедитесь, что:

    • sourceRoot установлен в значение "inertia"
    • rsc установлен в значение false

    Чтобы узнать больше о доступных параметрах, смотрите Опции компилятора.

  3. Объедините конфигурацию компилятора с существующей конфигурацией и экспортируйте её:

    export default withLingo(viteConfig);

С этой конфигурацией Компилятор Lingo.dev будет:

  • Обходить абстрактное синтаксическое дерево (AST) кодовой базы
  • Находить локализуемый контент (например, текст в элементах JSX и определённых значениях атрибутов)
  • Использовать настроенные AI-модели для генерации переводов
  • Сохранять оригинальный и переведённый контент в файл dictionary.js
  • Заменять локализованный контент на плейсхолдеры

Шаг 4. Загрузка локализованного контента

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

  • Загрузку соответствующего словаря на основе предпочтений пользователя по языку
  • Предоставление загруженных переводов вашему приложению через провайдер контекста

На стороне клиента

В файле inertia/app/app.tsx:

  1. Импортируйте компонент LingoProviderWrapper и функцию loadDictionary из lingo.dev/react/client:

    import {
  LingoProviderWrapper,
  loadDictionary,
} from "lingo.dev/react/client";

    Компонент LingoProviderWrapper является провайдером контекста, который заменяет созданные компилятором заполнители на локализованный контент.

    Функция loadDictionary:

    • Получает текущую локаль из cookie lingo-locale
    • Использует локаль "en" по умолчанию, если локаль не определена
    • Загружает локализованный контент из файла dictionary.js

  2. Оберните компонент App в компонент LingoProviderWrapper и передайте в него функцию loadDictionary:

    <LingoProviderWrapper loadDictionary={(locale) => loadDictionary(locale)}>
  <App {...props} />
</LingoProviderWrapper>

На стороне сервера

В файле inertia/app/ssr.tsx повторите те же шаги, чтобы избежать несоответствий при гидратации:

import { LingoProviderWrapper, loadDictionary } from "lingo.dev/react/client";

<LingoProviderWrapper loadDictionary={(locale) => loadDictionary(locale)}>
  <App {...props} />
</LingoProviderWrapper>;

Шаг 5. Настройка переключателя локалей

Чтобы пользователи могли переключаться между локалями, импортируйте LocaleSwitcher из пакета lingo.dev. Это не стилизованный компонент, который:

  • Отображает выпадающий список доступных локалей
  • Позволяет пользователю выбрать предпочитаемую локаль
  • Запоминает локаль пользователя для последующих посещений

Чтобы использовать компонент, вставьте его в любое место вашего приложения и установите свойство locales в массив, содержащий настроенные исходную и целевые локали:

import { LocaleSwitcher } from "lingo.dev/react/client";

<LocaleSwitcher locales={["en", "es"]} />;

Альтернатива: пользовательский переключатель локалей

Вы не обязаны использовать компонент LocaleSwitcher. Вы можете реализовать собственную логику и интерфейс переключения локалей. Единственное требование — читать и записывать активную локаль в cookie lingo-locale.

Шаг 6. Запуск приложения

Чтобы убедиться, что Lingo.dev Compiler настроен правильно:

  1. Запустите сервер разработки:

    npm run dev

  2. Перейдите на localhost:3333.

  3. Используйте компонент LocaleSwitcher, чтобы переключаться между локалями.

Страница должна перезагрузиться и отобразить локализованный контент.

Если вы не используете компонент LocaleSwitcher, альтернативный способ проверить, что локализация работает, — вручную установить cookie lingo-locale.

Если вы используете Google Chrome, выполните следующие действия:

  1. Перейдите в Вид > Разработчик > Инструменты разработчика.
  2. Откройте вкладку Приложение.
  3. В левой панели, в разделе Хранилище, разверните Cookies и выберите URL сайта.
  4. В таблице cookie щелкните правой кнопкой мыши в любом месте и выберите Добавить.
  5. В столбце Имя введите lingo-locale.
  6. В столбце Значение введите нужную локаль (например, es).
  7. Нажмите Enter, чтобы сохранить cookie.
  8. Обновите страницу, чтобы применить cookie.

Дополнительное чтение