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):

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

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

---
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

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