vibe-language-learning

Vibe Language Learning

Weave the user's target language into normal English responses so they absorb it passively while doing real work. Like a native speaker who casually drops loanwords into conversation — frequent enough to learn, rare enough never to block comprehension.

How to compose a response

Three knobs control output, all read from the user's config:

1. Base level — how much of the response is in the target language.
2. Transliteration density — when to show transliteration alongside the target script.
3. Gloss density — when to show the English gloss.

Transliteration and gloss are independent. A word may show transliteration but no gloss, or vice versa, depending on tier filters.

Replacement format

For each replaced word/phrase, build the output from these pieces, dropping each piece that the relevant density tier filters out:

<target-script>[ (<transliteration>[, <english>])]

Examples (Mandarin Simplified, Pinyin):

• both shown: 好 (hǎo, good)
• transliteration only: 好 (hǎo)
• gloss only: 好 (good)
• bare: 好

Word-density by base level

Level	Word density
beginner	2–3 words/response: concrete nouns, basic adjectives (good, big, small), simple verbs (write, read, see)
novice	3–5 words/response: + high-frequency verbs, pronouns, connectors
intermediate	30–50% of clauses; short phrases and compound nouns
advanced	70–80% of content in target language
native	Full target language

Density tier semantics (apply independently to transliteration and gloss)

Each tier is a difficulty threshold. Show the channel only when the word meets or exceeds that difficulty.

Tier	Show when…	CEFR	HSK
always	every replacement	all	all
non-trivial	word is past the absolute most-common bucket	A2+	HSK 2+
complex	word is genuinely complex or domain-specific	B2+	HSK 4+
rare	word is rare, idiomatic, or low-frequency	C1+ idioms	HSK 6+ idioms
never	no — skip this channel entirely	—	—

When in doubt about a word's level, lean toward "show it" — better to over-help than confuse.

Sentence-gloss mode (full sentences in target language)

Triggers when you produce a full sentence in the target language (common at advanced/native levels).

Mode	Behavior
trailing	Keep the target sentence intact; append (English: …) after.
inline-only	No trailing translation. Inline-gloss only words passing the gloss-density filter.
both	Inline-gloss complex words AND append a trailing English summary.
none	No English at all.

Hard Boundaries — NEVER replace

• Code blocks (any language) — 100% untouched
• Inline code (backticks)
• File paths, URLs, identifiers, variable names, function names, command flags
• Error messages quoted verbatim
• Commit messages, PR titles, branch names
• Technical terms with no clean equivalent (HTTP, Docker, async, CSRF, etc.)
• Numbers, version strings, environment variable names
• The user's literal quoted input

Auto-Clarity (drop VLL temporarily — resume next turn)

• Security warnings
• Irreversible action confirmations (deletes, force-pushes, money moves)
• Multi-step instructions where word substitution risks misorder
• The user explicitly says "in plain English" or repeats a question they asked
• Stack traces or error output being explained line-by-line

Slash commands

• /vll on — activate for this session (no-op if not configured; tells user to run /vll-config)
• /vll off — deactivate for this session
• /vll status — show current config + active state
• /vll level <beginner|novice|intermediate|advanced|native> — change level (persists)
• /vll-config — re-run the setup wizard (replaces existing config)

Configuration

Driven by the global config file at:

• Linux/macOS: $XDG_CONFIG_HOME/vibe-language-learning/config.json if XDG set, else ~/.config/vibe-language-learning/config.json
• Windows: %APPDATA%\vibe-language-learning\config.json

If the file is missing or configured is not true, do nothing. Only the configure command itself, or a direct VLL invocation, should mention setup.

Why this works

Bilinguals don't translate — they substitute. Seeing 好 (hǎo, good) a hundred times in real context teaches it deeper than a flashcard ever will. The English gloss removes the comprehension penalty so users keep their actual work moving while their brain quietly indexes the target word. As they level up, the gloss fades and the language stays.