# PageSync Translate

Translate books and papers into Chinese with **page-aligned bilingual side-by-side reading**, **formula-safe LaTeX handling**, and **glossary control** — then read original and translation locked together, scrolling in sync.

中文说明见下方 [中文简介](#中文简介)。

## Why

Existing translators produce a separate Chinese copy of a note. PageSync Translate is built for reading imported English books and papers inside Obsidian:

- **Page alignment** — documents with page markers (`[p.23]` etc.) are translated page by page; the reading view shows aligned page dividers on both sides and lets you jump to any original page.
- **Formulas never break** — LaTeX (`$$…$$`, `$…$`), code blocks, wikilinks and images are masked into placeholders before the engine sees them and restored after, with automatic validation and retry when the model drops one.
- **Glossary control** — keep domain terms in English or force a specific translation via a markdown glossary; the plugin re-validates every block and retries when a "keep" term gets translated.
- **Locked side-by-side view** — a dedicated view renders original and translation in two panes with block-level synchronized scrolling, plus an optional one-page-at-a-time paged mode.
- **Selection translation** — select any word or sentence for a dictionary-style popup, and add the term to the glossary in one click.
- **Whole-book background translation** — queue a file or an entire folder, with cost estimate before starting, incremental caching (only new/edited paragraphs are re-translated), pause/resume, and failure retry.
- **PDF import** — bring a PDF in as page-marked markdown. Text mode extracts the text layer (fast); vision mode renders each page to an image and asks a vision model to transcribe formulas as LaTeX **and** translate in one pass — the reliable fix for formula-heavy papers.
- **Interleaved export** — generate a single bilingual note (original quoted above, translation below) that fits your existing vault conventions.

## Setup

1. Enable the plugin, open **Settings → PageSync Translate**.
2. Pick a provider and enter your own API key:
   - **OpenAI-compatible** (default) — works with OpenAI, DeepSeek, Moonshot Kimi, Zhipu, SiliconFlow, Ollama and any `/chat/completions` endpoint (set Base URL + Model).
   - **Anthropic Claude** or **Google Gemini** — both support the vision mode used by PDF import.
3. Optional: set the **page marker preset** matching how your sources mark pages, and point the **glossary file** at an existing note.

The interface is bilingual — **Interface language** offers 中文 / English / both side by side / follow Obsidian's locale. 界面支持中英文切换（设置最顶部「界面语言」：中文 / English / 双语同显 / 跟随 Obsidian）。Use the **Test** buttons next to the model fields to verify provider, key and model before translating.

## Usage

| Command | What it does |
| --- | --- |
| Open bilingual view for current note | Side-by-side reader with sync scrolling |
| Translate current note (background) | Translate the note with cache + estimate |
| Translate all notes in a folder | Queue a whole book split across files |
| Translate selection | Popup dictionary / sentence translation |
| Jump to page | Go to an original page number |
| Export interleaved bilingual document | Write a `… 双语对照.md` file |
| Export (translation only) | Pick "Translation only" in the export dialog for a clean `… 译文.md` copy |
| Import PDF and translate | Page-marked markdown from a PDF (text or vision) |
| Pause / resume translation queue | Control a running job |
| Show translation queue and retry failures | Inspect and retry failed blocks |

Clicking an untranslated block or page in the bilingual view translates just that page.

### Glossary format

A markdown table (default file `Glossary.md`):

```markdown
| Term | Translation or LEAVE |
| --- | --- |
| betweenness centrality | LEAVE |
| graph neural network | 图神经网络 |
```

`LEAVE` (or `保留`/`不译`) keeps the term in English. Per-document overrides go in frontmatter:

```yaml
---
glossary: path/to/book-terms.md   # extra glossary file for this book
leave-terms: [betweenness centrality, layering]
term-map: {smurfing: 蚂蚁搬家}
---
```

### Page markers

Presets: `[p.23]`, `[Page 23]`, `{p.23}`, `--- Page 23 ---`, `%%page: 23%%`, or a custom regex with one capture group. Documents without markers fall back to paragraph alignment.

## Network use & privacy

- The plugin makes network requests **only** to the translation endpoint you configure (OpenAI-compatible, Anthropic, or Gemini), using your API key.
- API keys and settings are stored locally in the plugin's `data.json` inside your vault; nothing is sent anywhere else.
- Translation caches are plain JSON files in a hidden folder (default `.bilingual/`) inside your vault.
- No telemetry, no remote code loading.

Using a paid API requires your own key and usage costs; the plugin shows token estimates before large runs.

## Development

```bash
npm install
npm run dev        # watch build
npm test           # core logic tests (segmenter, masker, glossary, batching)
npm run build      # production build
```

## 中文简介

PageSync Translate 面向在 Obsidian 中阅读英文书籍/论文的场景：

- **按页对照**：识别源文档中的页码标记（`[p.23]` 等），译文与原文按页对齐，可跳转任意原版页码
- **公式不乱码**：`$$…$$`、`$…$`、代码块、wiki 链接在送入模型前用占位符保护，翻译后还原并校验，丢失自动重试
- **术语表**：`| 英文术语 | 译文或 LEAVE |`，LEAVE 表示保留英文；翻译后自动校验，违规重试；文档级覆盖写在 frontmatter
- **锁定双栏**：左原文右译文，按段落同步滚动，支持翻页模式（一次一页，◀ ▶ 导航）
- **划词翻译**：选中文本弹出词典/翻译浮层，可一键加入术语表
- **全书后台翻译**：队列 + 并发 + 成本预估 + 断点续翻（只补翻译新增/修改过的段落）
- **PDF 导入**：文本模式快速提取；视觉模式逐页渲染成图像交给视觉模型，转录 LaTeX 公式并翻译，根治公式乱码
- **双语导出**：生成"原文引用 + 译文"交错的双语笔记

## Roadmap

Planned for the next version (cost-focused):

- **Smart hybrid PDF import** — free local text extraction for plain pages, vision only for math-heavy ones (50-80% cheaper, ~3× faster)
- **Transcribe-only vision mode** — vision call returns the LaTeX transcription; translation goes through the cheaper text pipeline
- **Glossary slimming & selective invalidation** — inject only terms present in each batch; glossary edits re-translate only affected paragraphs
- **Usage dashboard** — per-document token accounting from engine responses
- **Margin cropping** — trim PDF page whitespace before sending images

## License

MIT