Решение проблем¶
Распространённые ошибки, что они означают, и как их исправить.
Ошибки настройки¶
"LLM is not configured"¶
Вы ещё не добавили API-ключ. Откройте десктопное приложение → Настройки → LLM → вставьте ключ. См. LLM-провайдеры для полного руководства.
AUTH_ERROR¶
API-ключ LLM неверный или истёк.
- Gemini — сгенерируйте новый ключ на https://aistudio.google.com/apikey, вставьте заново в Настройки → LLM.
- Custom-провайдер — проверьте, что ключ валиден (curl-ните
endpoint вручную с тем же заголовком
Authorization: Bearer …). Если endpoint переехал, обновите также поле Endpoint API.
QUOTA_ERROR¶
Вы достигли лимита бесплатного уровня или платного плана.
- Бесплатный уровень Gemini — суточная квота запросов варьируется по моделям (см. https://ai.google.dev/gemini-api/docs/rate-limits). Подождите день или перейдите на платный.
- OpenAI / другие — проверьте dashboard биллинга. Многие провайдеры имеют "spend caps", которые приостанавливают запросы при достижении.
MODEL_NOT_FOUND¶
Имя модели, которое вы выбрали, недоступно.
- Custom-провайдеры — убедитесь, что модель есть в списке Models, разделённом запятыми, в Настройки → LLM.
- Встроенный список Gemini — переключитесь на документированную модель в Настройки → LLM → Дефолтная модель Gemini.
VISION_NOT_SUPPORTED¶
Вы выбрали non-vision модель и попытались перевести изображение /
сканированный PDF. Переключитесь на модель, чьё имя содержит flash,
pro или vision (например gpt-4o для OpenAI, любой текущий
вариант Gemini Flash или Pro для Gemini).
Ошибки аудио / видео¶
FFMPEG_NOT_FOUND¶
FFmpeg отсутствует в PATH. См. Настройка FFmpeg для команды установки на вашей ОС.
MCP-сервер обрамляет это как: "FFmpeg is required to decode this audio/video file but is not installed or not on PATH."
Live-страница не показывает субтитры¶
- Неверный источник аудио — откройте Настройки → Live → Источник аудио и убедитесь, что он соответствует тому, что вы хотите (Микрофон / Система / Оба).
- Микрофон отключён — проверьте звуковые настройки ОС; приложение использует устройство ввода по умолчанию.
- Системное аудио не настроено — см. Захват системного аудио для шагов loopback на macOS / Windows.
Голосовой вывод тих / пуст¶
- ElevenLabs без ключа — страница Voice показывает дружелюбный диалог pre-flight; если он пропущен, файл может содержать пустые байты. Проверьте Настройки → Service → ElevenLabs API key.
- Сетевая ошибка Edge TTS — Edge TTS требует интернет; если ваш
firewall блокирует
speech.platform.bing.com, переключитесь на ElevenLabs, Google Cloud TTS, или Piper TTS (полностью офлайн).
Диалог "Piper voice not installed"¶
Страницы Voice / Dubbing / Translate Text проверяют pre-flight, что голос Piper для целевого языка на диске, прежде чем стартует worker. Если нет, вы увидите модал с кнопкой Открыть настройки.
Чтобы загрузить голос:
- Нажмите Открыть настройки в диалоге (или откройте Настройки → Голос вручную).
- Убедитесь, что TTS-метод установлен в Piper TTS.
- Нажмите Загрузить голоса для открытия диалога библиотеки голосов.
- Найдите строку целевого языка, затем нажмите Female voice или Male voice рядом. Голоса — ONNX-файлы ~25–60 МБ, скачиваемые с HuggingFace; одноразово на язык.
- Закройте диалог и перезапустите задачу перевода / voice / dub.
Если целевого языка нет в списке, у него нет покрытия Piper — движок тихо возвращается к Edge TTS во время синтеза, так что вам не нужно ничего загружать. 13 языков без Piper-голосов сегодня: белорусский, бенгальский, китайский (традиционный), хорватский, эстонский, иврит, японский, кхмерский, корейский, литовский, малайский, монгольский, тайский.
Страница Живой перевод — единственное место, которое не покажет этот диалог — прерывание live-стрима модалом было бы хуже fallback'а, так что случаи отсутствующего голоса там тихо идут на Edge TTS.
Ошибки перевода документа¶
Перевод PDF падает на конкретной странице¶
PDF используют per-page checkpointing — успешные страницы не
переделываются. Упавшая страница логирует stack в app.log;
распространённые виновники:
- Страница — скан без слоя текста, и OCR не настроен. Настройте Настройки → OCR (см. OCR-движки).
- Страница содержит сложный математический layout, который LLM испортил. Попробуйте более сильную модель (Pro вместо Flash).
Перевод Office ломает форматирование¶
- Современные форматы (
.docx,.xlsx,.pptx) — форматирование сохраняется per-run через HTML round-trip. Если видите блуждающие теги<b>в выводе, LLM не закрыл их — перезапустите с более сильной моделью. - Legacy-форматы (
.doc,.xls,.ppt) — включите Настройки → Перевод → Auto-convert legacy для гораздо лучшей точности. Pipeline сначала конвертирует в.docx, переводит, конвертирует обратно.
Очередь перевода останавливается посреди батча¶
Закройте приложение и проверьте базу данных:
sqlite3 ~/.local/share/ai-translate/translator.db \
"SELECT id, status, error_code, file_name FROM history WHERE status NOT IN ('Done', 'Failed') ORDER BY created_at DESC LIMIT 10;"
Строки Translating, к которым не обращались несколько минут,
означают, что worker тихо упал. Перезапустите десктопное приложение —
оно автоматически возобновляет задачи Pending / Translating при
запуске.
Кросс-функциональные проблемы¶
Несколько файлов одновременно тихо переводятся как один¶
Бросайте по одному файлу за раз, ИЛИ проверьте колонку Files в заголовке очереди — она должна показывать количество, которое вы бросили. Лимит 100 файлов показывает уведомление при превышении.
Sidebar показывает спиннер вечно¶
Указывает, что worker всё ещё помечен как работающий. Закройте приложение чисто (без SIGKILL) — autouse cleanup hooks сбрасывают флаги. Если SIGKILL оставил состояние застрявшим, очистите DB-workers вручную:
sqlite3 ~/.local/share/ai-translate/translator.db \
"UPDATE history SET status='Failed', error_code=99 WHERE status IN ('Pending', 'Translating');"
Где логи?¶
| ОС | Путь |
|---|---|
| Linux | ~/.local/state/log/ai-translate/app.log |
| macOS | ~/Library/Logs/ai-translate/app.log |
| Windows | %LOCALAPPDATA%\ai-translate\logs\app.log |
Логи всегда захватывают DEBUG+ независимо от уровня консоли. Вывод
консоли по умолчанию INFO+; передайте --verbose в CLI, чтобы
зеркалировать полный файловый лог в stdout.
Всё ещё застряли?¶
- См. FAQ для вопросов уровня дизайна.
- Заведите issue на
https://github.com/cadic2603/ai-translate/issues с: ОС, версия
Python, упавшая команда, релевантный фрагмент
app.log, и описание того, что вы ожидали.