# doc-html-translate

**Языки README:** [English](README.md) · **Русский** · [Українська](README_UK.md)

Преобразует EPUB, PDF, MOBI, AZW3, FB2, RTF, TXT, Markdown, HTML и комиксы CBZ/CBR/CB7/CBT в чистый
локальный HTML под Windows - с необязательным переводом через Google Cloud или локальную модель Ollama.
Аккаунт в облаке не нужен, лишних церемоний нет, и да, это по-прежнему работает на обычной Windows в 2026 году.

## Ссылки проекта

- Сайт: https://serzhyale.github.io/doc-html-translate/
- Репозиторий: https://github.com/SerZhyAle/doc-html-translate
- Последний релиз: https://github.com/SerZhyAle/doc-html-translate/releases/latest
- Расширение для браузера: https://chromewebstore.google.com/detail/nmcckamdocainafmmompkbmelkpbnmic
- Страница автора: https://sza.od.ua
- Почта: sza@ukr.net

## Издания

doc-html-translate существует в нескольких видах - берите тот, что удобнее; конвертер у всех один:

- **CLI** - `doc-html-translate.exe`, конвертер командной строки и обработчик файловых ассоциаций Windows.
- **Настольное приложение (GUI)** - `doc-html-ui.exe`, окно поверх того же конвертера, открывающее все
  параметры CLI (выбор файла, перетаскивание, диалог настроек, переключатель обработчика по умолчанию -
  строго по желанию, выключен по умолчанию).
- **Приложение из Microsoft Store** - то же настольное приложение (GUI + CLI) в виде пакета MSIX:
  подписано Store, обновляется само, скачивать вручную ничего не нужно. Под MSIX флаг `-register` ничего
  не делает (ассоциации приходят из манифеста пакета). Подробности упаковки: [`msix/README.md`](msix/README.md).
