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

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

Введение

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

В этом руководстве объясняется, как настроить Lingo.dev Compiler с Vite.

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

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

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

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

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

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

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

  2. Перейдите на страницу Проекты.

  3. Нажмите API-ключ > Копировать.

  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: "src",
  lingoDir: "lingo",
  sourceLocale: "en",
  targetLocales: ["es"],
  rsc: false,
  useDirective: false,
  debug: false,
  models: "lingo.dev",
});

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

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

    export default withLingo(viteConfig);

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

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

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

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

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

В файле src/main.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 />
</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:5173.

  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.

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