Быстрый старт

Добавьте мультиязычную поддержку в своё React-приложение меньше чем за 5 минут.

Необходимые условия

  • Node.js 18+
  • React-приложение на Next.js (App Router) или Vite

Установка

pnpm install @lingo.dev/compiler

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

Next.js

Сделайте ваш конфиг асинхронным и оберните его в withLingo:

// next.config.ts
import type { NextConfig } from "next";
import { withLingo } from "@lingo.dev/compiler/next";

const nextConfig: NextConfig = {};

export default async function (): Promise<NextConfig> {
  return await withLingo(nextConfig, {
    sourceRoot: "./app",
    sourceLocale: "en",
    targetLocales: ["es", "de", "fr"],
    models: "lingo.dev",
    dev: {
      usePseudotranslator: true, // Fake translations for development
    },
  });
}

Vite

Добавьте плагин Lingo в конфиг Vite:

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

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

Настройка провайдера

Next.js

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

// app/layout.tsx
import { LingoProvider } from "@lingo.dev/compiler/react";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <LingoProvider>
      <html>
        <body>{children}</body>
      </html>
    </LingoProvider>
  );
}

Vite

Обёрните приложение в LingoProvider в entry point:

// 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>
);

Аутентификация

Компилятор по умолчанию использует движок Lingo.dev для переводов.

Вариант 1: Движок Lingo.dev (рекомендуется)

Зарегистрируйтесь на lingo.dev и выполните аутентификацию:

npx lingo.dev@latest login

Пользователям Windows: Если npx lingo.dev не запускается в вашей среде:

  1. Установите пакет: npm install lingo.dev@latest
  2. Используйте npx lingo вместо этого (например, npx lingo login)

Это сохранит ваш API-ключ локально. Бесплатного тарифа Hobby достаточно для большинства проектов.

Проблемы с авторизацией? Если браузер блокирует процесс входа, добавьте API-ключ вручную в .env:

LINGODOTDEV_API_KEY=your_key_here

API-ключ можно найти в настройках проекта Lingo.dev.

Вариант 2: Прямое подключение LLM-провайдера

Можно напрямую использовать любого поддерживаемого LLM-провайдера. Обновите конфиг:

{
  models: {
    "*:*": "groq:llama-3.3-70b-versatile",
    // or "google:gemini-2.0-flash"
    // or "openai:gpt-4o"
    // or "anthropic:claude-3-5-sonnet"
  }
}

Добавьте соответствующий API-ключ в .env:

GROQ_API_KEY=your_key
# or GOOGLE_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY

Смотрите Провайдеры переводов для всех поддерживаемых провайдеров.

Запуск dev-сервера

Запустите dev-сервер:

npm run dev

Компилятор будет:

  1. Сканировать ваш JSX на наличие переводимого текста
  2. Генерировать псевдопереводы (фейковые переводы, чтобы увидеть, что переводится)
  3. Вставлять их в ваши компоненты
  4. Сохранять метаданные в .lingo/metadata.json

Зачем нужны псевдопереводы? Они мгновенные (без API-запросов), показывают, что именно переводится, и помогают тестировать интерфейс с разной длиной текста — и всё это без расхода API-кредитов.

Тест перевода

Добавьте простой компонент:

export function Welcome() {
  return (
    <div>
      <h1>Welcome to our app</h1>
      <p>This text will be translated automatically</p>
    </div>
  );
}

Изменять код не нужно — текст автоматически извлекается и переводится.

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

Дайте пользователям возможность менять язык:

"use client"; // For Next.js

import { useLingoContext } from "@lingo.dev/compiler/react";

export function LanguageSwitcher() {
  const { locale, setLocale } = useLingoContext();

  return (
    <select value={locale} onChange={(e) => setLocale(e.target.value)}>
      <option value="en">English</option>
      <option value="es">Español</option>
      <option value="de">Deutsch</option>
      <option value="fr">Français</option>
    </select>
  );
}

Генерация реальных переводов

Когда будете готовы к реальным переводам, обновите конфиг:

{
  dev: {
    usePseudotranslator: false, // Disable fake translations
  }
}

Перезапусти dev-сервер. Теперь компилятор будет генерировать реальные AI-переводы для любого нового или изменённого текста.

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

Частые вопросы

Нужно ли отмечать каждую переводимую строку? Нет. Компилятор сам определяет текст в JSX. Если хочешь включить ручной режим, задай useDirective: true и добавь 'use i18n' в начало файлов, которые хочешь переводить.

А как быть с динамическим контентом или пропсами? Компилятор автоматически обрабатывает строковые атрибуты вроде alt, aria-label и placeholder. Для динамического текста используй шаблонный синтаксис: <p>Hello {name}</p> работает как надо.

Можно ли настроить отдельные переводы? Да. Используй атрибут data-lingo-override:

<h1 data-lingo-override={{ es: "Bienvenido", de: "Willkommen" }}>
  Welcome
</h1>

Как закоммитить переводы? Закоммить директорию .lingo/ в систему контроля версий. В ней метаданные и кэшированные переводы — их можно и нужно версионировать вместе с кодом.

Что дальше