Инструменты разработки

@lingo.dev/compiler предоставляет инструменты для разработки, чтобы ускорить ваш рабочий процесс и снизить расходы на API во время разработки.

Псевдопереводчик

Псевдопереводчик генерирует мгновенные фейковые переводы без обращений к API.

Включить

{
  dev: {
    usePseudotranslator: true,
  }
}

Что он делает

Преобразует текст с визуальными маркерами:

Оригинал:

Welcome to our app

Псевдоперевод:

[!!! Ẃëļċöṁë ẗö öüř äþþ !!!]

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

  1. Мгновенная обратная связь — Без API-запросов, без ожидания
  2. Видно, что переводится — Сразу видно, какой текст подлежит переводу
  3. Тест разной длины — Псевдопереводы примерно на 30% длиннее, что помогает выявить проблемы с версткой
  4. Ноль затрат — Не тратятся кредиты API

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

Псевдопереводчик:

  • Добавляет маркеры ([!!! и !!!])
  • Заменяет символы на акцентированные (a → ä, e → ë)
  • Увеличивает длину текста примерно на 30%
  • Сохраняет интерполяции ({name} остаётся {name})
  • Сохраняет структуру HTML

Пример с интерполяциями:

<p>Hello {name}, you have {count} items</p>
// Becomes: [!!! Ḧëļļö {name}, ÿöü ḧävë {count} ïẗëṁṡ !!!]

Когда использовать

Во время разработки:

  • Начальная настройка и интеграция
  • Тестирование верстки с разной длиной текста
  • Отладка проблем с переводом
  • Быстрая итерация интерфейса

Когда НЕ использовать:

  • Для проверки качества реального перевода
  • Для тестирования форматирования под конкретную локаль
  • Для финального QA перед релизом

Отключите для настоящих переводов

{
  dev: {
    usePseudotranslator: false,
  }
}

Перезапустите dev-сервер, чтобы сгенерировать настоящие переводы с помощью вашего настроенного LLM-провайдера.

Сервер переводов

Сервер переводов генерирует переводы по запросу во время разработки.

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

Когда вы запускаете npm run dev:

  1. Компилятор запускает локальный HTTP-сервер
  2. Сервер автоматически находит свободный порт (60000–60099)
  3. Ваше приложение запрашивает переводы у сервера
  4. Сервер генерирует переводы (псевдо или реальные)
  5. Переводы кэшируются в .lingo/metadata.json

Конфигурация

{
  dev: {
    translationServerStartPort: 60000, // Starting port
    translationServerUrl: "http://localhost:60000", // Custom URL (advanced)
  }
}

Диапазон портов: Сервер поочередно пробует порты с 60000 по 60099, пока не найдет свободный.

Ручной запуск (для продвинутых)

Вы можете запустить сервер переводов вручную:

npx @lingo.dev/compiler translate-server \
  --port 60000 \
  --config ./lingo.config.json

Это удобно для:

  • Отдельного запуска сервера переводов вне процесса сборки
  • Отладки проблем с переводами
  • Кастомных CI/CD-процессов

Поддержка WebSocket

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

Когда переводы обновляются, сервер отправляет изменения подключённым клиентам через WebSocket.

Виджет разработки

Виджет разработки — это оверлей в браузере для редактирования переводов в реальном времени.

Возможности

  • Редактирование переводов в браузере — не нужно править файлы
  • Просмотр контекста — исходный текст, расположение компонента
  • Обновления в реальном времени — изменения применяются сразу через WebSocket
  • Смена локали — быстрое тестирование разных локалей

Включить

{
  dev: {
    enableWidget: true, // Coming soon
  }
}

Статус: Виджет разработки сейчас активно разрабатывается и будет доступен в одном из следующих релизов.

Как это будет работать

  1. Нажмите горячую клавишу (например, Cmd+Shift+L)
  2. Появится оверлей виджета
  3. Кликните по любому переведённому тексту для редактирования
  4. Измените переводы для нужных локалей
  5. Сохраните — изменения синхронизируются через WebSocket
  6. Переводы мгновенно обновятся в .lingo/metadata.json

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

Рекомендуемая настройка

1. Начальная настройка:

{
  dev: {
    usePseudotranslator: true, // Fast feedback
  }
}

Запусти npm run dev, чтобы сразу увидеть псевдопереводы.

2. Тестирование верстки:

Псевдопереводы помогают выявить проблемы с версткой:

  • Переполнение текста
  • Обрезанные подписи
  • Неправильное выравнивание
  • Ошибки адаптивности

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

3. Проверка реального перевода:

{
  dev: {
    usePseudotranslator: false,
  }
}

Сгенерируй реальные переводы, чтобы оценить качество. Проверь:

  • Точность перевода
  • Тональность и уровень формальности
  • Корректность технических терминов
  • Сохранность названия бренда

4. Тонкая настройка:

Используй data-lingo-override для точной настройки:

<h1 data-lingo-override={{ es: "Bienvenido", de: "Willkommen" }}>
  Welcome
</h1>

5. Сборка для продакшена:

{
  buildMode: "cache-only",
}

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

Отладка

Проверь сервер переводов

Сервер переводов пишет логи в консоль:

[lingo] Translation server started on port 60001
[lingo] Pseudotranslator: enabled
[lingo] Watching for changes...

Проверь файл метаданных

Открой .lingo/metadata.json, чтобы посмотреть кэшированные переводы:

{
  "translations": {
    "abc123": {
      "source": "Welcome to our app",
      "locales": {
        "es": "[!!! Ẃëļċöṁë ẗö öüř äþþ !!!]",
        "de": "[!!! Ẃëļċöṁë ẗö öüř äþþ !!!]"
      }
    }
  }
}

Если псевдопереводчик выключен, увидишь реальные переводы.

Конфликты портов

Если все порты с 60000 по 60099 заняты:

{
  dev: {
    translationServerStartPort: 61000, // Use different range
  }
}

Или вручную остановите процессы, использующие эти порты:

# Find process using port 60000
lsof -i :60000

# Kill process
kill -9 <PID>

Советы по производительности

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

Реальные переводы медленнее — используйте их только для проверки качества:

  • Генерация первого перевода: действует задержка API
  • Последующие сборки: переводы кэшируются, работают быстро

Сервер переводов легковесный — минимальная нагрузка на память и процессор.

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

Нужно ли запускать сервер переводов вручную? Нет. Он запускается автоматически при запуске npm run dev.

Можно ли использовать псевдопереводчик в продакшене? Нет. Псевдопереводчик только для разработки. В продакшене всегда используются реальные переводы из .lingo/metadata.json.

Почему виджет для разработки ещё недоступен? Он активно разрабатывается. Следите за обновлениями в релизах на GitHub.

Можно ли настраивать псевдопереводы? Пока нет. Псевдопереводчик использует фиксированный алгоритм, оптимизированный для визуализации переводимого текста.

Работают ли псевдопереводы со всеми наборами символов? Да. Псевдопереводчик корректно обрабатывает Unicode, включая эмодзи, CJK-символы и RTL-языки.

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