omnicaptions-translate

字幕翻译

默认：Claude 原生翻译（无需 API 密钥）

仅在用户明确提出要求时使用 Gemini API。

默认工作流（Claude）

1. 读取字幕文件
2. 使用 Claude 的原生能力进行翻译
3. 使用 _Claude_{lang} 后缀写入输出文件

Gemini API（可选）

用户要求使用 Gemini 时，通过 CLI 使用：

omnicaptions translate input.srt -l zh --bilingual

输出：input_Gemini_zh.srt

适用场景

• 将 SRT/VTT/ASS 翻译成其他语言
• 生成双语字幕（原文 + 译文）
• 翻译 YouTube 视频转录文本
• 需要结合上下文进行翻译（而非逐行翻译）

不适用场景

• 需要转录（使用 /omnicaptions:transcribe）
• 只需转换格式，不需要翻译（使用 /omnicaptions:convert）

设置

pip install omni-captions-skills --extra-index-url https://lattifai.github.io/pypi/simple/

API 密钥

优先级：GEMINI_API_KEY 环境变量 → .env 文件 → ~/.config/omnicaptions/config.json

如果未设置，请询问用户：Please enter your Gemini API key (get from https://aistudio.google.com/apikey):

然后使用 -k <key> 运行。密钥将自动保存到配置文件。

结合上下文进行翻译

基于 LLM 的翻译优于传统机器翻译，因为它能理解多行字幕之间的上下文：

上下文为何重要

方法	问题	结果
逐行翻译	没有上下文	译文生硬、不连贯
批量 + 上下文	能看到周围的字幕行	对话自然、连贯

工作原理

┌─────────────────────────────────────────┐
│  Batch size: 30 lines                   │
│  Context: 5 lines before/after          │
├─────────────────────────────────────────┤
│  [5 previous lines] → context           │
│  [30 current lines] → translate         │
│  [5 next lines]     → preview           │
└─────────────────────────────────────────┘

优点：

• 说话者连贯性 - 保持角色的说话风格
• 拆分的句子 - 处理跨多行的对话
• 习语与文化 - 自然地转换文化典故
• 代词消歧 - 根据上下文正确判断 he/she/they

高级功能

双语输出

# Original + Translation (for language learning)
omnicaptions translate input.srt -l zh --bilingual

输出示例：

1
00:00:01,000 --> 00:00:03,500
Welcome to the show.
欢迎来到节目。

2
00:00:03,500 --> 00:00:06,000
Thank you for having me.
感谢邀请我。

自定义术语表（即将推出）

适用于特定领域或品牌内容：

# Use glossary for consistent terminology
omnicaptions translate input.srt -l zh --glossary terms.json

术语表格式：

{
  "API": "接口",
  "Token": "令牌",
  "Machine Learning": "机器学习"
}

优点：

• 术语一致性 - “一个术语，一种译法”
• 品牌规范 - 使用官方产品名称
• 领域准确性 - 医疗、法律、技术术语

最佳实践

1. 提供上下文以提升质量

对于专业内容，使用自定义提示词：

from omnicaptions import GeminiCaption

gc = GeminiCaption()
gc._translation_prompt = """
You are translating captions for a medical documentary.
Use formal Chinese medical terminology.
Glossary: {glossary}
"""
gc.translate("input.srt", "output.srt", "zh")

2. 选择合适的模型

模型	适用场景
gemini-3-flash-preview	快速处理日常内容
gemini-3-pro-preview	复杂、细致的内容

3. 检查双语输出

双语字幕方便观众核验翻译质量，特别适合：

• 语言学习者
• 质量保证
• 无障碍访问

CLI 用法

# Translate (auto-output to same directory)
omnicaptions translate input.srt -l zh         # → ./input_Gemini_zh.srt

# Specify output file or directory
omnicaptions translate input.srt -o output/ -l zh   # → output/input_Gemini_zh.srt
omnicaptions translate input.srt -o zh.srt -l zh    # → zh.srt

# Bilingual output (original + translation)
omnicaptions translate input.srt -l zh --bilingual

# Specify model
omnicaptions translate input.vtt -l ja -m gemini-3-pro-preview

选项	描述
-k, --api-key	Gemini API 密钥（缺失时会自动提示）
-o, --output	输出文件或目录（默认：与输入文件相同的目录）
-l, --language	目标语言代码（必填）
--bilingual	同时输出原文和译文
-m, --model	模型名称（默认：gemini-3-flash-preview）
-v, --verbose	详细输出

语言代码

语言	代码
中文（简体）	zh
中文（繁体）	zh-TW
日语	ja
韩语	ko
英语	en
西班牙语	es
法语	fr
德语	de

支持的格式

lattifai-captions 支持的所有格式：SRT、VTT、ASS、TTML、JSON、Gemini MD 等。

常见错误

错误	解决方法
没有 API 密钥	使用 -k YOUR_KEY 或按提示操作
语言代码错误	使用 ISO 代码：zh、ja、en 等
格式丢失	保留 ASS 样式；SRT 仅保留基本格式
术语不一致	技术内容请使用术语表

参考资料

• 字幕 LLM 翻译器 - 上下文窗口方案
• 字幕翻译器 - 批量处理
• Captions.Translate.Agent - 多 Agent 工作流

相关技能

技能	使用场景
/omnicaptions:transcribe	需要先生成转录文本
/omnicaptions:LaiCut	翻译前对齐时间
/omnicaptions:convert	翻译后转换格式
/omnicaptions:download	下载要翻译的字幕

工作流示例

重要：LaiCut 对齐后再生成双语字幕。

文件命名约定 - 保留语言标签和处理链：

video.en.vtt → video.en_LaiCut.json → video.en_LaiCut.srt → video.en_LaiCut_Claude_zh.srt → video.en_LaiCut_Claude_zh_Color.ass

翻译方式	后缀	示例
Claude（默认）	_Claude_zh	video.en_LaiCut_Claude_zh.srt
Gemini API	_Gemini_zh	video.en_LaiCut_Gemini_zh.srt

# 1. LaiCut 对齐 (保留词级时间)
omnicaptions LaiCut video.mp4 video.en.vtt
# → video.en_LaiCut.json

# 2. 转换为 SRT (翻译用，文件小)
omnicaptions convert video.en_LaiCut.json -o video.en_LaiCut.srt

# 3a. Claude 翻译 (默认)
# → video.en_LaiCut_Claude_zh.srt

# 3b. 或 Gemini 翻译
omnicaptions translate video.en_LaiCut.srt -l zh --bilingual
# → video.en_LaiCut_Gemini_zh.srt

# 4. 转换为带颜色的 ASS
omnicaptions convert video.en_LaiCut_Claude_zh.srt -o video.en_LaiCut_Claude_zh_Color.ass \
  --line1-color "#00FF00" --line2-color "#FFFF00"

大型 JSON 文件

LaiCut 输出包含单词级时间信息的 JSON。翻译时，请先转换为 SRT（体积小得多）：

# JSON (word-level, ~150KB) → SRT (segment-level, ~15KB)
omnicaptions convert video.en_LaiCut.json -o video.en_LaiCut.srt

为什么？JSON 会保留用于卡拉 OK 的单词时间信息，但翻译只需要片段文本。SRT 的体积小 10～20 倍。

Claude 翻译规则（默认）

1. 准确保留格式 - 保留所有时间码、格式标签和样式定义
2. 结合上下文 - 参考前后行，确保对话连贯
3. 保持说话者一致性 - 保持角色的声音和语气
4. 进行文化适配 - 自然地调整习语和文化典故
5. 处理大型文件 - 每批处理 100 行，以保证质量

Claude 与 Gemini 对比

特性	Claude（默认）	Gemini API
API 密钥	无需	必需
调用方式	技能（读取/写入）	CLI 命令
输出后缀	_Claude_{lang}	_Gemini_{lang}
最适合	大多数任务	大型文件、自动化