SRT Translator

Translate .srt subtitle files using LLM APIs (OpenAI-compatible: Kimi, GPT, etc.). Supports extracting subtitles from video files and embedding translated tracks back.

Features

• Translate .srt subtitle files to any language via LLM
• Search OpenSubtitles for existing subtitles and auto-align timing to your video
• Extract embedded subtitle tracks from video files (requires ffmpeg)
• Embed translated subtitles back into video (no re-encoding)
• Supports multiple LLM providers (OpenAI-compatible: Kimi, OpenAI, etc.)
• CLI

Requirements

• Node.js 18+
• ffmpeg (required for subtitle extraction/embedding)

Installation

npm install -g srt-trans

Configuration

Config is loaded from the following locations in order:

1. --config <path> flag (explicit path)
2. ./config.yaml (current directory)
3. ~/.srt-trans/config.yaml (user home — recommended for global install)

For a global install, create the config once:

mkdir -p ~/.srt-trans
cp "$(npm root -g)/srt-trans/config.example.yaml" ~/.srt-trans/config.yaml
# then edit ~/.srt-trans/config.yaml and fill in your API key

Config file format:

providers:
  - name: kimi
    base_url: https://api.moonshot.cn/v1
    api_key: sk-your-key-here
    model: moonshot-v1-8k

  - name: openai
    base_url: https://api.openai.com/v1
    api_key: sk-your-openai-key-here
    model: gpt-4o

active_provider: kimi   # default provider
target_language: 中文   # default target language
batch_size: 30          # subtitle blocks per batch

opensubtitles:
  api_key: "your-api-key-here"   # get one at https://www.opensubtitles.com/consumers
  username: ""                    # optional — for higher rate limits
  password: ""                    # optional
  default_language: "zh-CN"       # e.g. zh-CN, en, ja, fr

providers is an array — any number of OpenAI-compatible services can be configured.

CLI Usage

Translate a subtitle file

srt-trans translate subtitle.srt
srt-trans translate subtitle.srt --target English
srt-trans translate subtitle.srt --provider openai --output out.srt

Output is auto-named: subtitle.srt → subtitle.trans.中文.srt

Extract subtitles from video (then translate)

# List subtitle tracks in a video
srt-trans list-tracks movie.mkv

# Extract subtitle to .srt (auto-selects if only one track)
srt-trans extract movie.mkv
srt-trans extract movie.mkv --track 0 --output subtitle.srt

# Extract + translate (auto-selects single track, interactive for multiple)
srt-trans translate movie.mkv --extract --target 中文

Extracted output is auto-named: movie.mkv → movie.<lang>.srt (e.g. movie.ita.srt)

Embed subtitles into video

srt-trans embed movie.mkv subtitle.trans.中文.srt --output movie.embedded.mkv

Stream copy only — no re-encoding. Original subtitle tracks are preserved; the new track is appended.

| Option | Description | Default | |--------|-------------|---------| | --lang | ISO 639-2 language code | chi | | --title | Track title shown in player | 中文 |

Search OpenSubtitles for an existing subtitle

srt-trans search-sub movie.mkv --lang zh-CN

Workflow:

1. Extracts the video's subtitle track as a timing baseline
2. Computes the video's OpenSubtitles hash for exact version matching
3. If hash matches → downloads the subtitle directly (timing is guaranteed correct)
4. If no hash match → falls back to title search, lets you pick a result
5. If block counts match → aligns timing via median offset correction
6. If block counts differ → saves as-is and suggests alternatives

Output is auto-named: movie.mkv → movie.zh-CN.srt

Check translation completeness

srt-trans diff original.srt translated.srt

Compares block counts and lists any missing entries by index, timestamp, and original text.

All commands

srt-trans translate <file>              Translate .srt or extract from video then translate
srt-trans extract <video>               Extract subtitle track from video to .srt
srt-trans list-tracks <video>           List all subtitle tracks in a video
srt-trans embed <video> <srt>           Embed .srt into video as a new subtitle track
srt-trans search-sub <video>            Search OpenSubtitles and align timing to your video
srt-trans diff <original> <translated>  Check for missing blocks between two SRT files

Each command supports --help for full options.

~~Web UI~~

~~Web UI is temporarily unavailable.~~

How Translation Works

• Subtitles are sent to the LLM in batches (default: 30 blocks per request) to minimize API calls
• If the LLM returns a malformed response, it retries automatically; on retry failure it falls back to one-by-one translation to guarantee completeness
• Timestamps are preserved exactly — only the text content is replaced
• After translation, a diff check is automatically run to report any missing blocks

SRT 字幕翻译工具

将 .srt 字幕文件翻译成目标语言，支持从视频文件提取字幕、嵌入字幕轨道。

功能

