subfanyi 0.1.0

Translate subtitles and documents from your terminal

fanyi

Translate subtitles and documents from your terminal.

fanyi is a command-line translation tool built for subtitle files. It supports SRT, ASS/SSA, and VTT formats out of the box, with additional support for plain text, Markdown, PDF, DOCX, and audio files. Powered by multiple translation engines including OpenAI, DeepL, and local models via Ollama.

Features

• Subtitle-first design - Native support for SRT, ASS/SSA, and VTT with timing preservation
• Multiple translation engines - OpenAI, DeepL, Ollama (local), or bring your own via plugins
• Batch processing - Translate entire folders of subtitle files in one command
• Context-aware translation - Use --context-lines to give the engine dialogue context for better translations
• Smart caching - Skip already-translated segments to save time and API costs
• Resumable jobs - Pick up where you left off if a translation is interrupted
• Glossary support - Define term mappings to ensure consistent translations
• Format detection - Automatically identifies file formats and encodings (including BOM)

Installation

pip install fanyi

Quick Start (30 seconds)

Translate an SRT subtitle file using the built-in mock engine (no API key needed):

fanyi subs movie.srt --target zh --engine mock

For real translations with OpenAI:

export OPENAI_API_KEY=your-key-here
fanyi subs movie.srt --target ja --engine openai

Translate all subtitles in a folder:

fanyi subs ./subtitles/ --target ko --engine openai

Supported Formats

Format	Extension	Description
SRT	.srt	SubRip subtitle format
ASS/SSA	.ass, .ssa	Advanced SubStation Alpha
VTT	.vtt	WebVTT subtitle format
Text	.txt	Plain text files
Markdown	.md	Markdown documents
PDF	.pdf	PDF documents (read-only extraction)
DOCX	.docx	Microsoft Word documents
Audio	.mp3, .wav	Audio transcription + translation

Supported Engines

Engine	Description	Requires API Key
OpenAI	GPT-based translation with high quality	Yes
DeepL	Professional translation API	Yes
Ollama	Local LLM models (no data leaves your machine)	No
Mock	Built-in test engine for development/CI	No

Configuration

Environment Variables

export OPENAI_API_KEY=your-openai-key
export DEEPL_API_KEY=your-deepl-key
export OLLAMA_HOST=http://localhost:11434

Config File

Create a config file at ~/.config/fanyi/config.yaml:

default_engine: openai
default_target: zh
engines:
  openai:
    model: gpt-4
    temperature: 0.3
  deepl:
    formality: more
  ollama:
    model: llama3
    host: http://localhost:11434

View current configuration:

fanyi config

Subtitle Translation

The subs command is optimized for subtitle workflows:

# Translate a single file
fanyi subs episode01.srt --target zh

# Translate with dialogue context for better quality
fanyi subs episode01.srt --target zh --context-lines 3

# Batch translate a folder
fanyi subs ./season1/ --target ja --engine openai

Context-Aware Translation

Use --context-lines to send surrounding dialogue lines to the engine. This helps produce translations that account for conversational flow:

fanyi subs interview.vtt --target fr --context-lines 5

CLI Commands

fanyi translate   # Translate any supported file
fanyi subs        # Subtitle-optimized translation
fanyi list-engines   # Show available engines
fanyi list-formats   # Show supported formats
fanyi config      # View/manage configuration
fanyi check       # Verify engine connectivity
fanyi cache       # Manage translation cache
fanyi jobs        # View and resume translation jobs
fanyi plugins     # Manage plugins
fanyi history     # View translation history

License

MIT