youtube-translate
Skill4 starsChanged 11 days agoMITView on GitHub
Given YouTube links (videos, channels, playlists) or local folders/files (subtitles or media), produce per-language translated SRT subtitle files (default en, uk, de, fr, es, pl) ready to upload to YouTube, plus accuracy QA. Works with any OpenAI-compatible endpoint, or with no endpoint at all — the calling model does the translation itself. Not for dubbing/voice-over, video editing, or titles/thumbnails.
- Reads credentials
In this repository3 other files it gives its agents.
- brain-searchSkill
- third-party-writingSkill
- video-editSkill
The file
We split this skill into the rules it gives an agent
2 rules. About 0 are common, 0 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 47
Read it. Translate each numbered value from _meta.source_language into _meta.target_language.
- Very specific: line 49
Write <n>.out.json next to it: the same numbered keys (no _meta), each value a non-empty translated string.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
YouTube / media → translated subtitles
Everything is in scripts/. Requirements: python3 (stdlib only) and yt-dlp on PATH for YouTube
inputs. Translation is done either by an OpenAI-compatible endpoint or by you, the calling model.
Local media without subtitles is transcribed only if an ASR tool is installed (faster-whisper,
mlx_whisper, or the whisper CLI); otherwise that item is marked needs-asr and the run continues.
Inputs
Pass any mix of:
- YouTube video, channel (
https://youtube.com/@Handle,/videos,/streams), or playlist URLs.--latest N= newest N per channel/playlist (0 = all). - Local folders or files:
.srt,.vtt, YouTube.json3, or media (.mp4/.mkv/.mov/.webm/.mp3/.m4a/.wav). A sidecar subtitle with the same stem is used when present; otherwise media is transcribed (if an ASR tool exists).
--langs sets target codes (default en,uk,de,fr,es,pl); the source language is skipped automatically.
Output (per item, stable across re-runs)
<out>/<source>/<YYYYMMDD>_<slug>_<id>/
video.json metadata, cues, status
original-script.md full original transcript in paragraphs
original.<src>.srt timed original captions
translations/<lang>.srt one SRT per target language, same cues/timings
translations/<lang>.md readable transcript in that language (same paragraph breaks as original-script.md)Mode A — you have an OpenAI-compatible endpoint
export YT_TX_BASE_URL=http://<host>:<port>/v1 YT_TX_API_KEY=<key> YT_TX_MODEL=<served-model>
python3 scripts/yt_translate.py run <inputs...> --langs en,uk,de --out ./out --concurrency 8Re-running is safe: finished <lang>.srt files are skipped and every chunk is cached under <video>/.cache/.
Mode B — no endpoint: you translate (agent mode)
- prepare — ingest and write numbered work items (no network model needed for translation):
This writes, per video and language, chunks atpython3 scripts/yt_translate.py prepare <inputs...> --langs en,uk,de --out ./out<video>/.work/<lang>/<n>.in.json:{"_meta": {"source_language": "...", "target_language": "...", ...}, "1": "first source line", "2": "second source line", ...} - translate each work item yourself. For every
<n>.in.json:- Read it. Translate each numbered value from
_meta.source_languageinto_meta.target_language. - Lines are consecutive speech fragments; a sentence may span lines — translate so they read naturally in order.
- Write
<n>.out.jsonnext to it: the same numbered keys (no_meta), each value a non-empty translated string. - Fan this out with subagents or parallel calls if your harness supports it — the items are independent.
- Read it. Translate each numbered value from
- check what's left (optional):
python3 scripts/yt_translate.py status --out ./outlists pending items. - assemble — validate every
.out.jsonand write the SRTs:
Any item with missing/extra keys or empty values is reported aspython3 scripts/yt_translate.py assemble --out ./outinvalid; incomplete languages are reported and skipped. Fix those.out.jsonfiles and runassembleagain.
Accuracy QA
# structural only (always available, no model):
python3 scripts/qa.py run ./out --sample 0
# with an endpoint GEMBA-MQM judge (use a DIFFERENT model than the translator if you can):
export YT_QA_BASE_URL=... YT_QA_MODEL=... YT_QA_API_KEY=...
python3 scripts/qa.py run ./out --sample 40 --review en,uk
# agent-mode judge (no endpoint): prepare -> fill qa/.judge/*/1.out.json -> assemble
python3 scripts/qa.py prepare ./out --sample 40
python3 scripts/qa.py assemble ./outThe judge follows GEMBA-MQM (Kocmi & Federmann, 2023): per line it lists errors by category
(accuracy/mistranslation, omission, addition, terminology, fluency/grammar) × severity (critical 25 /
major 5 / minor 1). Line score = 100 − penalties, clipped at 0. Outputs: qa/report.md, qa/flags.jsonl,
qa/judge.jsonl, qa/review-*.md.
Upload to YouTube
YouTube Studio → Subtitles → the video → Add language → Upload file → "With timing" → translations/<lang>.srt.
Known failures
- Members-only/private videos fail in yt-dlp ("Join this channel…") and are logged; the rest continue.
- Videos with captions disabled (or music only) end up
no-captions. - Dubbed videos expose several
*-origASR tracks; only the declared-language one is the true original. - Some videos need cookies: set
YT_DLP_COOKIES_FROM_BROWSER(e.g.chrome,brave:Profile 1) orYT_DLP_COOKIES(a cookies.txt path).
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

