Translation & LLM

Translation & LLM

Sublarr supports optional subtitle translation. Translation is off by default and is treated as an experimental feature — turn it on only if you need it. Backends fall into two camps:

• Cloud backends (DeepL, Claude, Gemini, OpenAI, DeepSeek, Mistral, Google, Azure, MyMemory) — currently the most reliable choice for production-grade output. Subtitle text leaves your server.
• Ollama (local LLM) — fully offline, no API keys, no data egress. Quality is improving but still rough at the edges; use general-purpose models like qwen2.5:14b or llama3.1:8b.

Note

For the current release, start with a general-purpose Ollama model or one of the cloud backends below. Custom fine-tunes are only recommended when you have tested them against your own subtitles and configured the exact model name in Sublarr.

Enabling translation

Translation ships disabled. To turn it on:

1. Open Settings and select Translation in the left-hand settings navigation.
2. On the Translation page, click Translation aktivieren (“Enable translation”) in the beta banner at the top.
3. The page switches to its full configuration view — pick and configure a backend below.

To turn it back off later, use the Disable Translation button at the bottom of the same page.

Caution

SUBLARR_TRANSLATION_ENABLED as an environment variable is intentionally ignored — translation is enabled only through the in-app toggle above. There is no separate “beta image”; the normal release image already contains the feature.

Configuring Ollama

Install Ollama on the host that runs Sublarr (or on a reachable LAN host), pull a general-purpose model, then point Sublarr at it:

ollama pull qwen2.5:14b-instruct
# or, lighter:
ollama pull llama3.1:8b-instruct

Set in Settings → Translation → Backends → Ollama:

Field	Example
Endpoint URL	http://ollama:11434
Model	qwen2.5:14b-instruct

Translation Backends

Sublarr ships 12 translation backends. Configure them in Settings → Translation Backends. Every backend records per-call cost, latency and token usage; visit Settings → Translation → Cost & Memory to compare.

Backend	Type	Self-Hosted	API Key	Best For
Ollama	Local LLM	Yes	No	Full control, custom prompts, GPU-accelerated
OpenAI-compatible	LLM	Both	Yes	GPT-4 / local OpenAI-compatible endpoints
OpenAI ChatGPT	LLM API	No	Yes	GPT-4o / GPT-4-turbo via official endpoint
Anthropic Claude	LLM API	No	Yes	High-quality long-context translation
Google Gemini	LLM API	No	Yes	Fast Gemini 2.x with native multilingual support
DeepSeek	LLM API	No	Yes	Cost-effective Chinese-LLM provider
Mistral	LLM API	No	Yes	EU-hosted LLM, GDPR-friendly
DeepL	NMT API	No	Yes	Highest-quality NMT for EU languages
Google Translate	NMT API	No	Yes	Broad language support, fast
LibreTranslate	NMT API	Yes	Optional	Self-hosted, privacy-focused fallback
Azure Translator	NMT API	No	Yes	Enterprise-grade NMT with regional endpoints
MyMemory	NMT API	No	Optional	Free tier, useful as zero-cost fallback

Tip

The Live Translation Queue dashboard (Activity → Translation Queue) shows in-flight jobs across all backends with per-job cancellation. Cancelled jobs raise JobCancelledError so partial work is rolled back cleanly.

Configuring Ollama (Default):

1. Install Ollama on your server
2. Pull a model: ollama pull qwen2.5:14b-instruct
3. In Sublarr: Settings > Translation Backends > Ollama
4. Enter your Ollama URL and model name
5. Click Test to verify

Fallback Chains: Configure backup backends in case your primary fails. Example:

1. Primary: Ollama (local, fast, free)
2. Fallback 1: DeepL (cloud, high quality)
3. Fallback 2: LibreTranslate (self-hosted backup)

Ollama Chat API and Series Context

See Settings → Translation → Ollama Chat API for the full reference including how to configure system prompts and series context injection.

Prompt Presets

Settings → Translation → Prompt Presets

Prompt presets let you save and reuse prompt templates across translation backends. Sublarr auto-creates one default preset on first run. The marked-default preset is what get_prompt_template() loads; switching a preset to default takes effect immediately for the next translation job without restarting.

Each preset is a free-form text field. Two variables are substituted at load time:

