Srtx

Srtx is a typed Python package and command-line tool for translating SRT subtitle files with the regular Gemini Developer API.

The current release implements one focused workflow:

• Read one local .srt file.
• Translate its subtitle text into a target language.
• Process subtitles in deterministic batches.
• Preserve indexes, timestamps, ordering, HTML tags, line breaks, and empty subtitle text.
• Write a translated SRT file.
• Return a typed result to Python callers.
• Display progress through the command-line interface.

Resume support, streaming, audio context, transcription, media extraction, multiple API keys, and token reports are not part of the current release.

Requirements

• Python 3.13 or later
• A regular Gemini API key
• uv, or another Python package installer

Installation

Using uv:

uv sync

Install the package into another project:

uv add /path/to/Srtx

Alternatively:

python -m pip install /path/to/Srtx

API key

The recommended approach is to use an environment variable:

export SRTX_API_KEY="your-gemini-api-key"

Srtx also recognizes:

export GEMINI_API_KEY="your-gemini-api-key"

An explicitly supplied API key takes precedence over environment variables.

Avoid passing API keys directly on a shared command line because they may be stored in shell history.

Command-line usage

Translate an English subtitle file into Persian:

srtx translate movie.srt --to Persian --batch-size 100

The same command can be run through Python:

python -m srtx translate movie.srt --to Persian --batch-size 100

Choose an explicit output path:

srtx translate movie.srt \
    --to Persian \
    --output movie.fa.srt \
    --batch-size 100

Choose a model:

srtx translate movie.srt \
    --to Persian \
    --model gemini-3.5-flash

Show all CLI options:

srtx translate --help

If no output path is supplied, Srtx writes the result beside the source file:

movie.srt
movie_translated.srt

An existing destination file is overwritten. The source file itself cannot be used as the output path.

Direct Python API

import srtx

result = srtx.translate(
    "movie.srt",
    target_language="Persian",
    batch_size=100,
)

print(result.output_path)
print(result.translated_lines)

Library code does not print progress or configure logging. The print() calls above belong to the calling application.

Configured facade API

import srtx

srtx.configure(
    api_key="your-gemini-api-key",
    target_language="Persian",
    batch_size=100,
)

first_result = srtx.translate("episode-01.srt")
second_result = srtx.translate("episode-02.srt")

Arguments passed directly to translate() override configured defaults.

Explicit object-oriented API

from srtx import Srtx, TranslationSettings

application = Srtx(
    translation_settings=TranslationSettings(
        api_key="your-gemini-api-key",
        target_language="Persian",
        batch_size=100,
    )
)

result = application.translate("movie.srt")

An explicit output path can be supplied as the second argument:

result = application.translate(
    "movie.srt",
    "movie.fa.srt",
)

Translation result

Every successful Python translation returns TranslationResult with:

• input_path: Path
• output_path: Path
• translated_lines: int
• total_lines: int

Progress integration

Core translation emits provider-independent ProgressEvent objects. Applications can provide their own sink:

from srtx import Srtx, TranslationSettings
from srtx.domain.progress import ProgressEvent


class GuiProgressSink:
    def emit(self, event: ProgressEvent) -> None:
        update_gui(
            stage=event.stage,
            percentage=event.percentage,
            message=event.message,
        )


application = Srtx(
    translation_settings=TranslationSettings(
        target_language="Persian",
    ),
    progress_sink=GuiProgressSink(),
)

The CLI supplies its own Rich progress sink. Rich is not imported by core translation services.

Error handling

Expected failures derive from SrtxError:

import srtx

try:
    srtx.translate(
        "movie.srt",
        target_language="Persian",
    )
except srtx.SrtxError as error:
    handle_translation_failure(error)

Failures include:

• Missing or invalid API configuration
• Invalid input and output paths
• Malformed SRT data
• Invalid Gemini responses
• Gemini quota, overload, and blocked-response errors
• File read and write failures

Library code raises typed exceptions instead of printing or exiting. The CLI converts these exceptions into readable terminal errors.

Development checks

uv run pytest
uv run ruff check .
uv run pyright
git diff --check

Tests use fake providers by default and do not require a real Gemini API key.