Public Python API

Direct translation

The smallest API call is:

import srtx

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

The API key is resolved in this order:

Explicit api_key
A key previously passed to srtx.configure()
SRTX_API_KEY
GEMINI_API_KEY

Configured facade

import srtx

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

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

Direct translate() arguments override configured defaults.

Explicit application object

from srtx import Srtx, TranslationSettings

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

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

This form is recommended for applications that want explicit ownership of configuration and progress reporting.

Translation settings

TranslationSettings contains:

Field	Type	Purpose
`target_language`	`str`	Required translation target
`api_key`	`str \| None`	Optional regular Gemini API key
`model`	`str`	Gemini model identifier
`batch_size`	`int`	Maximum subtitles per request

Target language and model values are stripped and must not be empty. Batch size must be a positive integer.

Translation result

translate() returns:

@dataclass(frozen=True, slots=True)
class TranslationResult:
    input_path: Path
    output_path: Path
    translated_lines: int
    total_lines: int

Output path behavior

Without an explicit destination:

/path/movie.srt
/path/movie_translated.srt

With an explicit destination:

result = srtx.translate(
    "movie.srt",
    target_language="Persian",
    output_path="subtitles/movie.fa.srt",
)

The destination parent directory must already exist. The output must use the .srt extension and must not be the same file as the input.

Custom progress sink

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


class ApplicationProgressSink:
    def emit(self, event: ProgressEvent) -> None:
        consume_progress(event)


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

Provider injection

Applications and tests may inject a provider implementing TextGenerationProvider:

application = Srtx(
    translation_settings=settings,
    provider=custom_provider,
)

Caller-supplied providers remain owned by the caller. Providers constructed internally by Srtx are closed by Srtx after translation.

Exceptions

Catch SrtxError when one error boundary is sufficient:

import srtx

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

More specific exceptions can be imported from srtx.exceptions.

Home