pdf-md-translate

把 PDF / Markdown 論文翻譯成你要的語言，並輸出排版好看的 PDF。

支持 OpenAI GPT 與 Google Gemini，自動保留 LaTeX 公式、程式碼與表格。

python -m pip install --upgrade pdf-md-translate     # 1. 安裝 有些python需要改成python3
md-translate --setup             # 2. 設定 API Key（第一次才需要）
md-translate paper.pdf           # 3. 翻譯！輸出 paper_trans.pdf

安裝（3 步驟）

1. 安裝 Chrome（用來生成 PDF）

只輸出 Markdown（加 -m）時不需要 Chrome。

2. 安裝套件

python -m pip install --upgrade pdf-md-translate

需要 Python 3.10 ~ 3.13，建議在虛擬環境中安裝。

第一次轉 PDF 時會檢查 Pandoc；若找不到，程式會自動下載至目前 Python 環境的 bin（Windows 為 Scripts）目錄。首次下載需要網路與該目錄的寫入權限；已找到可用的 Pandoc 時不會重複下載。只輸出 Markdown（-m）不需要 Pandoc。

3. 設定 API Key、模型與推理程度

md-translate --setup

互動式選單：選擇提供商 → 輸入 API Key、切換提供商或「選擇／指定模型」，可隨時重新進入修改。

更換 GPT 模型：執行 md-translate --setup → 1. OpenAI → 3. 選擇／指定模型：

• 手動輸入模型 ID：貼上官方模型頁的 ID，無需修改程式。Gemini 也支援手動指定。
• 從 OpenAI 即時清單選擇：使用目前 API Key 查詢文字模型候選，按 API 建立時間由新到舊排列，再輸入編號保存。

清單依官方 Models API取得；建立時間不是官方推薦順序，清單也不提供端點相容性。請選擇支援 Chat Completions 文字輸出的模型，並確認費用與帳號權限。圖片、語音等明顯不適用的模型會先過濾；未列出的模型仍可手動輸入。

模型 ID 會保存於設定檔，之後翻譯沿用該選擇，不會自動切換到其他模型。取得清單失敗或取消操作會保留原設定。舊設定檔沒有模型欄位時沿用下列預設值。

推理程度：md-translate --setup → 1. OpenAI → 5. 推理程度。先選模型，再選程度；設定按完整模型 ID 分別保存，切換模型不會沿用另一個模型的值。

以上依 2026-09-12 的官方模型頁核對：GPT-6 Astra、GPT-5.6 Sol、Terra、Luna、GPT-5.5、GPT-5.4、Mini。日期快照沿用所屬模型的選項；新模型的支援表需要更新程式，並非由模型清單 API 自動取得。

「模型預設」不等於 none，它會省略參數，使用模型本身的預設值。較高推理程度通常增加等待時間與用量。Gemini 此次僅支援選擇模型，未加入推理設定。

開始使用

兩個命令完全等價：md-translate（別名）和 pdf-md-translate（套件名）。下面都用 md-translate。

翻譯一個檔案

md-translate paper.pdf       # PDF → 翻譯 → 輸出 paper_trans.pdf
md-translate paper.md        # Markdown → 翻譯 → 輸出 paper_trans.pdf

預設翻成繁體中文，輸出檔名固定加上 _trans 後綴，不會覆蓋你的原始檔案。

指定翻譯語言

md-translate paper.pdf --lang 簡體中文
md-translate paper.pdf -l English      # -l 是 --lang 的簡寫

常用語言：繁體中文、簡體中文、English、日本語、한국어…（LLM 支援的語言都可以試）

只要 Markdown，不要 PDF

md-translate paper.pdf -m              # 輸出 paper_trans.md（不生成 PDF）

只轉檔不翻譯

md-translate paper.pdf --no-translate  # PDF → PDF，跳過翻譯

只將 Markdown 轉成 PDF

md-translate "paper.md" --no-translate  # 輸出 paper_trans.pdf

直接執行 Markdown → HTML → PDF，不啟用 MinerU，也不呼叫翻譯 API。預設套用內建的 default.css，也可以用 --css 指定其他樣式。

需要 Chrome 與 Pandoc（Pandoc 若未安裝，程式會嘗試自動下載）。不要加 -m，因為它代表只輸出 Markdown，不生成 PDF。

目前命令啟動時仍會檢查 API 設定，因此首次使用可能出現設定提示；轉檔本身不會呼叫翻譯 API。

就這些。下面是進階選項與細節，需要時再看。

進階選項

設定命令：

參數可任意順序、任意組合，例如：

md-translate thesis.pdf --lang 繁體中文 --no-css
md-translate file.pdf -m --no-translate --ocr-lang ch