• 通过 LLM 翻译 .srt 字幕文件到任意语言
• 从 OpenSubtitles 搜索现有字幕，并自动对齐时间轴
• 从视频文件提取内嵌字幕轨道（需要 ffmpeg）
• 将翻译后的字幕嵌入视频文件（无需重新编码）
• 支持多个 LLM 提供商（兼容 OpenAI 格式，如 Kimi、OpenAI 等）
• CLI

环境要求

• Node.js 18+
• ffmpeg（字幕提取/嵌入功能需要）

安装

npm install -g srt-trans

配置

配置文件按以下优先级查找：

1. --config <path> 参数指定的路径
2. ./config.yaml（当前目录）
3. ~/.srt-trans/config.yaml（用户主目录，全局安装推荐）

全局安装后，只需配置一次：

mkdir -p ~/.srt-trans
cp "$(npm root -g)/srt-trans/config.example.yaml" ~/.srt-trans/config.yaml
# 编辑 ~/.srt-trans/config.yaml，填入 API Key

配置文件格式：

providers:
  - name: kimi
    base_url: https://api.moonshot.cn/v1
    api_key: sk-your-key-here
    model: moonshot-v1-8k

  - name: openai
    base_url: https://api.openai.com/v1
    api_key: sk-your-openai-key-here
    model: gpt-4o

active_provider: kimi   # 默认使用的 provider
target_language: 中文   # 默认目标语言
batch_size: 30          # 每批翻译的字幕条数

opensubtitles:
  api_key: "your-api-key-here"   # 在 https://www.opensubtitles.com/consumers 免费申请
  username: ""                    # 可选，用于提高请求限额
  password: ""                    # 可选
  default_language: "zh-CN"       # 如 zh-CN、en、ja、fr

CLI 使用

翻译字幕文件

srt-trans translate subtitle.srt
srt-trans translate subtitle.srt --target English
srt-trans translate subtitle.srt --provider openai --output out.srt

输出文件自动命名：subtitle.srt → subtitle.trans.中文.srt

从视频提取字幕（再翻译）

# 查看视频有哪些字幕轨道
srt-trans list-tracks movie.mkv

# 仅提取字幕到 .srt 文件（只有一条轨道时自动选择）
srt-trans extract movie.mkv
srt-trans extract movie.mkv --track 0 --output subtitle.srt

# 提取 + 翻译（单轨道自动选择，多轨道交互式选择）
srt-trans translate movie.mkv --extract --target 中文

提取输出文件自动命名：movie.mkv → movie.<轨道语言>.srt（如 movie.ita.srt）

将字幕嵌入视频

srt-trans embed movie.mkv subtitle.trans.中文.srt --output movie.embedded.mkv

从 OpenSubtitles 搜索现有字幕

srt-trans search-sub movie.mkv --lang zh-CN

执行流程：

1. 提取视频内置字幕作为时间基准
2. 计算视频 OpenSubtitles 哈希，精确匹配发行版本
3. 哈希命中 → 直接下载（时间轴完全一致）
4. 未命中 → 按标题搜索，交互式选择结果
5. 块数相同 → 中位数时间偏移对齐
6. 块数不同 → 直接输出并提示备选方案

输出自动命名：movie.mkv → movie.zh-CN.srt

检查翻译完整性

srt-trans diff original.srt translated.srt

所有命令

srt-trans translate <file>              翻译 .srt 或从视频提取后翻译
srt-trans extract <video>               从视频提取字幕到 .srt
srt-trans list-tracks <video>           列出视频中所有字幕轨道
srt-trans embed <video> <srt>           将 .srt 嵌入视频文件
srt-trans search-sub <video>            从 OpenSubtitles 搜索字幕并对齐时间轴
srt-trans diff <original> <translated>  对比原始与翻译字幕，检查是否有遗漏

~~Web UI~~

~~Web UI 暂不可用。~~

翻译机制

• 字幕按批次发送给 LLM（默认每批 30 条），减少 API 调用次数
• LLM 返回格式异常时自动重试，重试失败降级为逐条翻译，保证结果完整
• 时间轴完整保留，仅替换文字内容
• 翻译完成后自动执行 diff 检查，报告缺失块

项目结构

srtTrans/
├── config.example.yaml       # 配置示例
├── src/
│   ├── core/
│   │   ├── srtParser.js      # 解析 / 写入 .srt
│   │   ├── extractor.js      # ffmpeg 提取 / 嵌入字幕
│   │   ├── translator.js     # LLM 翻译引擎
│   │   ├── osHash.js         # OpenSubtitles 视频哈希计算
│   │   ├── opensubtitles.js  # OpenSubtitles API 客户端
│   │   └── aligner.js        # 字幕时间轴对齐
│   └── cli/
│       └── index.js          # CLI 入口
└── package.json