Micheon

A fully offline desktop app for learning German with premium neural voices, spaced repetition, and lessons that actually understand what you type.

Made with love ❤️ by Leon and Michelle.

Micheon is a native-feeling desktop language tutor that runs entirely on your machine. There's no subscription, no login server, no cloud calls for content, and no usage limits. You download it once, and everything — thousands of sentences, dialogues, grammar drills, and natural-sounding speech — works on a plane, on the train, or with the Wi-Fi off.

Repo folder: germ · Product name: Micheon · Platforms: Windows and Linux desktop (Electron)

---

Micheon in action

The app keeps the next useful lesson obvious while still giving you full access to the curriculum, focused practice, progress tracking, and games.

Lesson preview
Preview both languages, listen to every phrase, then practise through reading, meaning, typing, translation, word order, and recall.

Guided session
A focused practice space with a clear stage path, natural phrasing notes, audio replay, personal mastery controls, and a background you can choose in Profile & Settings.

Your app, your colours
Use light, dark, or system mode, then pick one of Micheon's accent presets or choose any custom colour. Buttons, progress, selections, and guided lessons update together while keeping their text readable.

Searchable curriculum Browse practical conversation packs, filter by level and progress, and jump directly into the material you need.

Games and mastery Build recall through short arcade-style games while vocabulary mastery and milestones update alongside your lessons.

---

What it is

Micheon teaches German the way you'll actually use it: whole sentences and real conversations, not flashcard word-lists. It bundles a hand-built, natively-verified curriculum and pairs it with a smart answer-checker that accepts the many ways a person really phrases something — so you're graded on whether you understood the German, not on hitting one exact string.

It ships as a Windows installer with automatic updates. Under the hood it's a React front-end wrapped in Electron, with a tiny local Express server that generates Microsoft neural TTS audio on demand.

Who it's for

• Self-learners who want to reach confident, conversational — up to roughly university-level — German without paying a monthly fee or handing their data to a cloud service.
• Offline learners — commuters, travellers, anyone with unreliable internet. The whole app works with no connection.
• German speakers learning English. Set your interface language to Deutsch and the direction flips: the app speaks German to you and teaches the same expressions in English.
• Privacy-minded people. Your progress lives in a local store on your machine, not on someone's server.

---

What you can do

Feature	What it does
Guided lessons	Learn a batch of new material, then identify, type, translate, fill gaps, and rebuild it from memory. Correct typed answers auto-advance — no clicking "Check". Each lesson mixes new items with review so nothing fades.
Premium voice	Every sentence can be read aloud in a natural Microsoft neural voice (via edge-tts), generated locally. A waveform reacts while it speaks.
Smart answer matching	Write it your way. The checker forgives typos, contractions, British/American spelling, articles, word-order-preserving paraphrases, and a large library of synonyms — while still rejecting genuinely wrong answers, wrong tense, and reversed meaning.
Spaced review	Items you've seen come back on a memory-strength schedule so they stick for the long term.
Desktop learning pets	Animated companions live on your desktop and actively help you remember. They ask whether you still recall learned words and phrases, bring struggling material back sooner, give useful language-specific grammar tips, and run a recall checkpoint after each lesson before new material is introduced. Pets can be moved, resized, muted, or hidden whenever you want.
Micheon Immersion for Chromium	An optional companion extension for Chrome, Edge, and Brave. It adds bilingual hover definitions to Micheon vocabulary while you browse, collects unfamiliar German words for review, and selects an official German YouTube audio track with English captions when one is available.
Vocabulary games	Eight arcade-style games (Snake, Whack-a-Mole, Falling Letters, Verb Shooter, Minesweeper, and more) that drill vocab without feeling like study.
Grammar drills	Cloze (fill-in-the-blank) exercises and grammar notes for the patterns behind the sentences.
Fluency meter & gamification	Track known-word count toward a fluency estimate, earn XP, keep a daily streak, level up, and unlock milestones.
Micheon appearance	Choose light, dark, or system mode, then use a curated accent preset or any custom colour. Micheon derives readable text, hover, pressed, and soft-selection shades from your choice and saves it on your device.
Learning direction	Switch between learn German, learn English, learn French and learn Polish; the interface, prompts, and lesson make-up follow the language you pick.
Multiple courses	German is the flagship; English, French and Polish are taught from the same catalogue, narrowed to what each language covers, and the course registry also carries a Spanish track and a bonus C# course, selectable from the course switcher.
Local accounts	Per-machine profiles keep each person's progress separate and sync across browser/app restarts — no account server involved.

