LLM-Subtrans: Subtitle Translation Through Provider APIs, Not Local Models
Open Source project using LLMs to translate subtitles (SRT, SSA/ASS, VTT)
At a glance
- What is it?
- LLM-Subtrans is a Python subtitle translator that routes SRT, SSA/ASS and VTT files through hosted LLM providers. It is a thin, provider-agnostic client, and the quality you get depends almost entirely on which API key you paste in.
- Who is it for?
- Adopt LLM-Subtrans if you already pay for an LLM API and need batch subtitle translation across SRT, SSA/ASS and VTT without sending files through a web upload form. Do not adopt it if your subtitles cannot leave your network, or if you expected a local model to do the work: the README states plainly that quantized consumer-GPU models tend to produce poor translations, invalid responses or endless loops.
- Can I use it commercially?
- Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
- Is it still maintained?
- Yes. The repository last received commits 1 day ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The Problem: Subtitle Files Are Structured, and Chat Interfaces Ignore That
Pasting subtitle text into a chat window loses everything that makes a subtitle file a subtitle file. SRT and VTT carry sequence numbers and timecodes, SSA/ASS carries style and positioning data, and a translation that drops or reorders those breaks the file in a player. LLM-Subtrans exists to keep the container intact while the text inside it changes language. The README describes it as an open source subtitle translator that uses LLMs as a translation service, capable of translating between any language pairs the model supports, with a pluggable format system covering .srt, .ssa/.ass and .vtt. The audience is narrow and identifiable: people who already hold an API key from one of the supported providers and want a repeatable batch job rather than a browser tab. It is not aimed at someone who wants a free web app. The README notes that the Gemini-powered LLM-Subtrans Web was retired because it was costing the maintainer money, and points users to Google AI Studio if they want to rebuild it themselves.
How Translation Actually Flows: Batches, a Prompt Template, and a Provider Endpoint
The architecture visible in the README is a client, not a model host. Subtitle files are parsed by format-specific handlers, the text is assembled into batches, and each batch is sent to a provider over that provider's API. The README's Custom Server section exposes the mechanism most clearly: the tool can talk to any server exposing an OpenAI-compatible API, chat and completion endpoints are both supported, and the prompt template is editable in the GUI. That template must contain at least the {prompt} tag, described as the place where the subtitles for each batch are filled in. So the pipeline is: parse, batch, substitute into template, POST to endpoint, parse the response back into the original timing structure. Two consequences follow. First, translation quality is a property of the model and the template, not of this program, which is why the README's provider notes read like model reviews rather than feature lists. Second, anything that changes the response shape breaks the round trip, which is exactly what the v1.6.1 release note about a fix for Sonnet 5 and the v1.5.8 note about error handling and retry for certain providers describe. Version 1.6.0 added support for terminology maps, a mechanism for pinning names and recurring terms so they do not drift between batches.
Getting It Running: Packaged Builds, gui-subtrans, and --auto
The README states that for most users the packaged release is the easiest path: download from the releases page, unzip, and run gui-subtrans, then answer some basic settings on first run. Windows receives a gui-subtrans-x.x.x.zip for every release. macOS builds are usually provided for Apple Silicon as gui-subtrans-x.x.x.macos-arm64.zip, and Intel Mac owners are directed to install from source. Linux gets no prebuilt package at all, so source installation is the only route there. The command line is where the provider switches live. OpenRouter offers a Use Default Model setting in the GUI, or --auto on the command line, to let the aggregator pick the model, with model preferences configurable in the OpenRouter dashboard. DeepSeek accepts an optional API Base for self-hosted instances and defaults to deepseek-chat, with deepseek-reasoner suggested for source subtitles carrying OCR or transcription errors because it spends longer inferring what the error was. Mistral accepts --server_url for custom deployments. The README recommends mistral-large-latest and warns that smaller Mistral models perform poorly and may not follow system instructions. One constraint sits above all of this: an active internet connection is required, and subtitles are sent to the provider's servers under that provider's privacy policy.
Where It Breaks: Censorship, Rate Limits and the Local Model Trap
The most concrete failure mode in the README concerns Gemini. It states that Gemini will refuse to translate content containing certain words or phrases even with minimal safety settings, and the suggested workaround is to switch provider or split the batch and translate the offending lines by hand. That is a manual intervention inside an otherwise automated job, and it scales badly across a season of episodes. Anthropic carries a different constraint: the README notes strict rate limits tied to credit tier, on both requests per minute and tokens per day, alongside the observation that translation is not Claude's strongest suit and the API is expensive relative to others. OpenAI API keys tied to a free trial are described as severely speed-restricted. Then there is the local model case, which the README addresses head-on in the Custom Server section: this route is mainly for research, and users should not expect particularly good results, because small quantized models on a consumer GPU are likely to produce poor translations, fail to generate valid responses, or get stuck in endless loops. If your reason for choosing this tool is data residency, the Custom Server path is the only one that keeps subtitles on your hardware, and the README says that path is the weakest on quality. Amazon Bedrock is listed but explicitly not recommended for most users, with setup described as complex and requiring AWS credentials, IAM permissions and region configuration.
What It Is Not: Comparing the Approach to a Dedicated Translation Service
The obvious alternative is a conventional machine translation service with a subtitle-aware API, or a subtitle editor with an integrated translation feature. The difference is architectural. A dedicated MT service ships a translation model trained for the language pair; LLM-Subtrans ships no model at all and instead borrows general-purpose chat models through a template you can edit. That gives you model choice, which is the point: swapping from DeepSeek to Gemini to Mistral is a settings change, and OpenRouter alone aggregates hundreds of models grouped by family, with the default list pulled from the Translation category. It also means you inherit every quirk of the model you pick, from Gemini's refusals to a small model's malformed output. A dedicated service gives you a stable, predictable output contract and no prompt to maintain. LLM-Subtrans gives you flexibility and puts the prompt, the batching and the provider behaviour in your hands. Neither is strictly better; they fail in different ways. The README's own provider commentary makes the trade-off explicit rather than hiding it, which is more honest than most tool documentation manages.
Maintenance Cost and the Licence Question
The release cadence visible in the supplied material is provider-driven rather than feature-driven. v1.5.8 fixed error handling and retry for certain providers, v1.6.0 added terminology maps, and v1.6.1 fixed Sonnet 5 and added the Requesty provider. Every one of those is a response to something changing outside the repository: a model revision, a provider outage pattern, a new aggregator. The practical consequence is that this tool needs updating whenever your provider changes its API or model lineup, and an unmaintained copy will eventually start failing on the provider side rather than the parsing side. Budget for that. On licensing, the repository metadata reports NOASSERTION, which means GitHub could not map the project's licence file to a recognised SPDX identifier. The README does not state a licence. That is not a reason to avoid the project, but it is a reason to read the actual licence file in the repository before shipping the tool inside a commercial pipeline, and to take advice if the terms are ambiguous. No legal conclusion can be drawn from the metadata alone.
Who Should Run This, and What to Check First
The tool fits a workflow where subtitles are already being produced or ingested in bulk and an API budget exists. A subtitling shop translating a back catalogue into several languages, with an OpenRouter or DeepSeek key and a terminology map for character names, is the sweet spot. The command line plus --auto keeps the model choice out of the way until quality problems appear. The wrong user is anyone whose content cannot leave their network, since the README states that subtitles go to the provider's servers, and the only local option is the Custom Server path the README itself describes as research-grade. The second wrong user is anyone expecting a polished free experience: the hosted web version is gone, and every provider needs a key and usually a credit balance, though OpenRouter notes some capable models are free. Practically, the first thing to verify is a single episode through your chosen provider before committing to a series, because provider refusals and malformed responses show up per batch and are cheaper to discover on one file than on fifty. The second is the licence file itself, given the NOASSERTION metadata. The third is your provider's rate limits against the length of your queue, since Anthropic's tier-based limits and OpenAI's trial restrictions are both documented constraints rather than edge cases.
Editorial conclusion
Adopt LLM-Subtrans if you already pay for an LLM API and need batch subtitle translation across SRT, SSA/ASS and VTT without sending files through a web upload form. Do not adopt it if your subtitles cannot leave your network, or if you expected a local model to do the work: the README states plainly that quantized consumer-GPU models tend to produce poor translations, invalid responses or endless loops. Before committing, verify three things: that your chosen provider does not refuse your content (Gemini censorship is documented), that your credit tier clears the provider's rate limits, and that the licence actually permits your use, because the repository metadata reports NOASSERTION rather than a recognised SPDX identifier.
Community notes