Справочник по настройке

Полное описание всех опций конфигурации @lingo.dev/compiler.

Основные параметры

Пример

{
  sourceRoot: "./app",
  lingoDir: ".lingo",
  sourceLocale: "en",
  targetLocales: ["es", "de", "fr", "ja"],
  useDirective: false,
  models: "lingo.dev",
  buildMode: "translate",
}

Опции для разработки

Настройте поведение для разработки через объект dev:

Пример

{
  dev: {
    usePseudotranslator: true, // Fast fake translations
    translationServerStartPort: 60000, // Default port range
  }
}

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

Сохранение локали

Настройте, как будут сохраняться изменения локали:

Пример

{
  localePersistence: {
    type: "cookie",
    config: {
      name: "user-locale",
      maxAge: 31536000, // 1 year
    },
  },
}

Нужна своя система сохранения? Реализуйте Custom Locale Resolvers, чтобы использовать localStorage, параметры URL или базу данных.

Плюрализация

Настройте автоматическое определение плюрализации:

Пример

{
  pluralization: {
    enabled: true,
    model: "groq:llama-3.1-8b-instant", // Fast model for plural detection
  },
}

Как это работает: Компилятор определяет формы плюрализации в вашем тексте (например, «У вас 5 элементов») и преобразует их в ICU MessageFormat ({count, plural, one {1 item} other {# items}}).

Отключите для ускорения: Если не используете плюрализацию, отключите эту функцию, чтобы не делать LLM-запросы.

Провайдеры перевода

Опция models настраивает, какой LLM-провайдер(ы) использовать для перевода.

Простая настройка

Используйте одного провайдера для всех переводов:

{
  models: "lingo.dev" // Recommended: Lingo.dev Engine
}

Расширенная конфигурация

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

{
  models: {
    "en:es": "groq:llama-3.3-70b-versatile", // English to Spanish
    "en:de": "google:gemini-2.0-flash",      // English to German
    "*:fr": "openai:gpt-4o",                 // Any locale to French
    "*:*": "anthropic:claude-3-5-sonnet",    // Fallback for all others
  }
}

Паттерны:

• "source:target": Конкретная пара локалей (например, "en:es")
• "*:target": Любой исходный язык к определённому целевому (например, "*:de")
• "source:*": Конкретный исходный язык к любому целевому (например, "en:*")
• "*:*": Фолбэк для всех пар

Смотрите Поставщики переводов для синтаксиса и настройки API-ключей.

Кастомные промпты для перевода

Настройте промпт для перевода с помощью плейсхолдеров:

{
  prompt: `Translate from {SOURCE_LOCALE} to {TARGET_LOCALE}.
Use a formal tone and preserve all technical terms.
Do not translate brand names or product names.`
}

Доступные плейсхолдеры:

• {SOURCE_LOCALE}: Код исходной локали (например, "en")
• {TARGET_LOCALE}: Код целевой локали (например, "es")

Компилятор добавляет контекст о переводимом тексте (расположение компонента, окружающие элементы) к вашему кастомному промпту.

Переопределение через переменные окружения

Переопределяйте конфигурацию с помощью переменных окружения:

# Override build mode
LINGO_BUILD_MODE=cache-only npm run build

# Set API key
LINGODOTDEV_API_KEY=your_key_here
GROQ_API_KEY=gsk_...
GOOGLE_API_KEY=...
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
MISTRAL_API_KEY=...
OPENROUTER_API_KEY=...

Полный пример

// 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, {
    // Core
    sourceRoot: "./app",
    lingoDir: ".lingo",
    sourceLocale: "en",
    targetLocales: ["es", "de", "fr", "ja"],
    useDirective: false,

    // Build mode
    buildMode: process.env.NODE_ENV === "production" ? "cache-only" : "translate",

    // Models
    models: {
      "en:es": "groq:llama-3.3-70b-versatile",
      "*:*": "lingo.dev",
    },

    // Custom prompt
    prompt: "Translate from {SOURCE_LOCALE} to {TARGET_LOCALE}. Use a professional tone.",

    // Development
    dev: {
      usePseudotranslator: true,
      translationServerStartPort: 60000,
    },

    // Locale persistence
    localePersistence: {
      type: "cookie",
      config: {
        name: "locale",
        maxAge: 31536000,
      },
    },

    // Pluralization
    pluralization: {
      enabled: true,
      model: "groq:llama-3.1-8b-instant",
    },
  });
}

Типы TypeScript

Импортируйте типы конфигурации для типобезопасности:

import type { LingoConfig } from "@lingo.dev/compiler";

const config: LingoConfig = {
  // ...config
};

Часто задаваемые вопросы

Нужно ли настраивать все параметры? Нет. Только sourceLocale и targetLocales обязательны. Остальные имеют разумные значения по умолчанию.

В чём разница между sourceRoot и lingoDir? sourceRoot — это место, где находится ваш исходный код (например, ./app, src). lingoDir — это место хранения метаданных переводов (по умолчанию: .lingo).

Можно ли использовать разные модели для разных локалей? Да. Используйте сопоставление пар локалей в опции models. Смотрите Поставщики переводов.

Нужно ли коммитить .lingo/ в git? Да. Директория .lingo/ содержит метаданные переводов и кэш. Её стоит хранить под версионным контролем вместе с кодом.

Как отключить плюрализацию? Установите pluralization.enabled: false. Это отключит определение форм множественного числа и уменьшит количество обращений к LLM.

Дальнейшие шаги

• Поставщики переводов — настройте LLM-провайдеров
• Режимы сборки — разница между translate и cache-only
• Пользовательские резолверы локалей — настройте определение локали
• Лучшие практики — рекомендуемые конфигурации