subtrans

subtrans extracts the first usable subtitle track from video files, translates it, and writes a sidecar subtitle that VLC can auto-load. If a video has no embedded subtitle track, subtrans falls back to an existing sidecar .srt next to it (Movie.srt or Movie.<tag>.srt, e.g. Movie.en.srt) and translates that instead. By default it opens a small native graphical window with progress and live logs.

By default it searches the current directory recursively, translates to Hebrew, and writes files like:

Movie.mkv
Movie.heb.srt

Dependencies

• Internet access for translation

Release binaries embed ffmpeg, so they work offline (apart from translation) and never download it at runtime. On first use subtrans extracts the embedded ffmpeg into the OS user cache and reuses that copy on later runs; if the cache is deleted it is re-extracted. If an ffmpeg is found next to the executable it is preferred.

Binaries built from source without the embedffmpeg build tag do not contain ffmpeg; those fall back to downloading it into the user cache on first use.

The translator uses the free, unofficial Google Translate endpoint. It does not require an API key, but it is not an SLA-backed Google Cloud API and may rate-limit or change behavior. Translation still requires network access.

Usage

subtrans [flags] [directory-or-video]

Examples:

subtrans
subtrans /path/to/videos
subtrans --cli /path/to/videos
subtrans -lang fr -overwrite movie.mkv
subtrans -recursive=false ~/Movies
subtrans --register

The graphical window shows timestamped progress logs while it scans, resolves cached ffmpeg, extracts subtitles, translates batches, and writes output files. You can also drag video files or folders onto the window; dropped files are processed in place and the translated .srt is saved alongside each video. Use --cli to run without the graphical window.

Existing target subtitles are skipped by default. For example, if Movie.heb.srt already exists, Movie.mkv is not processed again unless -overwrite is set.

Use subtrans --register once to add the executable's directory to your user PATH so future terminals can run subtrans from any directory.

Flags:

  -lang string       target language code (default "he")
  -source string     source language code (default "auto")
  -recursive         search subdirectories (default true)
  -overwrite         overwrite existing translated subtitle files
  -register          add this executable's directory to the user PATH and exit
  -cli               run in command-line mode without opening the graphical log window
  -min-size int      minimum usable extracted subtitle size in bytes (default 32)
  -timeout duration  HTTP translation timeout (default 30s)
  -version           print version

Release builds

The GitHub Actions workflow builds:

• Windows amd64: subtrans-windows-amd64.exe
• macOS arm64: subtrans-darwin-arm64

On a push to main or a manual workflow run, the workflow creates the next patch tag. If the repository has no tags yet, it starts at v0.1.0, then creates a GitHub release with downloadable executable assets and a commit history in the release description.