DocuTranslate：把 PDF、字幕與論文交給 LLM 翻譯的本機工具

它要解決的是格式而不是語言

翻譯本身不是難題，難的是把內容從容器裡挖出來、翻完之後再放回去。DocuTranslate 針對的正是這一段。README 列出的格式包括 pdf、docx、xlsx、md、txt、json、epub、srt、ass，涵蓋論文、小說與字幕三種典型場景。這三種場景的共通點是：文字散落在結構化容器中，逐段複製貼上到聊天視窗並不現實。

專案的定位寫得很直白，是「a lightweight local file translation tool based on Large Language Models」。本機執行意味著檔案不必上傳到某個第三方翻譯網站，但文字仍然會送到你設定的 AI 平台，這一點在評估資料流向時不能混淆。

它適合的對象是：手上有一批文件要處理、願意自己管理 API key、且不需要逐頁比對版面的使用者。若你只是偶爾翻一段文字，這個工具的前置設定成本並不划算。

PDF 先轉 markdown，代價寫在 README 裡

整個流程的關鍵在 PDF 這條路徑。README 的說明是：翻譯 pdf 時會先轉換成 markdown，並以粗體標出這會 lose 原始版面。這句話決定了它的適用邊界。學術論文常見的雙欄排版、圖表與公式位置，在轉換後不會保留原樣。

為了讓論文這類文件仍能處理，專案引入 mineru 作為 PDF 解析引擎，README 描述它支援表格、公式與程式碼的辨識與翻譯，可線上使用或本地部署。轉換引擎由 DOCUTRANSLATE_CONVERT_ENGINE 指定，走線上服務時則需要 DOCUTRANSLATE_MINERU_TOKEN。

docx 與 xlsx 走的是另一條路。README 明確表示支援這兩種格式並維持原始格式，同時也明確表示目前不支援 doc 與 xls。這是一個乾淨的界線：舊版二進位格式請先自行轉存。

json 的處理方式值得一提。它支援用 jsonpath-ng 語法指定要翻譯的 value，而不是整份檔案丟進去。對於設定檔或語系檔這類混合了鍵名與內容的結構，這個設計避免了把不該翻的欄位一起送出去。

安裝路徑與啟動參數

pip 路線最直接，README 給的指令是 pip install docutranslate，需要 MCP 擴充時改為 pip install docutranslate[mcp]，安裝後以 docutranslate -i 啟動。uv 路線則是 uv add docutranslate，再以 uv run --no-dev docutranslate -i 執行。從原始碼起步的話，先 git clone 專案，進入目錄後執行 uv sync --no-dev，需要 MCP 時加上 --extra mcp 或 --all-extras。

Docker 是最省事的一種，README 的例子是 docker run -d -p 8010:8010 xunbu/docutranslate:latest，也示範了以互動模式執行以及指定版本標籤 v1.5.4。容器啟動後服務預設在 8010 埠。

啟動參數有幾個會直接影響使用方式。docutranslate -i 只允許本機存取，加上 --host 0.0.0.0 才開放同網段其他裝置連入，這對應到 README 提到的區域網路多使用者情境。--cors 啟用預設的跨來源設定，-p 可換埠號。加上 --with-mcp 會同時開啟 MCP SSE 端點，與 GUI 共用佇列與埠號。

服務起來之後，瀏覽器連到 http://127.0.0.1:8010，API 文件在 /docs，SSE 端點在 /mcp/sse。這幾個路徑是固定的，部署到反向代理後面時要一併處理。

MCP 模式與環境變數的耦合

DocuTranslate 可以當成 MCP server 使用，這是它與一般翻譯腳本最不一樣的地方。stdio 模式用 docutranslate --mcp，SSE 模式加上 --transport sse 並以 --mcp-host 與 --mcp-port 指定位址，另有 streamable-http 模式。

MCP 模式讀的是環境變數，不是設定檔。必填三項：DOCUTRANSLATE_API_KEY、DOCUTRANSLATE_BASE_URL、DOCUTRANSLATE_MODEL_ID。選填的包括 DOCUTRANSLATE_TO_LANG（預設 Chinese）、DOCUTRANSLATE_CONCURRENT（預設 10）、DOCUTRANSLATE_CONVERT_ENGINE 與 DOCUTRANSLATE_MINERU_TOKEN。

BASE_URL 這一項值得多看兩眼。README 的範例填的是 https://api.openai.com/v1，說明它走的是 OpenAI 相容介面，因此任何提供相同介面的平台理論上都能接。但 README 只用「支援大多數 AI 平台」帶過，沒有列出驗證過的清單，實際相容性得自己試。

uvx 的設定方式讓人不需安裝即可使用，客戶端設定裡把 command 設為 uvx、args 設為 --from docutranslate[mcp] docutranslate --mcp，再把上述環境變數放進 env 區塊。要注意這些值是寫在 MCP 客戶端的設定檔裡，API key 會以明文形式存在該檔案中。

DOCUTRANSLATE_CONCURRENT 預設 10，代表同時送出 10 個請求。這個數字直接對應到你的 API 額度與速率限制，調高之前先確認平台端的限制。

詞彙表與併發解決的是長文件問題

