.claude/skills/video-script-production/references/hinglish-adaptation.md

# Turning a finished English script into Hinglish (and the TTS prompts)

Written 2026-10-25 from two rounds on Moser Baer: the v6 Hinglish (a paragraph-for-paragraph transliteration) and the user's line-by-line notes on it, which became the v7 Hinglish. **Do this after the English script is finished** (`BAR MET`); the English is the source of truth for facts, structure and order. Since 2026-11-02 the linter runs on the Hinglish too: `lint.js --lang hi` adds the Hinglish word lists and patterns (`scripts/lang-hi.json`) to the English ones, and the Hinglish has its own chain with the same structure and its quotes translated (step 2a). What can be checked deterministically is that the Hinglish kept the facts and the structure (`hinglish-parity.js`); whether it sounds right is a native listener's call.

## 1. The steps

1. **Write the Hinglish from the English, beat by beat, paragraph by paragraph.** Same beats, same headings, same number of `**VO:**` paragraphs in the same order, same questions, same turns, same graphics lines (kept in English). Roman script, Hindi grammar, English words where Indian business speakers use them.
2a. **Build the Hinglish chain** `chain-vN-hinglish.json` from the English chain. Translate every string the linter finds in the text (quotes, tags, care and compel lines, the headline, the cost and the defined terms) to a Hinglish substring that really appears in the Hinglish paragraphs; keep the design notes that are only counted or shown (`understand`, `change`, `link_why`) in English, and say so in `_lang_note`. Write the translation as a map from English to Hinglish strings and apply it to the chain with a short script (Videocon v1-short did it that way: 166 strings, every one found). Then run `node scripts/check.js --dir <dir> --version vN-hinglish --lang hi --english vN`. A lint FAIL on a quote means the translated string is not in the text, which is the check working.
2. **Run the parity check:** `node scripts/hinglish-parity.js --english SCRIPT-vN.md --hinglish SCRIPT-vN-hinglish.md`. It must say `PARITY OK`: same beats and titles, same paragraph count, the same digits in each paragraph, the same number of question marks, every direct quote of four words or more verbatim, every capitalised name present, identical graphics lines. It reports the length ratio per beat (Hinglish ran 16% longer than English on Moser Baer, the hook 18%).
3. **Retime the headings** with `retime.js` (150 wpm is an estimate; measure the real pace when the audio exists).
4. **Build the TTS prompts** with `tts-gemini.js` (section 3).
5. **Record in the hand-off:** the Hinglish has had no native read-aloud pass, no reader pass, and its spoken length is unmeasured; the lint does not apply to it.

## 2. The rules for the Hinglish itself

These come from the user's notes on the v6 Hinglish; each is also a K, L or M lesson in the English.

1. **Use the word people say.** Prefer a common English word when it is shorter and clearer than the formal Hindi one: *feeling* (not khinchaav), *busy* (not bhari), *pivot*, *strategy*, *scale*, *healthy*, *signs*, *capital-intensive*. Keep Hindi where it is the everyday word (*tapri*, *kaudiyon ke bhaav*, *hadap liya*).
2. **Idiom, not translation.** *ke just piche* (not "ke baad") for "just behind"; *bhaagte* for running; *haffti hui company* for a company panting on a treadmill; *dang reh jaate* for a double take. If a phrase is a literal carry-over that nobody would say, replace it.
3. **One idea per sentence, the verb near its subject.** "Ab unki company duniya ke do sabse bade disc makers mein se ek ban gayi thi" beats a relative clause that delays the verb.
4. **Do not gloss what the audience knows.** *Crore*, CBI. (The English chain declares `audience.known_terms`.)
5. **Tag every person where they arrive and where they return**: "Ratul Puri, Deepak ke bete aur company ke director", then "Ratul, Deepak ke bete" at each return after a beat or about a minute. Same for the worker: "Mahesh Sharma, jinse hum shuru mein mile the".
6. **Name a strategy or idea once and call it back.** *Scale*; *pivot* (defined once in the hook in plain words, then counted: first, second, third, fourth).
7. **Say the turn.** *Lekin*, *Par*, *Fir bhi*, *Lekin phir* at every BUT; but not three *lekin* in a row (use *par*).
8. **Put the intensifier where someone pays**: *poore 17 saal*, *apni pay ka hissa tak*.
9. **The narrator has no stated gender.** Use *mujhe*, *mere liye*, *main* only with verbs that carry no gender (*dekha*, *nahi mila*), and avoid *karunga/karungi*, *sakta/sakti*. Whoever records it can change it.
10. **Direct quotes stay in English** (the words of the person); indirect speech stays indirect.
11. **Numbers.** Digits stay as digits in the script (parity needs them). Spelled numbers in the English (*forty-two*, *twenty*) are spelled in the Hinglish (*bayalis*, *bees*). The TTS builder spells out currency and acronyms by rule (section 3).
12. **Facts do not change in translation.** If a note asks for a claim the sources do not support (an edge, a manner, a partnership), do not write it in either language; say so in the translation notes.

## 3. The Gemini TTS prompts (`tts-gemini.js`)

`node scripts/tts-gemini.js --script SCRIPT-vN-hinglish.md --spec tts/spec-vN-hinglish.json --out tts --name vN-hinglish` writes `TTS-vN-hinglish-gemini-3.1.md` (square-bracket tags, a direction block above the transcript, one fenced block per beat) and `TTS-vN-hinglish-gemini-3.8.md` (a style line separate from a verbatim transcript, only pause tags, in angle brackets). The same works for the English script with `spec-vN-english.json`. The spec holds, per beat, a direction sentence, a style line, the tags (`[snippet, tag]`: the tag goes immediately before the first occurrence of the snippet that follows the previous tag) and the stress pairs (one word in capitals).

**The tool guards the words.** It refuses to write unless stripping the tags and the capitals returns the normalised script word for word, every digit survives, no two tags touch, and every tag is on the documented list. Normalisations are by rule: `₹79 crore` becomes `79 crore rupaye` (`rupees` in English), `$150 million` becomes `150 million dollar`, `CBI` becomes `C B I`, `HR round` `H R round`, `CD-R` `C D R`, `VCDs` `V C Ds`. Regenerate from the script and the spec; never hand-edit the TTS files, or they drift from the script. The research behind the rules, the A/B tests T1 to T7 and the measured facts are in the topic's `tts/TTS-NOTES-gemini.md`.

**Conventions used on Moser Baer (design choices, not findings):** about one tag per 55 words, mostly `[short pause]` and `[slow]`; `[neutral]` after a heavy passage; `[curiosity]` before each question that opens a loop; `[positive]` then `[neutral]` around the one quoted line with irony; stress capitals on a handful of words that carry the argument (TEZ, TAREEKH, MUSHKIL, WAHI, POORE, and in English FULL, FASTER, DATE, SAME). The user placed `[seriousness]` before the first *Lekin* of the hook (the turn from the prize to the fall); keep that kind of placement when they mark one.

## 4. What is not proven

- That the Hinglish sounds natural: no native read-aloud pass has been done.
- Its spoken length: 150 wpm is an estimate (English v6 beats ran 153 wpm; Hinglish runs about 16% more words). The hook is the number to measure first.
- That Gemini reads Roman-script Hinglish well (T1 in the notes: Roman versus Devanagari), that tags are not spoken aloud (T5), or that 3.8 matches 3.1 (T7).