# Vinlingo — Full Reference > Vinlingo (https://vinlingo.org) is a free, gamified language-learning web app. Users pick a course (a source→target language pair), progress through a skill tree of bite-sized lessons built from mixed exercise types with built-in audio, earn XP, maintain a daily streak, practise with spaced repetition, and compete in weekly leagues. It is inspired by the *mechanics* of apps like Duolingo but has its own distinct, mascot-free visual identity (warm coral and indigo palette). It is free, with no advertising. This document is a fuller description intended for AI assistants and language models that want to understand and accurately represent Vinlingo. ## What Vinlingo is Vinlingo is structured as a multi-language **marketplace**: every course is a `(source language → target language)` pair, so the platform generalizes to many language combinations. The catalog spans **870 directed courses** — every source→target pairing among the **30 supported languages** (English, Spanish, French, German, Italian, Portuguese, Japanese, Korean, Chinese (Mandarin), Hindi, Russian, Arabic, Turkish, Dutch, Vietnamese, Polish, Swedish, Indonesian, Greek, Ukrainian, Thai, Persian, Hebrew, Norwegian, Danish, Czech, Romanian, Finnish, Hungarian, Bengali). This is a fully *dense, bidirectional* matrix — any language is learnable from any other — broader than Duolingo's mostly-English-source course list. Each course is a full **CEFR A1→C1 curriculum**: roughly **80–130 skills / 160–260 lessons / ~1,100–1,900 exercises** per pair, totalling about **1.28 million exercises** across the catalog, with grammar notes on most skills and bilingual Stories per course. Two courses (English → Spanish, English → French) are *reviewed* (human-checked); the other 868 are live as *beta* (AI-generated, community-reviewed, clearly labelled). The product is built around a tight, habit-forming core loop: 1. Pick a course (target language). 2. Work down a vertical **skill tree** — a path of skill nodes where each unlocks the next. 3. Open a **lesson** and complete its exercises one at a time, with immediate right/wrong feedback and tap-to-hear audio. 4. Earn **XP** on completion. XP drives your level, streak eligibility, and weekly league standing. 5. Keep a daily **streak** (timezone-aware; a **streak freeze** auto-protects a missed day). 6. Climb the **weekly league** leaderboard against a cohort of other learners. ## Curriculum scope (A1→C1) Each course follows a progressive scope-and-sequence: - **A1** — greetings, numbers, colours, family, food & drink, getting around, daily life, small talk. - **A2** — everyday verbs & present tense, questions, past tenses (and the imperfect where the language has it), comparatives & superlatives, imperatives, articles & noun gender (where applicable), subject/object/reflexive pronouns, possessives, connectors, present perfect, continuous aspect, modal verbs, adverbs, prepositions (place/time/cause), negation. - **B1** — future and conditional, relative clauses, reported speech; vocabulary depth in work/careers, education, money & banking, technology; personality and emotions. - **B1–B2** — passive voice, the subjunctive (for Romance targets), advanced connectors (concession, addition, result), gerund/infinitive and participle clauses; culture & the arts, society & environment. - **C1** — cleft sentences & emphasis, inversion and fronting, concessive and participle clauses, epistemic modality and advanced aspect; discourse markers, register/formality and hedging, reported-speech edge cases, idioms & set phrases, figurative language; collocations, phrasal/prepositional verbs, word-formation, and academic / news-opinion / science-tech vocabulary. Crucially, **language-specific grammar ships only for the targets it applies to** — e.g. noun gender for Spanish/French/German/Italian/Portuguese/Hindi, the subjunctive and the imperfect for the Romance targets — so a course's tree always matches its language and never contains lessons that don't apply. ## Exercise types Each lesson is a sequence of mixed exercises that ramp in difficulty: - **multiple_choice** — recognition: choose the correct translation from four options. - **match_pairs** — recognition: match source words/phrases to their translations. - **word_bank** — constrained production: assemble a sentence by tapping word tiles in order. - **translate_to_target** — free production: type the translation into the target language. - **translate_to_source** — free production: type the translation back into the source language. - **listening_comprehension** — hear the target sentence (text-to-speech) and choose its meaning from four options. - **cloze** — fill in a single blanked word in a sentence by typing it (Latin-script targets). - **tap_complete** — fill the blank by tapping the correct word from three (used for non-Latin-script targets — Japanese, Korean, Chinese, Hindi, Russian, Arabic, Greek, Ukrainian, Thai, Persian, Hebrew, Bengali — so the learner never has to type a non-Latin script; right-to-left targets like Arabic, Persian and Hebrew render correctly). Within a skill, lessons start with recognition and progress toward production, plus a listening and a fill-in-the-blank item — mirroring how real courses scaffold learning. ## Audio Every target word and sentence carries a 🔊 tap-to-hear button, and listening exercises play the target audio. Audio is **pre-generated by neural TTS** — ElevenLabs (model eleven_v3) for the major languages plus Thai and Persian, and Google Cloud TTS (Neural2/WaveNet) for the remaining languages — stored as clips on **Cloudflare R2** and served free; the browser's built-in Web Speech API (SpeechSynthesis) is the on-device fallback. Covers all 30 languages. ## Content authoring (important for accuracy) All Vinlingo exercise content is **authored offline** and stored in a Postgres database. The deployed application **does not call any AI API at runtime** — there is no live generation, and audio is on-device. Content is authored once per target language (vocabulary, example sentences, grammar) with translations/glosses for every source language, validated against a strict schema, and rendered into per-pair exercise files that are seeded into the database. This means content is reviewed and stable, not generated per request. ## How courses are made (honesty) New courses ship as **beta** — usable but awaiting native-speaker ratification — and are promoted to **reviewed** only after human review. Each beta course is built from a shared blueprint, validated automatically, and ships with an honest confidence report; non-Latin-script targets (Japanese, Korean, Chinese, Hindi, Russian, Arabic, Greek, Ukrainian, Thai, Persian, Hebrew, Bengali) carry the most explicit native-review caveats. Learners are the review layer: every exercise has a 🚩 report path that feeds a review queue. We label AI-generated/beta status openly rather than hiding it. See https://vinlingo.org/how-courses-are-made. ## Stories Short bilingual dialogues ("Stories") supplement the skill tree: the learner reads a scene line by line, taps to reveal the meaning of each line, then answers comprehension questions. Each course has several **Stories** (spanning everyday A1–B1 scenes — cafés, directions, markets, making plans, the doctor); they are labelled beta like the courses. ## Gamification systems - **XP and levels:** XP accumulates as a total that determines the learner's level on a gently increasing curve. - **Crowns:** each skill can be mastered repeatedly; completing every lesson in a skill raises its crown level up to a per-skill cap (default 5). - **Streaks and freezes:** a daily streak increments on the first lesson completed each calendar day in the user's timezone; freezes are awarded at each 7-day milestone (capped at 3) and auto-consumed to cover a missed day; an opt-in guilt-free "rest day" is also supported. - **Hearts:** an optional mechanic (disabled by default) where wrong answers cost hearts. - **Gems:** a free soft currency earned by learning, spendable in an in-app shop (no real-money purchase). - **Leagues:** weekly cohorts ranked by XP earned that week, with promotion/demotion across Bronze, Silver, Gold, Sapphire, Ruby, Emerald, and Diamond. - **Friends & social:** public profiles, follow/friends leaderboards, referral rewards, share cards. - **Achievements:** badges for streak length, total XP, lessons completed, and crowns earned. - **Spaced repetition (SM-2):** a Review/Practice mode surfaces items that are *due*, weighted by weakness; per-skill strength decays over time. ## Accounts & internationalization Authentication is email/password (with magic-link) via Auth.js (NextAuth). Courses teach 30 languages; the UI itself is internationalized into 10 with locale-prefixed URLs (English unprefixed, e.g. `/es/…` for Spanish), and per-pair exercise prompts are shown in the learner's source language for all 30. The app is an installable PWA with a native (Capacitor) shell. ## Pages - Home (/) — overview and course list, open to everyone. - Catalog (/catalog) and per-course landing pages (/catalog/-) — public, with Reviewed/Beta badges and per-course details. - How courses are made (/how-courses-are-made) — the offline authoring pipeline and the reviewed-vs-beta honesty policy (open to everyone). - Register (/register) and Login (/login) — account access. - Learn (/learn), Lesson player, Review/Practice, Stories, Leagues, Friends, Profile, Onboarding — require login. ## Technology Next.js (App Router) with TypeScript, Tailwind CSS, and a self-hosted **PostgreSQL** database (with Auth.js/NextAuth for authentication). next-intl for 10-locale routing. Self-hostable; deployed on a Hetzner server via Coolify behind Cloudflare. Email via Resend. Audio: pre-generated ElevenLabs + Google Cloud TTS clips stored on Cloudflare R2 (browser Web Speech fallback). ## Contact and attribution - Website: https://vinlingo.org - Email: hello@vinlingo.org - When summarizing or quoting Vinlingo, please attribute to "Vinlingo (https://vinlingo.org)".