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 中均有引用，涵盖定价、速率限制和结构化输出。