⚠️ 別把兩個「語言」搞混：

• --lang / -l = 要翻成什麼語言（翻譯目標）
• --ocr-lang = PDF 原文本身是什麼語言（OCR 辨識來源）

翻譯非英文論文時，要改的是 --ocr-lang，不是 -l。

它做了什麼（處理流程）

PDF  ──(mineru)──►  Markdown  ──(LLM)──►  翻譯後 Markdown  ──(pandoc+Chrome)──►  PDF
MD   ─────────────────────────(LLM)──►  翻譯後 Markdown  ──(pandoc+Chrome)──►  PDF

• 輸出檔名統一加 _trans 後綴：paper.pdf → paper_trans.pdf
• 原始檔案永遠保留，翻譯結果是新檔案
• 最終輸出 PDF 時，中間的 .md 與圖片資料夾會自動清掉；用 -m 時則保留 .md

不同輸入 × 參數的輸出對照

翻譯特性

• 🧮 保留 LaTeX 公式：$...$ / $$...$$ 內容原封不動，不翻譯
• 💻 保留程式碼與表格：程式碼塊（```）、Markdown／HTML 表格不翻譯
• 🔖 資工術語：常見術語會保留原文或標註原文
• 🔢 移除標題編號：自動去掉原文標題的 1.1、2.3.1 等編號
• 📑 雙語對照：內文輸出「原文 + 譯文」對照（標題則同行並排）

範例——公式在翻譯後位置不變：

原文：The mutant vector $V_{i,G+1}$ is calculated using $V_{i,G+1} = X_{r1,G} + F \cdot (X_{r2,G} - X_{r3,G})$.

譯文：變異向量 $V_{i,G+1}$ 是使用公式 $V_{i,G+1} = X_{r1,G} + F \cdot (X_{r2,G} - X_{r3,G})$ 計算得出的。

PDF 樣式（CSS）

輸出 PDF 時有四種樣式可選，擇一使用：

md-translate paper.md                 # 預設主題（PT Serif 襯線、米色背景）
md-translate paper.md --no-css        # 內建 GitHub 主題（Open Sans、白底）
md-translate paper.md --black-css     # 內建 night 暗色主題（深色背景）
md-translate paper.md --css mine.css  # 你自己的 CSS

--no-css：內建 GitHub 主題

不用自己寫 CSS 就能套用乾淨現代的版面：

• 🅰️ Open Sans 字體 + 白色背景，貼近 GitHub 的 Markdown 預覽
• 📦 字體已內建，免另外安裝
• 🈶 完整中文支援（含程式碼區塊內的中文）
• 🧱 程式碼區塊是單一連續方框，不會斷裂

--black-css：內建 night 暗色主題

深色背景版面，適合在螢幕上閱讀：

• 🌙 深灰背景（#363B40）+ 淺色文字，長時間閱讀較不刺眼
• 🈶 完整中文支援（含程式碼區塊內的中文）
• 🎨 程式碼採暗色語法高亮，在深色底上清晰易讀

此主題以 Typora 的 night 主題為基礎，並針對 PDF 輸出補上中文字體與程式碼區塊樣式。

--css：自訂樣式

最簡單的做法是複製內建的 default.css 改：

cp default.css my_style.css
# 編輯 my_style.css …
md-translate paper.md --css my_style.css

系統會自動偵測背景色、加上列印最佳化，且不會修改你的原始 CSS 檔。支援 --bg-color 等 CSS 變數。

ℹ️ 中文字體：靠系統內建的 CJK 字體顯示（macOS／Windows 開箱即用）。極簡 Linux 環境若缺中文字體，請自行安裝，例如 apt install fonts-noto-cjk。

CPU 模式與後端差異（--cpu）

很多人以為 --cpu 只是「把 GPU 的工作改用 CPU 做、單純變慢」，其實它會切換成另一套完全不同的解析引擎，辨識能力也跟著不同：

💡 結論：一般文件建議不要加 --cpu，程式會使用 hybrid-engine 的預設 medium 強度。它仍會提取 PDF 圖片，但不會額外分析圖片與圖表內容，速度較快且較省記憶體；--cpu 只當作記憶體不足、Hybrid 跑不動時的輕量備援。

🍎 Mac 用戶：M 系列 Mac 不加 --cpu 時會用 Apple GPU 執行 Hybrid medium 模式，建議優先不要加 --cpu。

OCR 語言（--ocr-lang）

--ocr-lang 決定 mineru 用哪種語言模型辨識原文 PDF。MinerU 3.4.5 將英文、中文、日文、繁體中文與拉丁字母場景統一交由 ch 模型處理，因此本工具預設使用 ch。翻譯其他語系論文時要改的是這個參數，不是 --lang：

md-translate english_paper.pdf                       # 英文論文（預設 ch）
md-translate 中文論文.pdf --ocr-lang ch              # 中文論文
md-translate 中文論文.pdf --ocr-lang ch --lang 英文  # 中文原文 → 翻成英文

常用代碼（完整清單見 mineru --help）：

設定檔

位置：~/.config/markdown-translator/config.json（用 md-translate --config 查看）

{
  "api_provider": "openai",
  "openai_api_key": "your_key_here",
  "gemini_api_key": "",
  "target_language": "繁體中文",
  "openai_model": "gpt-5.4-mini",
  "gemini_model": "gemini-3.1-flash-lite"
}

API Key 以 600 權限（僅所有者可讀寫）安全存放在個人設定目錄。

故障排除

md-translate paper_trans.md --no-translate

常見問題

Q：兩個命令 md-translate 和 pdf-md-translate 有差別嗎？ 完全一樣，任選一個用。

Q：-m 和 --no-translate 差在哪？ -m = 只輸出 Markdown 不轉 PDF；--no-translate = 跳過翻譯只轉檔。兩者可一起用。

Q：原始檔案會被覆蓋嗎？ 不會。輸出一律加 _trans 後綴，原始 PDF／MD 永遠保留。

Q：可以一次翻譯多個檔案嗎？ 目前不行，請逐一執行。

Q：Mac 需要加 --cpu 嗎？ 建議不要。M 系列 Mac 預設用 Apple GPU 執行 hybrid-engine；MinerU 會採用預設的 medium 強度。只有跑不動時才拿 --cpu 當備援（見〈CPU 模式與後端差異〉）。

Q：要先裝 Pandoc 嗎？ 不用。程式會在轉 PDF 前檢查，缺少時才下載到目前 Python 環境；首次下載需要網路。

Q：支援哪些翻譯語言？ 由 LLM 決定，繁中／簡中／英／日／韓／法／西／德等常見語言都支援，其他語言也可以試。

1.0.6 更新

• 調整預設 PDF 的左右邊距、內文字級、標題大小與段落間距，所有頁面使用相同的左右邊距。
• 為二級標題加入底線，並讓標題字級獨立於內文字級。
• 限制表格寬度，讓表格與程式碼中的長內容換行，減少超出頁面的情況。
• 量測 MathJax 公式寬度，僅縮小超寬公式，並限制隱藏 MathML 對版面的影響，避免整份 PDF 被連帶縮小。
• 補上使用 --no-translate 將 Markdown 直接轉成 PDF 的說明。

1.0.5 更新

• 將 MinerU 從 3.0.9 升級至 3.4.5。
• Apple Silicon 已完成 pipeline 與 MLX hybrid-engine 的 19 頁 PDF 轉換測試。
• 預設使用 MinerU 的 Hybrid medium 解析強度；仍會提取圖片，但不額外分析圖片與圖表內容。
• OCR 預設代碼改為 MinerU 3.4.5 支援的 ch，並更新語言選項說明。
• 保留驗證通過的 pypdfium2==4.30.0、pdftext==0.6.3 與 mlx==0.31.1。

1.0.4 更新

• OpenAI 設定新增「5. 推理程度」，按模型分別保存，翻譯時傳入 reasoning_effort。
• 「模型預設」省略參數；none 明確關閉推理，僅在模型支援時提供。
• 未確認支援程度的模型只提供模型預設，避免傳入不相容參數。

1.0.3 更新

• 設定選單可保存 OpenAI／Gemini 模型 ID，翻譯與啟動畫面使用已保存的選擇。
• OpenAI 可即時取得模型候選清單，依 API 建立時間排序後選擇。
• OpenAI 翻譯不再固定傳送 temperature=0.3，避免選擇不支援該參數的模型時失敗；使用各模型的預設採樣設定。

1.0.2 更新

• 固定 MinerU 3.0.9 的相容依賴：pypdfium2==4.30.0、pdftext==0.6.3；Apple Silicon macOS 使用 mlx==0.31.1，避免 PDFium 與 MLX 介面不相容。
• 補上缺少 Pandoc 時的自動安裝流程。
• PDF 輸出失敗會保留 Markdown、譯文與圖片，並回傳非零結束狀態，不再誤報完成。
• Chrome 輸出穩定且 PDF 驗證通過後就結束瀏覽器，避免檔案已產生仍等待兩分鐘；120 秒保留為未完成輸出的等待上限。

本次已在 Apple Silicon macOS／Python 3.12 驗證；其他平台尚未實測。

相依套件

授權：GNU AGPL v3