長文件翻譯最常見的失敗不是譯錯單句，而是同一個專有名詞在第一章與第十章出現不同譯法。README 提到支援自動生成詞彙表以確保術語一致。這是一個先掃描、再統一的兩段式做法，代價是多一輪 LLM 呼叫，成本會隨文件長度上升。

自訂 prompt 也是同一個問題的另一種解法。README 說支援自訂 prompt 與高效能併發 AI 翻譯，但沒有給出具體的 prompt 範本或長度上限。這部分屬於文件較薄的地方，實際效果取決於你怎麼寫。

非同步設計在 README 中被描述為針對高效能場景，提供完整非同步支援與平行多工介面。對於一次要處理整批字幕或整本小說的用途，這比逐檔等待實際得多。但非同步也意味著失敗重試的粒度是單一區塊，部分失敗時要自己確認哪些段落沒翻到。

什麼情況下不該用它

第一種是版面即內容的 PDF。排版精美的型錄、含大量圖表標註的技術手冊、需要保留頁碼與頁眉的法律文件，轉成 markdown 之後這些資訊就沒了。README 對這件事沒有含糊其辭，它直接寫明會遺失原始版面並提醒有嚴格版面需求的使用者注意。

第二種是舊版 Office 格式。doc 與 xls 明確不在支援範圍內，README 說的是 currently does not support，沒有承諾時程。

第三種是無法接受內容離開本機網路的情況。工具本身在本機執行，但翻譯請求會送到你設定的 BASE_URL。若合規要求文件內容不得離開內網，唯一可行的是把 BASE_URL 指向自架且 OpenAI 相容的推論服務，這需要另外的部署工作，不在這個專案範圍內。

第四種是只想快速翻一兩段文字。安裝 Python 環境、設定環境變數、啟動服務，這一串流程對單次小量需求並不經濟。

與直接寫腳本呼叫 API 的差異

最直接的替代方案是自己寫一支 Python 腳本，讀檔、切段、呼叫 API、寫回。對於單一格式、結構固定的檔案，這樣做反而更可控，因為你完全知道每一段文字送去哪裡、回來怎麼組。

DocuTranslate 多出來的是格式轉接層與服務層。格式轉接層處理的是 pdf 轉 markdown、docx 與 xlsx 的格式保留、json 的 jsonpath-ng 取值、字幕時序的對應。這些工作每一項都不難，但加起來是相當份量的解析程式碼，而且各格式的邊角案例會持續出現。服務層則是 Web UI 與 RESTful API，讓不寫程式的人也能上傳檔案。

另一個方向是使用現成的雲端文件翻譯服務。差別在於模型與 prompt 由對方決定，你無法替換成自己偏好的模型，也無法自訂術語表。DocuTranslate 把這兩個控制權留給使用者，代價是要自己申請 key 與承擔 API 費用。

如果你的需求是單一格式且量不大，自寫腳本的總持有成本可能更低。當格式超過兩種、或需要給非工程師使用時，這個專案的價值才顯現出來。

維護節奏與 MPL-2.0 的實務面

從發布紀錄看，v1.7.7 到 v1.7.8 相隔約兩週，v1.7.8 到 v1.7.9 約兩個月，最新一次推送與 v1.7.9 發布時間相近。這是一個仍在活動的專案，但節奏並不固定，版本間隔從兩週到兩個月都有。專案未被封存。

升級成本主要來自兩個方向。一是環境變數的介面，目前以 DOCUTRANSLATE_ 為前綴的一組變數承載設定，若未來新增必填項，既有部署會啟動失敗。二是格式解析的相依套件，PDF 這條路徑牽涉 mineru 與其 token，解析引擎的行為變動會直接影響輸出。

授權是 MPL-2.0。這是一種檔案層級的 copyleft 授權：修改過的原始碼檔案需要以相同授權釋出，但可以與其他授權的程式碼組合。對於內部使用或包裝成服務，通常不涉及散布義務；若你要修改原始碼後再散布，就需要注意對應檔案的釋出要求。這裡只是描述授權條款的常見理解，不構成法律意見，實際情況請諮詢法務。

專案沒有提供 Homepage，對外文件集中在 README 與各語系版本，另有 MCP 專屬說明文件位於 docutranslate/mcp/README.md。README 中列有 QQ 社群群組，這是它主要的支援管道之一。

編輯結論

如果你要翻譯的是純文字為主的檔案，例如 srt 字幕、epub 電子書、json 欄位或 markdown，而且願意自己接上 AI 平台的 API key，DocuTranslate 值得裝來試；它的 Web UI 與 RESTful API 讓非開發者也能操作。若你的 PDF 有嚴格版面要求，README 已明說轉成 markdown 後會遺失原始版面，這類需求不該用它。採用前請先確認三件事：你的目標語言是否已列在 DOCUTRANSLATE_TO_LANG 的支援範圍、你的 AI 平台是否提供 OpenAI 相容的 base URL、以及是否需要另外申請 DOCUTRANSLATE_MINERU_TOKEN 才能解析表格與公式。

官方來源

1. Issues
2. License: MPL-2.0
3. README
4. Releases
5. xunbu/docutranslate on GitHub