TROUBLESHOOTING.md

Troubleshooting Guide

Timeout Errors

Problem

Error translating text: HTTPSConnectionPool(host='text.pollinations.ai', port=443): Read timed out. (read timeout=30)

Solutions

1. Increase Timeout (Recommended)

The default timeout is now 60 seconds. If you still get timeouts, increase it:

python translate_srt.py input.srt -t es --timeout 120

This gives each request 2 minutes to complete.

2. Increase Delay Between Requests

Add more delay between requests to give the API breathing room:

python translate_srt.py input.srt -t es --delay 2.0

This waits 2 seconds between each subtitle translation.

3. Adjust Retry Settings

Increase the number of retries:

python translate_srt.py input.srt -t es --max-retries 5

4. Combine Multiple Settings

For best reliability with free tier:

python translate_srt.py input.srt -t es --timeout 90 --delay 2.0 --max-retries 5

What Changed

The script now:

• ✅ 60-second timeout (was 30s)
• ✅ Automatic retries with exponential backoff
• ✅ Delays between requests (1 second default)
• ✅ Individual subtitle processing (no more batching)
• ✅ Better error messages with retry indicators

Rate Limiting

Problem

Getting too many requests or rate limit errors.

Solutions

1. Increase delay:

   python translate_srt.py input.srt -t es --delay 3.0

2. Get an API key for higher tier access:

   • Visit Pollinations AI
   • Sign up for free tier (higher limits)
   • Use with: --api-key YOUR_KEY

Network Issues

Problem

Connection errors, DNS failures, or network timeouts.

Solutions

1. Check internet connection
2. Try a different network
3. Check if API is accessible:

   curl https://text.pollinations.ai/

Slow Translation

Why It's Slow

Translating 2,245 subtitles individually with delays:

• Default: 1 second delay × 2,245 = ~37 minutes minimum
• Plus translation time: ~1-2 hours total

Speed It Up

1. Reduce delay (may cause rate limiting):

   python translate_srt.py input.srt -t es --delay 0.5

2. Get API key for higher tier (up to 50 concurrent requests):

   python translate_srt.py input.srt -t es --api-key YOUR_KEY --delay 0.1

3. Try a different model (some might be faster):

   python translate_srt.py input.srt -t es --model mistral

Translation Quality Issues

Problem

Translation is incorrect or doesn't make sense.

Solutions

1. Specify source language explicitly:

   python translate_srt.py input.srt -s en -t es

2. Try a different model:

   python translate_srt.py input.srt -t es --model claude

Resume Interrupted Translation

Problem

Translation stopped midway and you want to continue.

Solution (Manual)

1. Open the partially translated SRT file
2. Find the last translated entry number (e.g., entry #150)
3. Edit the original script to skip already translated entries

Or:

1. Delete the partial output file
2. Re-run with better settings:

   python translate_srt.py input.srt -t es --timeout 120 --delay 2.0

API Response Issues

Problem

Getting empty translations or original text back.

Potential Causes

1. API might be down or rate-limited
2. Request format might not match API expectations
3. Model might not support the language

Solutions

1. Check API status:

   curl -X POST https://text.pollinations.ai/ \
     -H "Content-Type: application/json" \
     -d '{"messages":[{"role":"user","content":"Hello"}]}'

2. Try different model:

   python translate_srt.py input.srt -t es --model openai

3. Check language support:

   • Some models may not support all languages
   • Try common languages first (Spanish, French, German)

Command Examples for Common Issues

For Timeout Issues

python translate_srt.py "One.Battle.After.Another.2025.1080p.AMZN.WEB-DL.DDP5.1.H.264-KyoGo.srt" \
  -t es \
  -o "translated.srt" \
  --timeout 120 \
  --max-retries 5 \
  --delay 2.0

For Rate Limiting Issues

python translate_srt.py input.srt \
  -t es \
  --delay 3.0 \
  --max-retries 3

For Best Reliability (Slow but Stable)

python translate_srt.py input.srt \
  -t es \
  --timeout 120 \
  --delay 3.0 \
  --max-retries 5

For Speed (With API Key)

python translate_srt.py input.srt \
  -t es \
  --api-key YOUR_KEY \
  --timeout 60 \
  --delay 0.5

Understanding the Progress

You'll see messages like:

✅ Translated 10/2245 subtitles...
⏱️  Timeout on attempt 1/3. Retrying in 1.0s...
✅ Translated 20/2245 subtitles...

• ✅ = Successful translation
• ⏱️ = Timeout, retrying
• ⚠️ = Error, retrying
• ❌ = Failed after all retries (uses original text)

Getting Help

If none of these solutions work:

1. Check the Pollinations AI status page
2. Try again during off-peak hours
3. Consider using an alternative translation API
4. Open an issue with the error message and command you ran

Alternative Approach: Smaller Chunks

For very large files, consider splitting them:

1. Split your SRT into smaller files (500 subtitles each)
2. Translate each file separately
3. Combine the results

This makes it easier to resume if something fails.