Устранение неполадок

Типичные проблемы и их решения при использовании @lingo.dev/compiler.

Проблемы с установкой

"Не удаётся найти модуль '@lingo.dev/compiler'"

Причина: Пакет не установлен или установлен некорректно.

Решение:

npm install @lingo.dev/compiler
# or
pnpm install @lingo.dev/compiler

Проверьте установку:

ls node_modules/@lingo.dev/compiler

"Модуль не найден: Не удаётся найти '@lingo.dev/compiler/react'"

Причина: Импорт из неправильного пути или устаревший пакет.

Решение:

  1. Проверьте строку импорта:

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

  2. Переустановите пакет:

    rm -rf node_modules
npm install

Проблемы с конфигурацией

"Config должен быть async-функцией" (Next.js)

Причина: Конфиг Next.js не обёрнут в async-функцию.

Решение:

// Wrong
export default withLingo(nextConfig, {...});

// Correct
export default async function (): Promise<NextConfig> {
  return await withLingo(nextConfig, {...});
}

"sourceLocale обязателен"

Причина: В конфиге отсутствует sourceLocale.

Решение:

{
  sourceLocale: "en", // Required
  targetLocales: ["es", "de"],
}

"targetLocales должен быть массивом"

Причина: targetLocales не является массивом или он пустой.

Решение:

{
  targetLocales: ["es", "de"], // Must be array with at least one locale
}

Проблемы с переводом

Переводы не отображаются

Симптомы: Текст отображается только на исходном языке.

Причины и решения:

1. LingoProvider не добавлен или находится не в том месте

// Wrong - too low in tree
export default function Page() {
  return (
    <LingoProvider>
      <Content />
    </LingoProvider>
  );
}

// Correct - in root layout
export default function RootLayout({ children }) {
  return (
    <LingoProvider>
      <html>
        <body>{children}</body>
      </html>
    </LingoProvider>
  );
}

2. Отсутствуют переводы в метаданных Проверьте .lingo/metadata.json:

{
  "translations": {
    "abc123": {
      "locales": {
        "es": "..." // Should have translation
      }
    }
  }
}

Если пусто или отсутствует, запустите с buildMode: "translate":

npm run dev # or build

3. Режим сборки только кэш, но переводы не закэшированы

# Generate translations first
LINGO_BUILD_MODE=translate npm run build

# Then use cache-only
LINGO_BUILD_MODE=cache-only npm run build

Все переводы отображаются как "[!!! ...]"

Причина: Включён псевдопереводчик.

Решение:

{
  dev: {
    usePseudotranslator: false, // Disable for real translations
  }
}

Перезапустите dev-сервер.

Часть текста не переводится

Возможные причины:

1. Динамический контент или пропсы

// Not translated (yet) - string in variable
const title = "Welcome";
<h1>{title}</h1>

// Translated - string in JSX
<h1>Welcome</h1>

Решение: Компилятор дорабатывается для поддержки строковых литералов. Пока что вставляйте текст прямо в JSX.

2. Текст в атрибутах требует особой обработки

// Translated automatically
<img alt="Logo" />
<button aria-label="Close" />

// May need explicit handling
<div custom-attr="Some text" /> // Not translated unless configured

3. useDirective включён Если useDirective: true, файлы без 'use i18n' не переводятся.

Решение: Добавьте директиву:

'use i18n';

export function Component() { ... }

Проблемы со сборкой

«Отсутствуют переводы для локали X»

Причина: buildMode: "cache-only", но переводы отсутствуют.

Решение:

  1. Сгенерируйте переводы:

    npm run dev # or
LINGO_BUILD_MODE=translate npm run build

  2. Зафиксируйте .lingo/metadata.json

  3. Повторите с cache-only

«Не удалось сгенерировать перевод»

Возможные причины:

1. Неверный API-ключ

# Check .env file
cat .env | grep API_KEY

Проверьте, что API-ключ для вашего провайдера введён верно.

2. Проблемы с сетью Проверьте соединение с API:

curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

3. Ограничение по количеству запросов Замедлите генерацию переводов или обновите тариф API.

4. Неверная конфигурация модели

// Wrong
{
  models: {
    "*:*": "invalid-provider:model",
  }
}

// Correct
{
  models: {
    "*:*": "groq:llama-3.3-70b-versatile",
  }
}

Сборка идёт медленно

Возможные причины:

1. Генерируется много переводов Первая сборка с новым текстом идёт медленно. Последующие сборки проходят быстро (используется кэш).

2. Псевдопереводчик отключён в режиме разработки

{
  dev: {
    usePseudotranslator: true, // Enable for fast development
  }
}

3. Включено множественное число без необходимости

{
  pluralization: {
    enabled: false, // Disable if not using plural forms
  }
}

Проблемы с HMR

HMR не работает

Причина: расположение LingoProvider или конфиг фреймворка.

Решения:

Next.js: Убедись, что LingoProvider находится в корневом layout, а не во вложенных.

