PageSync Translate

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

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