SRT Translator CLI

A Python tool to translate SRT subtitle files using the Pollinations AI API while preserving timing information. It might take a few hours to translate the subs for a full-length movie, but it's completely free!!

✨ Free to use - No API key required!

Quick Start

# 1. Install dependencies
pip install -r requirements.txt

# 2. Translate an SRT file (that's it!)
python translate_srt.py input.srt

# 3. Or translate to a specific language
python translate_srt.py input.srt -t es  # Spanish
python translate_srt.py input.srt -t fr  # French

Features

• Parses SRT files and preserves all timing information
• Isolates subtitle text for translation
• Supports batch translation for efficiency
• Configurable source and target languages
• Range translation: translate specific subtitle ranges using --start-index and --end-index
• Incremental saving: translations are saved progressively to prevent data loss
• Error handling with fallback to individual translations

Installation

1. Install dependencies:

pip install -r requirements.txt

2. Make the script executable (optional):

chmod +x translate_srt.py

Configuration

API Setup

Good News: Pollinations AI is completely free and doesn't require an API key for basic usage! 🎉

The script works out of the box without any configuration. However, you can optionally configure:

1. API Key (optional - for higher rate limits and priority access):

   • Anonymous: Free access, concurrency cap of 1
   • Seed (🌱): Standard models, concurrency cap of 3
   • Flower (🌸): Advanced models, concurrency cap of 7
   • Nectar (🍯): All models with priority access, concurrency cap of 50

2. Configuration via environment variables (optional):

export POLLINATION_API_KEY="your_api_key_here"  # Optional
export POLLINATION_API_URL="https://text.pollinations.ai/"  # Optional, if different
export POLLINATION_MODEL="openai"  # Optional, default model

3. Configuration via command-line arguments (optional):

python translate_srt.py input.srt --api-key YOUR_KEY --model openai

Usage

Basic Usage

Translate an SRT file to English (default):

python translate_srt.py input.srt

Specify Output File

python translate_srt.py input.srt -o translated.srt

Specify Languages

# Translate from English to Spanish
python translate_srt.py input.srt -s en -t es

# Auto-detect source language, translate to French
python translate_srt.py input.srt -t fr

Complete Example

python translate_srt.py "One.Battle.After.Another.2025.1080p.AMZN.WEB-DL.DDP5.1.H.264-KyoGo.srt" \
  -o "One.Battle.After.Another.Spanish.srt" \
  -s en \
  -t es \
  --timeout 90 \
  --delay 2.0

Translate a Specific Range

# Translate only subtitles 1-100
python translate_srt.py input.srt -o output.srt -t es --end-index 100

# Resume translation from subtitle 101 onwards
python translate_srt.py input.srt -o output.srt -t es --start-index 101

# Translate only subtitles 50-150
python translate_srt.py input.srt -o output.srt -t es --start-index 50 --end-index 150

Handling Timeouts

If you're getting timeout errors:

# Increase timeout and add more delay
python translate_srt.py input.srt -t es --timeout 120 --delay 2.0 --max-retries 5

Command-Line Options

positional arguments:
  input                 Input SRT file path

optional arguments:
  -h, --help            Show help message and exit
  -o, --output OUTPUT   Output SRT file path (default: input_translated.srt)
  -s, --source SOURCE   Source language code (default: auto)
  -t, --target TARGET   Target language code (default: en)
  --api-key API_KEY     Optional Pollination API key (for higher rate limits)
  --api-url API_URL     Pollination API URL (default: https://text.pollinations.ai/)
  --model MODEL         Model to use for translation (default: openai)
  --timeout SECONDS     Request timeout in seconds (default: 60)
  --max-retries NUM     Maximum retries for failed requests (default: 3)
  --delay SECONDS       Delay between requests in seconds (default: 2.0)
  --start-index NUM     Start translating from this subtitle index (default: 1)
  --end-index NUM       Stop translating at this subtitle index (inclusive)

Reliability Options Explained

• --timeout 60: How long to wait for each API response (increase if getting timeouts)
• --max-retries 3: How many times to retry failed requests (increase for reliability)
• --delay 2.0: Seconds to wait between requests (increase to avoid rate limits)

Range Translation Options

• --start-index 1: Start translating from a specific subtitle number (useful for resuming interrupted translations)
• --end-index NUM: Stop at a specific subtitle number (useful for translating only a portion of the file)

Language Codes

Common language codes (adjust based on Pollination API documentation):

• en - English
• es - Spanish
• fr - French
• de - German
• it - Italian
• pt - Portuguese
• ja - Japanese
• ko - Korean
• zh - Chinese
• auto - Auto-detect

API Integration

The script is now properly configured to work with the Pollinations AI Text API:

• Endpoint: https://text.pollinations.ai/
• Format: Uses a messages-based format similar to ChatGPT
• Authentication: Optional Bearer token for higher tier access
• Models: Supports multiple models (default: openai)
• Free to use: No API key required for basic usage

The script sends translation requests as chat messages and handles both plain text and JSON responses from the API.

How It Works

1. Parsing: The script reads the SRT file and separates it into entries containing:

   • Subtitle index number
   • Timestamp (start --> end)
   • Text content

2. Translation: Text content is extracted and sent to the Pollination API in batches

3. Reconstruction: The translated text is combined with the original timing information to create a new SRT file

Error Handling

• If batch translation fails, the script falls back to individual subtitle translation
• If a translation request fails, the original text is preserved
• Progress indicators show translation status

Example Output

Input:

1
00:01:33,135 --> 00:01:34,303
Welcome.

2
00:01:38,182 --> 00:01:41,352
Our best guess, there's about
250, 275 people in there.

Output (translated to Spanish):

1
00:01:33,135 --> 00:01:34,303
Bienvenido.

2
00:01:38,182 --> 00:01:41,352
Nuestra mejor estimación, hay alrededor
250, 275 personas allí.

Troubleshooting

Connection Errors

Verify:

• Your internet connection is working
• The API endpoint https://text.pollinations.ai/ is accessible
• If using an API key, ensure it's valid

Timeout Errors

If you get "Read timed out" errors:

• Increase timeout: --timeout 120 (gives 2 minutes per request)
• Add more delay: --delay 2.0 (waits 2 seconds between requests)
• More retries: --max-retries 5 (retries failed requests up to 5 times)
• Combination: --timeout 90 --delay 2.0 --max-retries 5

The script now includes:

• ✅ Automatic retry with exponential backoff
• ✅ Individual subtitle processing (no batching)
• ✅ 60-second default timeout (was 30s)
• ✅ 1-second delay between requests

Translation Quality Issues

• Try different models with --model parameter
• Specify source language explicitly with -s instead of using auto
• Check the language codes match Pollinations AI's supported languages

Rate Limiting

If you encounter rate limits on the free tier:

• Increase delay: --delay 3.0
• Consider getting an API key for higher tier access (see Pollinations AI for details)

For detailed troubleshooting, see TROUBLESHOOTING.md

License

MIT