Руководство по миграции

Альфа

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

В этом руководстве описан переход с прежнего пакета Compiler lingo.dev на актуальный пакет @lingo.dev/compiler. В новом пакете используется scoped-имя в npm, упрощённый API, интеграция Vite через плагин и новая директория .lingo/ для метаданных.

Кратко об изменениях#

Область	Было (`lingo.dev`)	Стало (`@lingo.dev/compiler`)
Имя пакета	`lingo.dev`	`@lingo.dev/compiler`
Интеграция с Next.js	Прямое изменение конфигурации	Асинхронная обёртка `withLingo()`
Интеграция с Vite	Ручная настройка	`lingoCompilerPlugin`
LingoProvider	Требовался проп `loadDictionary`	Пропсы не нужны
Директория метаданных	`lingo/`	`.lingo/`
Opt-in директива	Требовался `'use i18n'`	Необязательно (по умолчанию переводится всё)
Импорты	`from "lingo.dev/react"`	`from "@lingo.dev/compiler/react"`

Пошаговая миграция#

Замените пакет

Удалите старый пакет и установите новый:

bash

npm uninstall lingo.dev
npm install @lingo.dev/compiler

Обновите импорты

Замените все пути импорта:

// Before
import { LingoProvider, useLingoContext } from "lingo.dev/react";

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

Обновите конфигурацию Next.js (если нужно)

Теперь конфигурация Next.js должна быть асинхронной функцией:

// Before
import { withLingo } from "lingo.dev/next";
const nextConfig = {};
export default withLingo(nextConfig, { /* options */ });

// After
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",
  });
}

Асинхронная обёртка обязательна. Синхронный export приведёт к ошибке сборки. Подробнее см. в разделе Интеграция с Next.js.

Обновите конфигурацию Vite (если нужно)

Замените любую ручную настройку на lingoCompilerPlugin:

// 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"],
      models: "lingo.dev",
    }),
    react(), // Must come AFTER lingoCompilerPlugin
  ],
});

Упростите LingoProvider

Проп loadDictionary больше не нужен. Compiler теперь автоматически загружает словарь:

tsx

// Before
import { LingoProvider } from "lingo.dev/react";

<LingoProvider loadDictionary={loadDictionary}>
  <App />
</LingoProvider>

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

<LingoProvider>
  <App />
</LingoProvider>

Перенесите директорию метаданных

Переименуйте директорию метаданных с lingo/ на .lingo/:

bash

mv lingo/ .lingo/

Обновите ваш .gitignore, если в нём указано старое имя директории. Директорию .lingo/ нужно закоммитить в систему контроля версий.

Обновите директивы 'use i18n' (необязательно)

В новом пакете 'use i18n' больше не обязателен. По умолчанию переводятся все файлы в sourceRoot. Если вы хотите сохранить opt-in поведение, задайте useDirective: true в конфигурации:

{
  useDirective: true, // Keep requiring 'use i18n' in each file
}

Если вы удалите useDirective (или зададите ему значение false), то сможете также убрать директивы 'use i18n' из файлов — все файлы в sourceRoot будут переводиться автоматически.

Пересоберите и проверьте

Запустите dev-сервер и убедитесь, что переводы отображаются:

bash

npm run dev

Проверьте, что:

Псевдопереводчик добавляет маркеры [!!! ... !!!] (если он включён)
Все ранее переведённые строки по-прежнему работают
Файл .lingo/metadata.json создан или обновлён

Что дальше#

Настройка

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

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

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

Интеграция с Next.js

Детали миграции для Next.js

Vite + React

Детали миграции для Vite

Эта страница была полезной?

Руководство по миграции

Альфа

Кратко об изменениях#

Область	Было (`lingo.dev`)	Стало (`@lingo.dev/compiler`)
Имя пакета	`lingo.dev`	`@lingo.dev/compiler`
Интеграция с Next.js	Прямое изменение конфигурации	Асинхронная обёртка `withLingo()`
Интеграция с Vite	Ручная настройка	`lingoCompilerPlugin`
LingoProvider	Требовался проп `loadDictionary`	Пропсы не нужны
Директория метаданных	`lingo/`	`.lingo/`
Opt-in директива	Требовался `'use i18n'`	Необязательно (по умолчанию переводится всё)
Импорты	`from "lingo.dev/react"`	`from "@lingo.dev/compiler/react"`

Пошаговая миграция#

Замените пакет

Удалите старый пакет и установите новый:

bash

npm uninstall lingo.dev
npm install @lingo.dev/compiler

Обновите импорты

Замените все пути импорта:

// Before
import { LingoProvider, useLingoContext } from "lingo.dev/react";

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

Обновите конфигурацию Next.js (если нужно)

Теперь конфигурация Next.js должна быть асинхронной функцией:

// Before
import { withLingo } from "lingo.dev/next";
const nextConfig = {};
export default withLingo(nextConfig, { /* options */ });

// After
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",
  });
}

Обновите конфигурацию Vite (если нужно)

Замените любую ручную настройку на lingoCompilerPlugin:

// 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"],
      models: "lingo.dev",
    }),
    react(), // Must come AFTER lingoCompilerPlugin
  ],
});

Упростите LingoProvider

Проп loadDictionary больше не нужен. Compiler теперь автоматически загружает словарь:

tsx

// Before
import { LingoProvider } from "lingo.dev/react";

<LingoProvider loadDictionary={loadDictionary}>
  <App />
</LingoProvider>

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

<LingoProvider>
  <App />
</LingoProvider>

Перенесите директорию метаданных

Переименуйте директорию метаданных с lingo/ на .lingo/:

bash

mv lingo/ .lingo/

Обновите директивы 'use i18n' (необязательно)

{
  useDirective: true, // Keep requiring 'use i18n' in each file
}

Пересоберите и проверьте

Запустите dev-сервер и убедитесь, что переводы отображаются:

bash

npm run dev

Проверьте, что:

Псевдопереводчик добавляет маркеры [!!! ... !!!] (если он включён)
Все ранее переведённые строки по-прежнему работают
Файл .lingo/metadata.json создан или обновлён

Что дальше#

Настройка

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

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

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

Интеграция с Next.js

Детали миграции для Next.js

Vite + React

Детали миграции для Vite

Эта страница была полезной?