---

Getting started

Option A — Install the app (recommended)

1. Go to the Releases page.
2. Download the build for your system:
   • Windows — Micheon-Setup-x.y.z.exe
   • Linux — the .AppImage (make it executable and run it) or the .deb
3. Run it. Micheon installs, creates a menu entry, and launches.
4. Create a local profile, pick your course, and start your first daily lesson.

The app checks for updates on its own and installs them the next time you close it.

Option B — Run from source

Prerequisites: Node.js 18+ and npm.

git clone https://github.com/Leon2k909/Micheon.git
cd Micheon        # (the working folder is named "germ")
npm install

# Web dev server + local TTS server together, with hot reload:
npm run dev

# Or run it as the actual desktop app:
npm run electron

npm run dev starts Vite (the UI) and the Express TTS server side by side. Open the printed local URL in your browser, or use npm run electron for the full desktop experience with the title bar and auto-update wiring.

---

Micheon Immersion browser extension

Micheon includes an optional Manifest V3 extension for Chrome, Edge, and Brave. It is a browsing companion rather than a full-page translator: it reinforces vocabulary from Micheon's bundled word bank while leaving the page itself intact.

• Learn from normal browsing. Known Micheon vocabulary receives a dotted underline and a translation tooltip on hover or keyboard focus. German pages show the English meaning; on other pages, recognised English words can show the German you are learning. Hovering can also pronounce the German; a brief settling delay and latest-word-wins playback prevent repeated or overlapping speech as the pointer moves.
• Find useful gaps in the curriculum. On pages detected as German, the extension keeps a local candidate list of plausible words it does not recognise, including one real sentence where each word appeared. You can review, reset, or export that list as JSON. Candidates are never added to lessons automatically.
• Use German audio on YouTube. When a video provides an official German audio track, the extension selects it and enables English captions. Videos without a German track are left unchanged.

Install it from the desktop app

1. Open More → Profile and settings → Browser extension in Micheon.
2. Select Set up the extension folder. Micheon copies the unpacked extension to a stable folder in Documents and opens it in Explorer.
3. Open chrome://extensions, edge://extensions, or brave://extensions in the matching browser.
4. Enable Developer mode, select Load unpacked, and choose the folder Micheon opened.
5. Pin Micheon Immersion if you want its status and candidate-word controls within easy reach.

Chromium deliberately prevents apps from silently installing unpacked extensions, so the Load unpacked step must be confirmed in the browser. When Micheon is running outside the desktop shell, the same settings card offers a ZIP download that can be extracted and loaded instead.

The version shown in Brave comes from the Micheon release that supplied the files. After a Micheon update, select Set up for Brave again, then press Reload on the existing Micheon Immersion card at brave://extensions and refresh pages that were already open. Brave does not automatically activate changed files for an unpacked extension.

How words and data reach the extension

• Micheon's hardcoded lesson packs and bundled word bank are the source of truth. Every app build runs npm run sync:immersion-extension, which exports the deduplicated catalogue to data/words.json and rebuilds the downloadable extension archive before packaging Micheon.
• The release build refuses to ship changed extension files unless both the extension version and Micheon app version advance, ensuring every extension update reaches Git and the desktop autoupdater together.
• Installing or updating Micheon therefore supplies a new offline word snapshot. Set up for Brave copies that exact snapshot to the stable Documents/Micheon Immersion Extension folder; it does not download a separate or newer extension from the internet.
• There is no hidden account or progress sync between Micheon and Chromium at present. Extension settings and discovered-word candidates live in chrome.storage.local; app profiles and mastery records stay in Micheon's local profile store. The extension can use Micheon's 127.0.0.1 TTS service while the desktop app is running, but that is audio playback rather than data sync.
• New words found while browsing can be exported from the extension as JSON for review. They are deliberately not injected into lessons automatically: they only reach both products after being checked, authored, and added to Micheon's hardcoded catalogue.

All vocabulary matching and language detection run on the device against the word list bundled with the extension. It does not call a translation API, require a Micheon account, or upload its candidate-word list; extension preferences and candidates stay in Chromium's local extension storage.

---

How to use it, day to day