Vite: Убедись, что lingoCompilerPlugin стоит перед плагином react():

plugins: [
  lingoCompilerPlugin({...}), // Before react plugin
  react(),
]

Сброс состояния при смене перевода

Причина: перезагрузка страницы из-за смены локали.

Ожидаемое поведение: setLocale() по умолчанию перезагружает страницу для применения новой локали.

Чтобы избежать перезагрузки: реализуй кастомный persistLocale без перезагрузки:

// .lingo/locale-resolver.client.ts
export function persistLocale(locale: string): void {
  localStorage.setItem("locale", locale);
  // Don't call window.location.reload()
}

Примечание: для этого нужно заранее загрузить переводы для всех локалей.

Проблемы с API/авторизацией

"API-ключ недействителен"

Решения:

1. Проверь имя переменной окружения

# Lingo.dev Engine
LINGODOTDEV_API_KEY=...

# OpenAI
OPENAI_API_KEY=sk-...

# Anthropic
ANTHROPIC_API_KEY=sk-ant-...

2. Убедись, что API-ключ активен Зайди в дашборд провайдера и проверь статус ключа.

3. Перезапусти dev-сервер после добавления ключа

npm run dev

Переменные окружения загружаются при запуске.

«Ошибка аутентификации» (Lingo.dev)

Возможные решения:

1. Повторная аутентификация

npx lingo.dev@latest login

2. Ввести API-ключ вручную

# Add to .env
LINGODOTDEV_API_KEY=your_key_here

Получите ключ в настройках проекта на lingo.dev.

Браузер блокирует авторизацию

Причина: Браузер Brave или расширения блокируют аутентификацию.

Решение: Вручную добавьте API-ключ в .env:

LINGODOTDEV_API_KEY=...

Проблемы с сервером

«Не удалось запустить сервер перевода»

Причина: Все порты 60000–60099 заняты.

Возможные решения:

1. Указать другой диапазон портов

{
  dev: {
    translationServerStartPort: 61000,
  }
}

2. Завершить существующие процессы

# Find processes using ports
lsof -i :60000-60099

# Kill process
kill -9 <PID>

«Порт 60000 уже используется»

Причина: Другой процесс использует этот порт.

Решение: Сервер автоматически ищет следующий свободный порт. Проверьте консоль для актуального порта:

[lingo] Translation server started on port 60001

Если все порты заняты, смотрите «Не удалось запустить сервер перевода» выше.

Ошибки типов

«Свойство 'data-lingo-override' не существует»

Причина: TypeScript не распознаёт этот атрибут.

Решение: Добавьте объявление типа:

// global.d.ts
declare namespace React {
  interface HTMLAttributes<T> {
    "data-lingo-override"?: Record<string, string>;
  }
}

Или используйте кавычки:

<div {"data-lingo-override"}={{ es: "..." }}>
  Text
</div>

«Type error: Config must return Promise»

Причина: Конфиг Next.js неправильно типизирован.

Решение:

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, {...});
}

Проблемы в продакшене

Переводы отсутствуют в продакшене

Возможные причины:

1. .lingo/ не закоммичен

git add .lingo/
git commit -m "chore: add translations"
git push

2. Неправильный режим сборки продакшена

// Should be cache-only in production
{
  buildMode: "cache-only",
}

3. CI не сгенерировал переводы Проверьте логи CI — убедитесь, что переводы были сгенерированы и закоммичены.

Разные переводы в dev и prod

Причина: В продакшене включён псевдопереводчик.

Решение:

{
  dev: {
    usePseudotranslator: process.env.NODE_ENV === "development", // Only in dev
  }
}

Где искать помощь

Если всё ещё застряли:

  1. Проверьте логи — ищите ошибки в консоли
  2. Проверьте .lingo/metadata.json — проверьте структуру и содержимое
  3. Проверьте с псевдопереводчиком — чтобы изолировать проблемы с API
  4. Проверьте GitHub issues — github.com/lingodotdev/lingo.dev/issues
  5. Спросите в Discord — discord.gg/lingo

Когда просите о помощи, указывайте:

  • Сообщение об ошибке (полный stack trace)
  • Конфигурацию (next.config.ts или vite.config.ts)
  • Версии пакетов (npm list @lingo.dev/compiler)
  • Шаги для воспроизведения

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

Вопрос: Нужны ли API-ключи в продакшене? Ответ: Нет, с buildMode: "cache-only". Переводы заранее генерируются в CI.

Вопрос: Почему не собирается билд? Ответ: Проверьте сообщение об ошибке. Частые причины: отсутствуют переводы, неверный API-ключ, проблемы с сетью.

Вопрос: Можно ли использовать несколько LLM-провайдеров? Ответ: Да, с помощью сопоставления пар локалей в конфиге models.

Вопрос: Как тестировать без затрат на API? Ответ: Включите usePseudotranslator: true в режиме разработки.

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