Vite + React

Альфа

Compiler от Lingo.dev находится на стадии альфа-версии. Он нестабилен, не рекомендуется для использования в production, а API могут меняться от релиза к релизу.

Compiler от Lingo.dev интегрируется с Vite через lingoCompilerPlugin — плагин для Vite, который преобразует React-компоненты во время сборки и внедряет в них переводы. Он полностью поддерживает Hot Module Replacement, поэтому в процессе разработки переводы обновляются мгновенно.

Что понадобится#

Требования

Vite 5+ с React
Node.js 18+
Установленный @lingo.dev/compiler

Установка#

bash

pnpm install @lingo.dev/compiler

Настройка vite.config.ts#

Добавьте lingoCompilerPlugin в конфигурацию Vite. Плагин нужно разместить перед плагином react() — это обязательный порядок, потому что компилятор должен преобразовать JSX до того, как его обработает React-плагин.

// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { lingoCompilerPlugin } from "@lingo.dev/compiler/vite";

export default defineConfig({
  plugins: [
    lingoCompilerPlugin({
      sourceRoot: "src",
      sourceLocale: "en",
      targetLocales: ["es", "de", "fr", "ja"],
      models: "lingo.dev",
      dev: {
        usePseudotranslator: true,
      },
    }),
    react(),
  ],
});

Порядок плагинов имеет значение

Если lingoCompilerPlugin стоит после react(), React-плагин сначала обработает JSX, и компилятор не сможет распознать текст для перевода. Всегда ставьте плагин Lingo первым в массиве plugins.

Добавьте LingoProvider#

Оберните корневой компонент приложения в LingoProvider в entry-файле:

tsx

// src/main.tsx
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { LingoProvider } from "@lingo.dev/compiler/react";
import App from "./App";

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <LingoProvider>
      <App />
    </LingoProvider>
  </StrictMode>
);

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

Hot Module Replacement#

Плагин интегрируется с системой HMR в Vite. Когда вы редактируете текст для перевода в компоненте:

Измените исходный текст

Измените любой текст в JSX — например, замените заголовок с "Добро пожаловать" на "С возвращением".

Compiler обнаруживает изменение

Плагин перехватывает HMR-обновление, определяет изменённую строку и генерирует новый перевод (или псевдоперевод в режиме разработки).

Браузер обновляется мгновенно

Переведённый компонент перерисовывается без полной перезагрузки страницы. Метаданные перевода в .lingo/metadata.json обновляются на диске.

Конфигурация sourceRoot#

Параметр sourceRoot определяет, какие файлы Compiler сканирует в поиске текста для перевода. Для стандартного проекта на Vite + React:

{
  sourceRoot: "src",
}

Структура проекта	Рекомендуемый sourceRoot
Стандартная (`src/`)	`"src"`
Монорепозиторий с общими пакетами	`"."` (корень проекта)
Пользовательская директория	Путь к директории с вашими компонентами

Для крупных кодовых баз более узкий sourceRoot помогает сократить время сборки. Если переводы нужны только в определённых файлах, включите useDirective: true и добавьте 'use i18n' в эти файлы. См. Структура проекта.

Пример структуры проекта#

text

my-vite-app/
  src/
    main.tsx          # LingoProvider wraps <App />
    App.tsx           # Translatable components
    components/
      Header.tsx      # Automatically scanned
      Footer.tsx      # Automatically scanned
  .lingo/
    metadata.json     # Translation cache (commit this)
  vite.config.ts      # lingoCompilerPlugin configured here

Что дальше#

Настройка

Полное руководство по настройке с аутентификацией

Конфигурация — Справочник

Все параметры конфигурации

Переключение локали

Добавьте в приложение переключатель языка

Инструменты разработки

Псевдопереводчик и dev-сервер