1. Pick up where you left off. The dashboard's Continue learning card drops you into the next lesson.
2. Work through a lesson. You'll see the German sentence and its meaning. Depending on the step you'll choose what you heard, type the answer, translate it, fill a gap, or rebuild it from memory. Tap Hear it any time to hear a native voice. Get a typed answer right and it moves on automatically.
3. Check what you remember with your pet. At the end of a lesson, your desktop companion asks you to recall each item before revealing the answer. Anything you mark Not yet is reviewed again before Micheon introduces fresh material.
4. Do your scheduled reviews. Your pet also checks learned words and phrases between lessons. Confident answers move further along the spaced-repetition schedule; forgotten items return sooner.
5. Play a game or two. When you want a break that's still practice, the Games tab drills your current vocabulary.
6. Make it yours. Open More → Profile and settings to adjust your desktop pet, learning direction, and personal preferences.

---

How it works (architecture)

Micheon is deliberately simple and self-contained:

• UI — React 19 + TypeScript + Vite, styled with Tailwind CSS and animated with Framer Motion. Components live in src/.
• Content — bundled as data in src/lib/ (data.ts for authored lessons, plus phrasebank packs). No content is fetched at runtime, and no paid APIs are used. The curriculum is assembled and ordered in src/lib/curriculum.ts.
• Answer matching — src/lib/germanTextMatch.ts runs a tiered comparison: exact → contractions → articles-ignored → synonym/paraphrase canonicalisation → compound-spacing → typo tolerance → meaning-reduced ordered match. It's tuned to accept how real people phrase things while still failing wrong answers.
• Lesson audio — server/index.js is a small Express server that turns text into Microsoft neural-voice audio with edge-tts-universal, served locally (default port 41730). The Speak lesson stage is temporarily paused, and the desktop build contains no downloadable speech-recognition model.
• Desktop shell — electron/main.js wraps the UI, hosts the TTS server, provides the custom title bar, and handles automatic updates via electron-updater.
• Desktop pets — src/components/codexPets/ renders animated companions, proactive recall questions, lesson memory checks, message history, and language-focused tips. Pet answers update the same spaced-repetition records used by lessons and Continue Learning.
• Chromium companion — dist/micheon-immersion-extension/ contains the bundled Manifest V3 extension, its offline word-list snapshot, webpage glossing and candidate collection, and YouTube audio-track handling.
• Accounts & sync — profiles and progress are stored in the browser's localStorage, backed by a machine-local shared store so the same profile follows you across app restarts. Preferences sync the same way.

Project layout

src/
  App.tsx                   Main shell routing
  prototype/                Micheon's production dashboard and navigation
  guided_learning_session.tsx  Guided lesson orchestration
  GuidedSession.tsx         The lesson-taking experience
  Gamification.tsx          Profile, stats, milestones, preferences
  components/               Shared learning, course, account, and pet UI
  games/                    The eight vocabulary games
  lib/
    data.ts                 Authored lesson content
    curriculum.ts           Curriculum ordering
    germanTextMatch.ts      Smart answer checker
    voice.ts / tts.ts       Text-to-speech client
    direction.ts / i18n.ts  Learning direction & interface language
    ...
server/index.js             Local Express TTS server (edge-tts)
electron/main.js            Electron desktop wrapper + auto-update
dist/micheon-immersion-extension/
                             Chrome, Edge, and Brave companion extension

---

Scripts

Command	What it does
npm run dev	Vite UI + local TTS server together (hot reload).
npm run dev:web	UI only.
npm run server	TTS server only.
npm run build	Production build of the UI.
npm run electron	Build, then launch the desktop app.
npm run electron:dist	Build and package a Windows installer with electron-builder.
npm run lint	ESLint.

Building a release

Releases are built by CI. Bump the version, push, and publish a GitHub release for the vX.Y.Z tag — .github/workflows/release.yml then packages Windows and Linux on clean runners and attaches the artifacts (.exe + latest.yml, .AppImage + .deb + latest-linux.yml). Existing installs pick up the update automatically on next launch.

Locally, npm run electron:dist produces a build under release/ for testing. Note that antivirus real-time scanning can lock the extracted Electron binaries mid-package on Windows (EPERM ... rename win-unpacked.tmp) — which is precisely why release packaging lives in CI.

---

Third-party data

The spoken word frequencies that order the vocabulary queue come from a subtitle-derived frequency list. See NOTICE.md.

---

Design principles

• Offline first, free forever. Content is bundled; no subscriptions, no per-request AI costs, no telemetry.
• Sentences, not word-lists. Coverage grows through verified sentence and dialogue packs so you're rarely surprised in real conversation.
• Natively verified content. New material is checked by native-speaker review before it ships.
• Understanding over exact strings. If what you typed means the same thing, it counts.

---

Micheon - learn German properly, on your own machine.