- **Расширение для браузера** - расширение Chromium MV3, которое перерисовывает документы (PDF, EPUB,
  MOBI, AZW3, FB2, RTF, TXT, Markdown, локальный HTML и комиксы CBZ/CBT) в чистый HTML прямо в браузере,
  чтобы встроенный **перевод страницы** работал на них без установки приложения. Установка -
  [Chrome Web Store](https://chromewebstore.google.com/detail/nmcckamdocainafmmompkbmelkpbnmic); исходный код
  и документация - в [`extension/`](extension/).
- **Сайт и документация** - [лендинг](https://serzhyale.github.io/doc-html-translate/), многоязычная
  документация и отдельная [страница расширения](https://serzhyale.github.io/doc-html-translate/extension.html).

Настольное приложение и расширение независимы и дополняют друг друга: приложение превращает файл в
локальную папку с HTML, которая остаётся у вас; расширение делает ту же переверстку прямо во вкладке.
Оба опираются на одну «бесплатную» идею - отдать браузеру чистый HTML и позволить его встроенному
переводчику сделать остальное.

## Возможности

- Конвертация: EPUB, PDF, TXT, Markdown, FB2, RTF, HTML, MOBI, AZW3
- Чтение комиксов: архивы CBZ / CBR / CB7 / CBT открываются постранично, текст в репликах распознаётся
  (OCR) и накладывается на страницу переводимыми плашками - так что «Перевести страницу» в Chrome
  работает и на репликах. OCR включается автоматически (иначе в комиксе просто нечего переводить)
- Перевод отдельного изображения: передайте PNG/JPG/JPEG/WebP/GIF/BMP/TIFF - приложение распознает текст
  и положит переводимые плашки поверх картинки (дальше работает встроенный перевод страницы Chrome - то
  же поведение, что и у расширения). Для OCR нужен движок `tesseract` (см. `-ocr-lang`)
- Локальный HTML с созданной навигацией и оглавлением
- Настоящее многоуровневое оглавление: берётся авторское `toc.ncx` (EPUB2), `nav.xhtml` (EPUB3) или
  закладки PDF; при их отсутствии сканируются заголовки (`h1`-`h6`) и расставляются якоря. Отображается
  сворачиваемым деревом с глубокими ссылками; глубина настраивается (`-toc-depth`)
- Необязательный перевод:
  - Google Cloud Translation API (`-google`)
  - Локальная Ollama (`-ollama`)
  - Жёсткий ограничитель расходов для платных движков: `-max-cost N` отменяет отправку, если оценка в
    долларах превышает `N`
- Удобство чтения встроено в готовый HTML (без сервера, работает по `file://`):
  - Темы чтения - Light / Sepia / Dark / Night, выбор запоминается
  - Размер шрифта и гарнитура (с засечками / без засечек / моноширинная)
  - Продолжение с того места, где остановились
- Интерфейс на 13 языках: `en ru uk de it es fr pt ar hi bn ur zh` - флаг `-ui-lang <код>` в CLI,
  переключатель языка в GUI и в расширении. По умолчанию берётся язык системы (в расширении - язык
  браузера). Язык интерфейса не меняет язык документа: атрибут `<html lang>` готовой страницы остаётся
  языком книги, иначе Chrome перестал бы предлагать перевод страницы.

## Установка

Сборка из исходников:

```powershell
go build -o build/doc-html-translate.exe ./cmd/doc-html-translate
```

Или скриптами проекта:

```powershell
./scripts/build.ps1
```

## Загрузка приложения

Готовые сборки для Windows x64 публикуются на странице релизов:

- https://github.com/SerZhyAle/doc-html-translate/releases/latest

В каждом релизе есть:

- `doc-html-translate-setup-<версия>.exe` - **универсальный установщик** (x86 + x64, для текущего
  пользователя, без прав администратора) - самый простой путь: ставит GUI + CLI, с необязательными
  пунктами «Открыть с помощью», «Преобразовать в HTML» в контекстном меню и задачей для расширения
- `doc-html-translate-<версия>-windows-x64.exe` - консольная утилита (portable)
- `doc-html-ui-<версия>-windows-x64.exe` - настольное приложение (portable)
- `doc-html-translate-<версия>-windows-x64.zip` - полный архив (обе программы + LICENSE + README)

Установщик работает и на 32-, и на 64-битной Windows и не требует прав администратора (ставит в профиль
пользователя). Portable-варианты остаются для работы без установки.

Установка через winget (portable-сборка):

```powershell
winget install SerZhyAle.DocHtmlTranslate
```

## Быстрый старт

```powershell
# Обычный сценарий: конвертировать и открыть в браузере (без перевода, пока не заданы -google или -ollama)
doc-html-translate.exe "book.epub"

# Конвертация + перевод Google
doc-html-translate.exe -google "book.epub"

# Конвертация + перевод Ollama
doc-html-translate.exe -ollama -ollama-model gemma3:12b "book.epub"

# Явное направление перевода
doc-html-translate.exe -src en -dst ru "book.epub"

# Свой каталог для результата
doc-html-translate.exe -folder "D:\out" "book.pdf"

# Полная пересборка, даже если результат уже есть
doc-html-translate.exe -force "book.epub"

# Ограничить платный перевод: отменить, если оценка превышает $2.00
doc-html-translate.exe -google -max-cost 2 "book.epub"

# Интерфейс на другом языке
doc-html-translate.exe -ui-lang de "book.epub"

# Стать обработчиком поддерживаемых типов по умолчанию (по умолчанию выключено)
doc-html-translate.exe -register

# Отменить это - отпустить ассоциацию (пункт контекстного меню и «Открыть с помощью» остаются)
doc-html-translate.exe -unregister
```

## Самый быстрый бесплатный сценарий (рекомендуется)

Для многих самый удобный путь такой:

1. Откройте файл приложением или выполните команду по умолчанию:

```powershell
doc-html-translate.exe "book.epub"
```

2. Дайте программе открыть `index.html` в Chrome.
3. Используйте встроенный перевод страницы Chrome на свой язык.

Флаг `-notranslate` по-прежнему есть, но это лишь явная запись того же поведения по умолчанию.

Почему так делают чаще всего:

- Бесплатно (никакого биллинга Google Cloud и счетов, которых ждёшь с содроганием)
- Быстро начать (одна команда, без церемоний)
- Удобное чтение в браузере с навигацией по страницам

## Флаги

| Флаг | По умолчанию | Описание |
|------|--------------|----------|
| `-register` | `false` | Стать обработчиком по умолчанию в HKCU для всех поддерживаемых типов (выключено; при первом запуске добавляется только пункт контекстного меню и предлагается этот режим) |
| `-unregister` | `false` | Отпустить ассоциацию по умолчанию (пункт «Преобразовать в HTML» и «Открыть с помощью» остаются) |
| `-register-openwith` | `false` | Добавить программу в список «Открыть с помощью» и пункт «Преобразовать в HTML», не делая её обработчиком по умолчанию (GUI `doc-html-ui` делает это сам при запуске) |
| `-notranslate` | `false` | Только конвертация, без перевода |
| `-noopen` | `false` | Не открывать браузер после конвертации |
| `-google` | `false` | Перевод через Google Cloud Translation API |
| `-ollama` | `false` | Перевод через локальную Ollama |
| `-free` | `false` | Синоним `-ollama` |
| `-ollama-model` | `gemma3:12b` | Имя модели Ollama |
| `-ollama-parallel` | `1` | Число параллельных запросов |
| `-ollama-ctx` | `8192` | Размер контекста Ollama |
| `-max-cost` | `0` | Отменить платный перевод до отправки, если оценка в долларах превышает N (`0` - без ограничения) |
| `-ocr` | `false` | Распознавать текст на изображениях документа и накладывать его переводимым HTML (нужен Tesseract) |
| `-ocr-lang` | (из `-src`) | Язык(и) OCR, например `eng` или `eng+rus` (по умолчанию из `-src`, иначе `eng`) |
| `-ocr-langs` | `false` | Показать установленные и доступные языки OCR и выйти |
| `-ocr-download` | пусто | Скачать языковой пакет OCR (например, `-ocr-download rus`) и выйти |
| `-split` | `5000` | Делить страницы каждые N символов (`0` отключает деление) |
| `-toc-depth` | `0` | Глубина вложенности оглавления в `index.html` (`0` - без ограничения, `1` - только главы) |
| `-multipage` | `false` | Делать несколько HTML-страниц с оглавлением вместо одной страницы по умолчанию |
| `-folder` | пусто | Родительский каталог для результата |
| `-force` | `false` | Извлекать и переводить заново, даже если результат уже есть |
| `-ui-lang` | пусто | Язык интерфейса: `en ru uk de it es fr pt ar hi bn ur zh` (пусто - язык системы) |
| `-v` | `false` | Подробный вывод |
| `-src` | `en` | Исходный язык |
| `-dst` | `ru` | Язык перевода |
| `-version` | `false` | Показать версию и выйти |

## Ключ Google API

Для `-google` ключ берётся из первого доступного источника:

1. `google_api.key` рядом с исполняемым файлом (обычная сборка), затем
2. `%LOCALAPPDATA%\doc-html-translate\google_api.key` (доступный на запись путь пользователя, который
   работает и при установке из Microsoft Store/MSIX, где каталог программы только для чтения).

Пример содержимого файла:

```text
AIzaSy...ваш_ключ...
```

В `doc-html-ui` отметьте **Google Translate**, чтобы появилось поле ключа - вставьте ключ и нажмите
**Save**, он будет записан по пути выше (править файлы вручную не нужно).

Если пригодного ключа нет, приложение пишет предупреждение и пропускает перевод - лучше сказать прямо,
чем гадать.

## Наложение OCR (`-ocr`)

Текст, впечатанный в изображения документа (сканы, комиксы, скриншоты), не виден ни одному переводчику
текста. С флагом `-ocr` приложение распознаёт этот текст и накладывает его настоящим, переводимым HTML
поверх каждой картинки - так что и собственный перевод (`-google` / `-ollama`), и «Перевести страницу» в
браузере переводят и картинки тоже. Работает для форматов, чьи изображения доходят до этапа HTML.

Для OCR нужен внешний движок `tesseract`. Если его нет, конвертация не прерывается - просто изображения
остаются без текстового слоя.

## Особенности поведения

- Запуск без аргументов открывает сценарий регистрации, а не конвертацию.
- Если рядом уже есть `index.html`, результат переиспользуется - пока не передан `-force`.
- Язык интерфейса не влияет на язык готового документа.

## Разработка

Скрипты в `scripts/`: `build.ps1`, `build-ui.ps1`, `test.ps1`, `lint.ps1`, `check.ps1`.
Руководство для агентов и участников - [AGENTS.md](AGENTS.md).

## Лицензия

MIT - см. [LICENSE](LICENSE).

---

**О переводах интерфейса.** Интерфейс доступен на 13 языках. Английский, русский и украинский вычитаны
автором; остальные десять переведены машинно и не вычитаны - исправления присылайте на sza@ukr.net.