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 動画の文字起こしを翻訳する
• 文脈を考慮した翻訳が必要（1 行ずつではない）

使用しない場面

• 文字起こしが必要（/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 ベースの翻訳は、複数行にまたがる文脈を理解するため、従来の機械翻訳よりも優れています：

文脈が重要な理由

アプローチ	問題	結果
1 行ずつ	文脈がない	機械的で、つながりのない翻訳
まとめて＋文脈	前後の行を参照する	自然で、一貫性のある会話

仕組み

┌─────────────────────────────────────────┐
│  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 つの用語に 1 つの翻訳」
• ブランドへの準拠 - 公式の製品名を使用します
• 分野ごとの正確性 - 医療、法律、技術用語

ベストプラクティス

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 は基本的な書式のみです
用語が一貫しない	技術的なコンテンツでは用語集を使用します

参考資料

• Caption LLM Translator - コンテキストウィンドウを使用するアプローチ
• Caption Translator - バッチ処理
• Captions.Translate.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 はカラオケ用に単語単位のタイミングを保持しますが、翻訳に必要なのはセグメントのテキストだけです。SRT は 10〜20 倍小さくなります。

Claude の翻訳ルール（デフォルト）

1. 形式を正確に保持 - すべてのタイミングコード、書式タグ、スタイル定義を保持します
2. 文脈を考慮 - 一貫性のある会話になるよう、前後の行を考慮します
3. 話者の一貫性 - 登場人物の話し方や口調を維持します
4. 文化的な適応 - 慣用句や言及を自然に適応させます
5. 大きなファイル - 品質を維持するため、100 行ずつ処理します

Claude と Gemini の比較

機能	Claude（デフォルト）	Gemini API
API キー	不要	必須
呼び出し方法	スキル（Read/Write）	CLI コマンド
出力の接尾辞	_Claude_{lang}	_Gemini_{lang}
最適な用途	ほとんどのタスク	大きなファイル、自動化