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

Альфа

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

Объект конфигурации Lingo.dev Compiler определяет, как ваше React-приложение переводится во время сборки. На этой странице собраны все доступные параметры, их типы, значения по умолчанию и примеры использования.

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

Параметр	Тип	По умолчанию	Описание
`sourceRoot`	`string`	`"src"`	Каталог с компонентами, доступными для перевода. Указывается относительно корня проекта.
`lingoDir`	`string`	`".lingo"`	Каталог для метаданных перевода и файлов кэша.
`sourceLocale`	`string`	обязательно	Код языка исходного контента (например, `"en"`).
`targetLocales`	`string[]`	обязательно	Массив кодов целевых языков (например, `["es", "de", "fr"]`).
`useDirective`	`boolean`	`false`	Если `true`, переводятся только файлы с директивой `'use i18n'`. Если `false`, переводятся все файлы в `sourceRoot`.
`models`	`string \| object`	`"lingo.dev"`	Конфигурация провайдера перевода. Строка задаёт значение по умолчанию для всех пар локалей. Объект сопоставляет пары локалей с конкретными провайдерами.
`prompt`	`string`	`undefined`	Пользовательский системный промпт для переводческой LLM. Поддерживает плейсхолдеры `{SOURCE_LOCALE}` и `{TARGET_LOCALE}`.
`buildMode`	`"translate" \| "cache-only"`	`"translate"`	Определяет, будет ли Compiler генерировать новые переводы или использовать только переводы из кэша.

Параметры для разработки#

Параметры в ключе dev управляют поведением в процессе разработки:

Параметр	Тип	По умолчанию	Описание
`dev.usePseudotranslator`	`boolean`	`false`	Генерирует мгновенные тестовые переводы (например, `[!!! Welcome !!!]`) вместо обращения к LLM. API-ключ не нужен.
`dev.translationServerStartPort`	`number`	`60000`	Начальный порт для локального сервера перевода. Compiler автоматически находит свободный порт в диапазоне 60000-60099.
`dev.translationServerUrl`	`string`	`undefined`	Переопределяет URL сервера перевода. Полезно для нестандартных конфигураций или удалённых серверов перевода.

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

Параметры в localePersistence определяют, как выбранная пользователем локаль сохраняется и извлекается:

Параметр	Тип	По умолчанию	Описание
`localePersistence.type`	`string`	`"cookie"`	Механизм сохранения. Сейчас поддерживается `"cookie"`.
`localePersistence.config.name`	`string`	`"locale"`	Имя cookie, в котором хранится локаль.
`localePersistence.config.maxAge`	`number`	`31536000`	Максимальный срок действия cookie в секундах (по умолчанию — 1 год).

Если вам нужна собственная логика сохранения (localStorage, URL, заголовки), см. Custom Locale Resolvers.

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

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

Параметр	Тип	По умолчанию	Описание
`pluralization.enabled`	`boolean`	`true`	Включает или отключает автоматическое определение плюрализации.
`pluralization.model`	`string`	`"groq:llama-3.1-8b-instant"`	LLM-модель, используемая для определения форм множественного числа в исходном тексте. Рекомендуется более компактная и быстрая модель, поскольку определение — более простая задача, чем перевод.

Подробнее о том, как работает определение множественного числа, см. в разделе Automatic Pluralization.

Переменные окружения#

Переменные окружения переопределяют конфигурацию или дополняют её:

Переменная	Когда требуется	Описание
`LINGO_BUILD_MODE`	Необязательно	Переопределяет параметр конфигурации `buildMode`. Установите значение `"translate"` или `"cache-only"`.
`LINGODOTDEV_API_KEY`	При использовании моделей `"lingo.dev"`	API-ключ для движка локализации Lingo.dev. Получить его можно через `npx lingo.dev@latest login`.
`OPENAI_API_KEY`	При использовании моделей `"openai:*"`	API-ключ OpenAI.
`ANTHROPIC_API_KEY`	При использовании моделей `"anthropic:*"`	API-ключ Anthropic.
`GOOGLE_API_KEY`	При использовании моделей `"google:*"`	API-ключ Google AI.
`GROQ_API_KEY`	При использовании моделей `"groq:*"`	API-ключ Groq.
`MISTRAL_API_KEY`	При использовании моделей `"mistral:*"`	API-ключ Mistral.
`OPENROUTER_API_KEY`	При использовании моделей `"openrouter:*"`	API-ключ OpenRouter.

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

// 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",
    lingoDir: ".lingo",
    sourceLocale: "en",
    targetLocales: ["es", "de", "fr", "ja"],
    useDirective: false,
    models: {
      "*:*": "lingo.dev",
      "*:ja": "anthropic:claude-3-5-sonnet",
    },
    prompt: "Translate UI text from {SOURCE_LOCALE} to {TARGET_LOCALE}. Keep it concise.",
    buildMode: "translate",
    dev: {
      usePseudotranslator: true,
      translationServerStartPort: 60000,
    },
    localePersistence: {
      type: "cookie",
      config: {
        name: "locale",
        maxAge: 31536000,
      },
    },
    pluralization: {
      enabled: true,
      model: "groq:llama-3.1-8b-instant",
    },
  });
}

Что дальше#

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

Все поддерживаемые LLM-провайдеры и сопоставление пар локалей

Режимы сборки

Процессы для dev, CI и production

Custom Locale Resolvers

Как реализовать собственное определение локали

Лучшие практики

Рекомендуемые подходы для production