# doc-html-translate

**Мови README:** [English](README.md) · [Русский](README_RU.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.