Назначение

Плагин для Obsidian, который:

• Извлекает текст из PDF-страниц (через текстовый слой, внешний Python-скрипт),
• Отправляет текст на перевод через выбранного провайдера (OpenRouter, OpenAI, Gemini, Ollama, custom),
• Отображает перевод поверх исходного PDF в виде позиционированного оверлея,
• Сохраняет координаты и текст перевода в markdown-файлах для повторного использования,
• Позволяет экспортировать PDF со вшитым переводом (требуется Python + PyMuPDF).

Организация хранения переводов

Для каждого PDF-файла создаётся файл Имя_файла.translations.md.
Формат:

• Frontmatter:

  • pdf-source: '[[путь/к/файлу.pdf]]' – связь с исходным PDF.

• В теле страницы: для каждого блока перевода присутствует комментарий %% {JSON-метаданные} %%, а следующей строкой – переведённый текст (с <br> вместо переводов строк).

Метаданные JSON включают:

• r – относительный прямоугольник (left, top, width, height) в долях от размера текстового слоя (0..1).
• page – номер страницы.
• ot – оригинальный текст.
• fs, ff, ofs – размер шрифта, семейство, исходные размеры (опционально).

Хранилище может быть общим для всех PDF (задаётся в настройках) либо находиться в папке с каждым PDF. Плагин поддерживает автоматическое обновление ссылок при переименовании/перемещении файлов.

Три режима извлечения макета (Layout Engine)

1. Internal (DOM Text Layer)

• Использует текстовый слой, создаваемый PDF.js.
• Не требует внешних зависимостей.
• Работает, если PDF имеет машинный текст (не скан).

2. External Python Script

• Запускает скрипт layout_engine.py (PyMuPDF).
• Требует установки Python и PyMuPDF.
• Возвращает JSON с блоками текста и их абсолютными координатами на странице.

API-провайдеры для перевода

• OpenRouter
• OpenAI
• Google Gemini
• Ollama
• Custom – любой HTTP-эндпоинт с настраиваемыми заголовками и шаблоном тела запроса.

Для каждого провайдера хранятся: ключ API, модель, температура, флаг enableReasoning (для моделей с extended thinking).

Команды плагина (доступны в палитре команд)

Команда	Действие
Translate and add overlay to current PDF page	Анализ и перевод текущей страницы, создание оверлея.
Save current PDF overlay	Сохранить оверлей текущей страницы в .translations.md.
Refresh current PDF overlay	Перерисовать оверлей (после изменения настроек шрифта или масштаба).
Clear current PDF overlay	Удалить оверлей с текущей страницы.
Toggle PDF overlay visibility	Показать/скрыть все оверлеи.
Toggle BBox Edit Mode	Режим выделения и группового редактирования блоков (контекстное меню).
Translate multiple pages…	Перевести несколько страниц подряд (с сохранением).
Retranslate using saved overlay layout…	Использовать сохранённую разметку, но выполнить повторный перевод (например, с другой моделью).
Export PDF with translations	Экспорт PDF со вшитым переводом (только десктоп, требует PyMuPDF).
Rebuild PDF-to-translation file map	Перестроить внутренний кэш соответствий PDF ↔ .translations.md.
Clean unused translation files…	Найти и удалить файлы переводов, чей исходный PDF удалён из хранилища.

Основные настройки

Находятся в разделе Настройки → PDF Text Translator.

• API Provider – выбор провайдера и его параметров (ключ, модель, температура, reasoning).
• Layout Engine – выбор режима извлечения макета (внутренний, Python, OCR‑API). Для Python и OCR‑API – дополнительные настройки путей, параметров скриншота, промптов.
• Language – исходный и целевой язык.
• Translation Mode – пакетный (batch) или последовательный.
• Visual Settings – масштаб шрифта оверлея (outputFontSizeScale), высота строки (outputLineHeight), прозрачность.
• Storage Location – папка для хранения .translations.md (пусто – рядом с PDF).
• Custom Prompts – шаблоны системных промптов для перевода (можно отключить, используя специализированный шаблон Gemma для ветеринарной тематики).

Требования к внешним компонентам

• External Python Engine / PDF Export:
  • Python 3.8+
  • pip install PyMuPDF
  • В настройках указать абсолютный путь к python и к скриптам layout_engine.py / pdf_export.py.
• I:
  • API-ключ у выбранного провайдера, основной - OpenRouter.
• Ollama (любой режим):
  • Запущенный сервер Ollama (обычно http://localhost:11434).

Правила использования

1. Откройте PDF в Obsidian.
2. Настройте API и layout engine в соответствии с типом PDF.
3. Выполните команду перевода текущей страницы.
4. При необходимости сохраните оверлей (команда Save current PDF overlay).
5. Для экспорта PDF с переводом выполните соответствующую команду (предварительно установив PyMuPDF и указав пути).
6. Для пакетного перевода нескольких страниц используйте команду Translate multiple pages….
7. Для очистки неиспользуемых файлов переводов – Clean unused translation files….

Плагин автоматически загружает сохранённые оверлеи при прокрутке PDF и перерисовывает их при изменении масштаба.