Variable	Replaced with
{source_language}	Full name of the source language (e.g. English)
{target_language}	Full name of the target language (e.g. German)

For Ollama in Chat API mode, the system prompt field additionally supports:

Variable	Replaced with
{series_context}	Show synopsis from Sonarr/Radarr metadata, if available

Caution

The Settings UI displays a hint box listing {title}, {context}, {source_lang}, {target_lang}, and {line_count} as “available variables”. These short-form names are not substituted by the current backend — only {source_language}, {target_language}, and (Ollama Chat API only) {series_context} are actually replaced at runtime. Using the short forms will cause them to appear verbatim in the prompt sent to the model.

Tip

A minimal working preset that respects the configured language pair:

Translate these anime subtitle lines from {source_language} to {target_language}.
Return ONLY the translated lines, one per line, same count.
Preserve \N exactly as \N (hard line break).
Do NOT add numbering or prefixes to the output lines.

Episode Context

Settings → Translation → Backends → Episode Context

When enabled, Sublarr prepends the subtitle text from one or more previous episodes as context, giving the LLM enough dialogue history to keep character voice, pronouns, and proper nouns consistent across an entire series.

Setting	Default	Values	Effect
Use Episode Context	Off	toggle	Include prior-episode subtitles as translation context
Context Episodes	1	1–5	How many previous episodes to draw context from
Auto Series Glossary	Off	toggle	Automatically extract a per-series glossary from existing translated subtitles

Note

Episode context and auto-glossary only apply to LLM backends (Ollama, Claude, Gemini, OpenAI, etc.). NMT backends such as DeepL and Google Translate silently ignore these settings.

Caution

Both options increase token usage — episode context adds one full subtitle file to the system prompt per episode, and auto-glossary injects up to glossary_max_terms (default 100) term pairs. Expect noticeably longer per-batch times and higher API costs when these are enabled on large series.

Advanced LLM Tuning

Settings → Translation → Backends

Global request settings

The “Global LLM Request Settings” card exposes controls that apply to all LLM backends as fallback defaults:

Setting	Default	Range	Effect
Request Timeout	90 s	10–600	Seconds before an in-flight LLM API call is killed; raise for slow local models or large batches
Backoff Base	5 s	1–60	Base interval for exponential back-off between retry attempts

Additional global tuning knobs exist in the underlying settings store (not directly exposed in this card):

Setting	Default	Values	Effect
temperature	0.3	0.0–1.0	Sampling temperature; lower = more deterministic output
max_retries	3	integer	Retry attempts before a batch is considered failed
translation_max_workers	4	integer	Parallel worker threads in the translation job queue
batch_size	15	integer	Subtitle lines sent per LLM request

Context window (lookback / lookahead)

LLM backends receive surrounding lines as read-only context to improve pronoun resolution and terminology consistency across batch boundaries. This is controlled by three settings:

Setting	Default	Range	Effect
Context Window	On	toggle (translation_context_enabled)	Enable/disable lookback+lookahead entirely
Lookback lines	10	0–50 (translation_context_lookback_lines)	Lines before each batch shown as context only
Lookahead lines	5	0–50 (translation_context_lookahead_lines)	Lines after each batch shown as context only

Each line of context adds approximately 6 extra tokens. At the defaults (10 + 5 = 15 context lines, 15-line batches) this costs roughly 90 additional tokens per request — negligible for cloud APIs but noticeable on small local models.

Non-LLM backends (DeepL, Google Translate, LibreTranslate, Azure, MyMemory) ignore all context-window settings.

Per-backend vs global precedence

Caution

This is the most common point of confusion.

Each backend’s config card stores its own temperature, request_timeout, max_retries, and backoff_base independently (as backend.<name>.* entries). When a backend has been individually configured, it uses its own values exclusively — the global controls on the “Global LLM Request Settings” card have no effect on that backend.

The global values act as defaults only for backends that have never been individually saved. Once you click Save on a backend’s card, that backend owns its own copy of every tunable parameter. To change it afterwards you must edit the backend’s card directly, not the global card.

Practically: if you want to give your Ollama instance a 300 s timeout without touching other backends, expand the Ollama card, set Timeout to 300, and save. The global timeout remains 90 s for any backend you have not individually configured.