subtrans

使用 OpenAI API 翻译字幕文件（SRT / VTT / ASS / LRC / SBV）

中文 | English

特性

• 支持多种字幕格式：SRT、WebVTT、ASS/SSA、LRC、SBV
• 支持 OpenAI 兼容 API
• 支持按句子边界智能分批
• 支持翻译缺失/合并自动重试
• 支持自定义翻译指令和提示词
• 支持原文与译文双语输出
• 支持作为 命令行工具、Go 库 使用
• 支持 HTTP API 及 SSE 流式输出

安装

Homebrew (macOS / Linux):

brew install heartleo/tap/subtrans

curl (macOS / Linux):

curl -fsSL https://raw.githubusercontent.com/heartleo/subtrans/main/install.sh | sh

Go install (需要 Go 1.25+):

go install github.com/heartleo/subtrans/cmd/subtrans@latest

从源码编译:

git clone https://github.com/heartleo/subtrans
cd subtrans
go build -o subtrans ./cmd/subtrans

快速开始

命令行

# 创建env文件或设置环境变量
cat > .env <<EOF
OPENAI_API_KEY=sk-xxx
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_MODEL=gpt-4.1
EOF

# 默认翻译为中文（按后缀自动识别格式）
subtrans input.srt
subtrans input.vtt
subtrans lyrics.lrc
subtrans anime.ass

# 翻译为法语并指定输出文件
subtrans -l fr -o output.fr.srt input.srt

# 使用自定义 API 地址和模型
export OPENAI_BASE_URL=https://your-api.com/v1
export OPENAI_MODEL=gpt-5.2
subtrans -l fr input.srt

Go 库

go get github.com/heartleo/subtrans

package main

import (
	"context"
	"log"
	"os"

	"github.com/heartleo/subtrans"
)

func main() {
	t, err := subtrans.New(subtrans.Config{
		APIKey: os.Getenv("OPENAI_API_KEY"),
	})
	if err != nil {
		log.Fatal(err)
	}

	subContent, err := os.ReadFile("input.srt")
	if err != nil {
		log.Fatal(err)
	}

	result, err := t.Translate(context.TODO(), string(subContent), "zh")
	if err != nil {
		log.Fatal(err)
	}
}

非 SRT 格式通过 WithFormat 指定：

t.Translate(ctx, content, "zh", subtrans.WithFormat(subtrans.FormatVTT))
t.Translate(ctx, content, "zh", subtrans.WithFormat(subtrans.FormatASS))

// 或按文件名自动识别
f, _ := subtrans.DetectFormat("input.lrc")
t.Translate(ctx, content, "zh", subtrans.WithFormat(f))

支持的字幕格式

格式	扩展名	支持
SRT	.srt	✅
VTT	.vtt	✅
ASS	.ass/.ssa	✅
LRC	.lrc	✅
SBV	.sbv	✅

环境变量

变量	说明	默认值
OPENAI_API_KEY	API 密钥	-
OPENAI_BASE_URL	API 地址	https://api.openai.com/v1
OPENAI_MODEL	模型名称	gpt-5.5
OPENAI_TEMPERATURE	温度	0.0
OPENAI_MAX_RETRIES	最大重试次数	3

Server API

# 启动服务
subtrans serve

# 自定义提示词
curl -X POST http://localhost:8091/translate \
  -F "file=@input.srt" \
  -F "language=fr" \
  -F "prompt=your-prompt"

# 上传 VTT/ASS/LRC/SBV 字幕文件
curl -X POST http://localhost:8091/translate \
  -F "file=@anime.ass" \
  -F "language=zh"

# 显式指定格式
curl -X POST http://localhost:8091/translate \
  -F "file=@noext_file" \
  -F "format=vtt" \
  -F "language=zh"

# SSE 流式输出，逐批返回翻译结果
curl -X POST http://localhost:8091/translate \
  -H "Accept: text/event-stream" \
  -F "file=@input.srt" \
  -F "language=zh"

参数	说明	默认值
file	字幕文件	-
format	字幕格式（srt/vtt/ass/lrc/sbv）	按后缀识别
language	目标语言 ISO 代码	zh
prompt	自定义提示词	-
instructions	自定义系统指令	-

命令行参数

全局参数（翻译和 serve 均支持）：

参数	缩写	说明	默认值
--verbose	-v	启用调试日志	false

subtrans

参数	缩写	说明	默认值
--language	-l	目标语言 ISO 代码	zh
--output	-o	输出文件路径	<输入文件>.<语言>.<原后缀>
--model	-m	模型	-
--max-batch-size		每批行数	30
--batch-split-punct		分批切分标点符号	.
--instructions		指令文本文件路径	-
--prompt		自定义用户提示词	-
--temperature		温度	0.0
--max-retries		API 失败重试次数	3
--include-original		输出中包含原文	false
--strip-punctuation		去除译文及原文（--include-original 时）尾部标点	true

subtrans serve

参数	缩写	说明	默认值
--host		监听地址	localhost
--port	-p	监听端口	8091

---

Made with ❤️ by heartleo