Lingo.dev - Automated AI localization for web & mobile apps

Введение

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

В этом руководстве объясняется, как настроить Lingo.dev Compiler с The Epic Stack — фреймворком для веб-приложений полного стека от Кента С. Доддса, построенным на основе Remix.

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

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

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

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

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

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

Войдите в Lingo.dev Engine.
Перейдите на страницу Проекты.
Нажмите API key > Copy.
Сохраните 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:

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

import lingoCompiler from "lingo.dev/compiler";

Инициализируйте компилятор с помощью метода vite:
```
const withLingo = lingoCompiler.vite({
  sourceRoot: "app",
  lingoDir: "lingo",
  sourceLocale: "en",
  targetLocales: ["es"],
  rsc: false,
  useDirective: false,
  debug: false,
  models: "lingo.dev",
});
```
Для совместимости с The Epic Stack убедитесь, что:
- sourceRoot установлен в значение "app"
- rsc установлен в значение false
Чтобы узнать больше о доступных опциях, смотрите Опции компилятора.

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

export default defineConfig((config) => {
  const configWithSentry = {
    ...viteConfig,
    plugins: [
      ...viteConfig.plugins!.filter(Boolean),
      MODE === "production" && process.env.SENTRY_AUTH_TOKEN
        ? sentryReactRouter(sentryConfig, config)
        : null,
    ].filter(Boolean),
  };

  return withLingo(configWithSentry);
});

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

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

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

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

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

Загрузка словаря

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

Импортируйте функцию loadDictionary из lingo.dev/react/react-router:
```
import { loadDictionary } from "lingo.dev/react/react-router";
```
Эта функция:
- Получает текущую локаль из cookie lingo-locale
- Использует значение по умолчанию "en", если локаль не определена
- Загружает локализованный контент из файла dictionary.js
Вызовите функцию loadDictionary из функции loader:
```
const lingoDictionary = await loadDictionary(request);
```

Верните словарь как часть данных загрузчика:

return data(
  {
    user,
    requestInfo: {
      hints: getHints(request),
      origin: getDomainUrl(request),
      path: new URL(request.url).pathname,
      userPrefs: {
        theme: getTheme(request),
      },
    },
    ENV: getEnv(),
    toast,
    honeyProps,
    lingoDictionary,
  },
  {
    headers: combineHeaders(
      { "Server-Timing": timings.toString() },
      toastHeaders,
    ),
  },
);

Предоставление переводов

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

Импортируйте компонент LingoProvider из lingo.dev/react/client:
```
import { LingoProvider } from "lingo.dev/react/client";
```
Этот компонент является провайдером контекста React, который заменяет созданные компилятором заполнители на локализованный контент.
В компоненте Layout получите данные из загрузчика данных:
```
const data = useLoaderData<typeof loader | null>();
```

Оберните приложение в компонент LingoProvider:

<LingoProvider>{/* Существующий код приложения */}</LingoProvider>

Передайте загруженный словарь в компонент:

<LingoProvider dictionary={data?.lingoDictionary}>
  {/* Существующий код приложения */}
</LingoProvider>

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

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

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

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

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

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

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

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

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

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

Запустите сервер разработки:
```
npm run dev
```
Перейдите на localhost:3000.
Используйте компонент LocaleSwitcher, чтобы переключаться между локалями.

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

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

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

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

Дополнительные материалы

Чтобы понять, как работает компилятор, см. Как это работает.
Чтобы узнать, как настроить компилятор, см. Параметры компилятора.

Краткое руководство по The Epic Stack