Cerlancism/chatgpt-subtitle-translator

Efficient translation tool based on ChatGPT or any OpenAI compatible LLM chat completion API

ChatGPT API SRT 字幕翻譯工具

是什麼 – 一個調用 OpenAI ChatGPT（或相容）API 的 Node.js 工具，逐行翻譯 SRT 字幕檔案或純文字。旨在保持字幕行與翻譯之間的一一對應關係，同時最小化令牌浪費。

為何重要 – 字幕通常是帶有時間戳的大量短行。若將每行作為單獨請求發送，將導致令牌使用量激增並觸發速率限制。此工具會剝離 SRT 的開銷，智能分批處理，並可利用 OpenAI 的 結構化輸出 和 提示快取 功能，實現緊湊且確定性的翻譯。

核心功能（README 中描述）

Web UI + CLI – 瀏覽器端介面和命令列程式（cli/translator.mjs）。
結構化輸出 – JSON 數組、物件或帶時間戳感知的格式，強制模型返回精確的翻譯行。
提示快取支援 – 可選擇包含最近的翻譯歷史（--context），以複用快取的提示片段。
分批行處理 – 將多行字幕合併為單個請求，減少每行的令牌開銷。
OpenAI 審核檢查 – 可在發送前預過濾模型會拒絕的輸入（--use-moderator）。
串流進度 – 模型串流返回回應時，提供即時終端機回饋。
速率限制處理 – 尊重 OpenAI RPM 限制，並可恢復中斷的任務。
代理模式 – 多輪工作流程，先建立檔案概要，制定優化的翻譯指令，再進行翻譯；適用於長或複雜的字幕。
相容任意 OpenAI 相容端點 – 例如本地 Ollama 伺服器。

快速開始（來自 README）

# 克隆並安裝
git clone https://github.com/Cerlancism/chatgpt-subtitle-translator
cd chatgpt-subtitle-translator
npm install
chmod +x cli/translator.mjs

# 設定 API 金鑰
cp .env.example .env   # 然後編輯 .env 並貼上你的 OpenAI 金鑰

翻譯檔案

cli/translator.mjs --input mymovie.srt --from Japanese --to English

工具會產生一個包含翻譯文字的新 *.srt 檔案。

一次性純文字翻譯

cli/translator.mjs --plain-text "你好"

輸出：Hello.

內部工作原理

剝離 SRT 元資料 – 在發送給模型前移除索引和時間戳（或在 時間戳 模式下壓縮）。
批量建立 – 根據 --batch-sizes 或由 --context 令牌預算推導出的自動大小對行進行分組。
提示建構 – 使用最小系統指令（如 Translate to English，約 3 個令牌）加上包含批量行的 JSON 負載。
模型呼叫 – 請求可使用結構化輸出（json_schema），確保回應是翻譯行的數組/物件。
重新組裝 – 將返回的翻譯重新插入原始 SRT 格式，保留時間戳（或在 時間戳 模式下合併項目）。
重試邏輯 – 若模型返回不同行數，減小批量大小並重試，避免浪費令牌。

重要選項（精選）

-r, --structured <mode> – 選擇 array（預設）、object、timestamp、agent 或 none。
-c, --context <tokens> – 為提示快取包含多少令牌的先前翻譯歷史。
-b, --batch-sizes <sizes> – 明確列出批量大小，例如 100,50,20。
--use-moderator – 在發送批量前執行 OpenAI 審核端點。
-m, --model <model> – 預設為 gpt-4o-mini；任何端點支援的模型均可使用。
-t, --temperature <value> – 設定為 0 以實現確定性翻譯。
--no-prefix-number / --no-line-matching – 放寬嚴格的行對行強制。

限制與注意事項（來自 README）

該工具依賴 OpenAI API（或相容服務）——你需要有效的 API 金鑰，並將產生令牌費用。
透過設定 temperature=0 可鼓勵確定性輸出，但模型仍可能因模糊文字而產生變化。
結構化輸出模式要求模型理解提供的 JSON 模式；舊版或非 ChatGPT 模型可能不支援。
在 timestamp 模式下，輸出行數可能與輸入不同（項目可合併），因此進度恢復功能被停用。
大型字幕檔案若批量大小對模型上下文視窗過於激進，可能觸發多次重試。

適合誰使用

內容創作者 – 無需支付專用翻譯服務費用，即可快速獲得高品質電影或影片字幕翻譯。
開發者 – 建構字幕輸入流程，需要可程式化、API 驅動的翻譯步驟。
研究人員 – 在行結構化資料上實驗基於 LLM 的翻譯品質。

連結

Web UI – https://cerlancism.github.io/chatgpt-subtitle-translator
遷移指南 – docs/CHANGELOG.md#300-2026-03-01
OpenAI API 文件 – 整個 README 中均有引用，涵蓋定價、速率限制和結構化輸出。