ai-sub-translator

AI-powered subtitle translator using Google Gemini. Translates SRT subtitle files to any language.

Installation

npm install ai-sub-translator

Quick Start

import { translate } from 'ai-sub-translator';
import { readFileSync } from 'fs';

const srtContent = readFileSync('movie.srt', 'utf-8');

const result = await translate({
  text: srtContent,
  targetLanguage: 'French',
  apiKey: 'your-gemini-api-key',
  context: 'Breaking Bad S01E01',
  onProgress: (p) => console.log(`${Math.round(p * 100)}%`),
});

console.log(result.translatedText);

API

translate(options): Promise<TranslateResult>

Translates SRT subtitle content to a target language using Google Gemini.

Options

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | text | string | Yes | - | SRT subtitle content | | targetLanguage | string | Yes | - | Target language (e.g., "French", "Spanish") | | apiKey | string | Yes | - | Google Gemini API key | | model | string | No | gemini-2.0-flash | Gemini model to use | | batchSize | number | No | 50 | Subtitles per translation batch | | context | string | No | '' | Movie/show name for better translation | | onProgress | (progress: number) => void | No | - | Progress callback (0-1 range) | | signal | AbortSignal | No | - | Cancellation signal |

Returns TranslateResult

{
  translatedText: string;   // Full translated SRT content
  totalBatches: number;     // Total batches processed
  completedBatches: number; // Completed batches
}

parseSrt(text): SrtEntry[]

Parses SRT content into structured entries.

import { parseSrt } from 'ai-sub-translator';

const entries = parseSrt(srtContent);
// [{ index: 1, timestamp: '00:00:01,000 --> 00:00:05,000', text: 'Hello' }, ...]

formatSrt(entries): string

Formats structured entries back into SRT content.

import { formatSrt } from 'ai-sub-translator';

const srt = formatSrt(entries);

Types

interface SrtEntry {
  index: number;
  timestamp: string;
  text: string;
}

interface TranslateOptions {
  text: string;
  targetLanguage: string;
  apiKey: string;
  model?: string;
  batchSize?: number;
  context?: string;
  onProgress?: (progress: number) => void;
  signal?: AbortSignal;
}

interface TranslateResult {
  translatedText: string;
  totalBatches: number;
  completedBatches: number;
}

Supported Models

All models have a free tier available from Google AI Studio:

• gemini-2.0-flash (default, recommended)
• gemini-2.5-flash
• gemini-1.5-flash
• gemini-1.5-flash-8b

Cancellation

const controller = new AbortController();

const result = translate({
  text: srtContent,
  targetLanguage: 'French',
  apiKey: 'key',
  signal: controller.signal,
});

// Cancel after 30 seconds
setTimeout(() => controller.abort(), 30000);

License

MIT