"use i18n";

Директива "use i18n" позволяет выполнять локализацию React-компонентов файл за файлом без необходимости рефакторинга существующего кода. Подобно "use client" или "use server", вы просто добавляете её в начало файла, чтобы автоматически локализовать весь переводимый контент в этом компоненте.

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

Как это работает

Когда вы добавляете "use i18n" в начало React-файла, компилятор Lingo.dev автоматически:

  1. Сканирует весь файл на наличие переводимого контента
  2. Извлекает текст JSX и переводимые атрибуты
  3. Генерирует переводы с использованием настроенной AI-модели
  4. Встраивает локализованные версии на этапе сборки
  5. Сохраняет горячую замену модулей (Hot Module Replacement) для удобной разработки

Директива работает на уровне файла, обрабатывая всё в пределах границ компонента, оставляя остальную часть вашего приложения без изменений.

Включение директивы

Чтобы использовать директиву "use i18n", включите её в конфигурации компилятора:

{
  sourceLocale: "en",
  targetLocales: ["es", "fr", "de"],
  useDirective: true, // Включить директиву "use i18n"
  models: "lingo.dev", // Вариант 1: Движок Lingo.dev
  // models: {
  //   "*:*": "groq:qwen/qwen3-32b", // Вариант 2: GROQ
  //   "*:*": "google:gemini-2.0-flash", // Вариант 2: Google AI
  //   "*:*": "openrouter:mistralai/mistral-small-24b-instruct-2501", // Вариант 2: OpenRouter
  //   "*:*": "ollama:mistral-small3.1", // Вариант 2: Ollama
  //   "*:*": "mistral:mistral-small-latest", // Mistral
  // },
}

Примечание: Если параметр useDirective установлен в false (по умолчанию), компилятор Lingo.dev обрабатывает все файлы так, как если бы в них была директива "use i18n" в начале. Установка useDirective: true позволяет вам управлять локализацией файлов индивидуально.

Настройка модели: Вы можете использовать либо движок Lingo.dev с упрощённым синтаксисом (models: "lingo.dev"), либо модели от альтернативных поставщиков LLM с конкретным сопоставлением моделей (например, models: { "*:*": "groq:qwen/qwen3-32b" }, см. выше). Движок автоматически выбирает оптимальные модели для каждой языковой пары.

Основное использование

Добавьте директиву в начало любого файла React-компонента:

"use i18n";

import React from "react";

export function WelcomeCard() {
  return (
    <div className="card">
      <h2>Добро пожаловать в наше приложение!</h2>
      <p>
        Начните с изучения наших функций и узнайте, что делает нашу
        платформу особенной.
      </p>
      <button>Начать</button>
    </div>
  );
}

Примечание: Добавьте "use i18n" в начало файла, который рендерит <LingoProvider>.

Вот и всё! Компонент теперь автоматически будет отображаться на выбранном пользователем языке без каких-либо изменений в коде.

Работает с существующими директивами

Директива "use i18n" естественно работает вместе с другими директивами React, которые вы уже используете:

"use client";
"use i18n";

export function InteractiveComponent() {
  const [count, setCount] = useState(0);

  return (
    <div>
      <h1>Счётчик кликов</h1>
      <p>Вы нажали {count} раз(а)</p>
      <button onClick={() => setCount(count + 1)}>Нажми меня!</button>
    </div>
  );
}

"use server";
"use i18n";

export async function ServerComponent() {
  const data = await fetchData();

  return (
    <div>
      <h1>Контент, рендеренный на сервере</h1>
      <p>Этот контент рендерится на сервере и локализуется во время сборки</p>
    </div>
  );
}

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

Рабочий процесс разработки

1. Постепенная миграция

Начните с добавления директивы в отдельные компоненты:

// До: Компонент только на английском
export function Header() {
  return <h1>My Application</h1>;
}

// После: Многоязычный компонент с одной строкой
("use i18n");

export function Header() {
  return <h1>My Application</h1>;
}

2. Горячая замена модулей

Директива бесшовно работает с HMR. Когда вы изменяете текст в компоненте с "use i18n", переводы обновляются мгновенно в вашем браузере:

"use i18n";

export function StatusMessage() {
  return (
    <div>
      {/* Измените этот текст, и он мгновенно обновится на всех языках */}
      <p>Ваши изменения успешно сохранены!</p>
    </div>
  );
}

3. Подход файл за файлом

Идеально подходит для крупных кодовых баз, где вы хотите локализовать постепенно:

src/
├── components/
│   ├── Header.tsx          // ✅ "use i18n" - локализовано
│   ├── Navigation.tsx      // ✅ "use i18n" - локализовано
│   ├── ProductCard.tsx     // ✅ "use i18n" - локализовано
│   ├── Footer.tsx          // ⏳ Ещё не локализовано
│   └── Sidebar.tsx         // ⏳ Ещё не локализовано

Преимущества

Директива "use i18n" делает локализацию настолько простой, что достаточно добавить одну строку в ваши React-компоненты. Она разработана для зрелых проектов, которые требуют постепенной локализации.

Следующие шаги