Mandarin Pathways

Overview

A focused Mandarin Chinese learning platform designed to take learners from foundational phrases to advanced professional fluency. The program offers a modular 40-day journey through interactive audio-visual lessons (dual-language audio and transcripts), real-world phrase practice, reading comprehension exercises, character writing practice, and culturally relevant topics—ideal for travelers, professionals, and global citizens.

🚀 Now Available as a Flutter Mobile App!

Mandarin Pathways has been converted to a native Flutter application! The Flutter version provides:

• ✅ Cross-platform support: iOS, Android, Web, Desktop (Windows, macOS, Linux)
• ✅ Native mobile performance with smooth animations
• ✅ Offline-first architecture with all content cached locally
• ✅ Enhanced audio controls (speed adjustment, looping, seeking)
• ✅ Native notifications for daily reminders
• ✅ Modern Material Design 3 UI
• ✅ App Store/Play Store ready for distribution

📱 Get Started with Flutter App →

Two Versions Available

1. Flutter Mobile/Desktop App (recommended) - Native performance, cross-platform

   • Located in: flutter_app/
   • See: Flutter App Documentation

2. Progressive Web App (PWA) - Original web-based version

   • Located in: Root directory
   • Access via local server: python server.py

Technical Skills Demonstrated

Web Development

• Interactive, responsive web interface using HTML5, CSS3, and modern JavaScript
• Dynamic content updates and micro-interactions for enhanced user engagement
• Progressive Web App with offline-ready static assets (first-party lesson audio and transcripts)
• Mobile-first responsive design using media queries and grid layouts
• Canvas-based drawing system for Chinese character practice
• Interactive reading comprehension exercises with vocabulary tools

Python Development

• Automated content generation scripts for lesson materials
• Efficient audio file processing and generation
• Asynchronous programming for optimized performance

Educational Technology

• Structured 40-day curriculum design with progressive learning paths
• Interactive learning tools and progress tracking systems
• Multimedia content integration (text, audio, interactive exercises)
• Character writing practice with stroke order guidance
• Reading comprehension exercises with vocabulary support

Multilingual Support

• Trilingual content management (Simplified Chinese, Pinyin, English)
• Dynamic language switching functionality
• Cultural context integration

User Experience Design

• Progress tracking with completion badges
• Offline-capable web application
• Persistent user preferences and progress storage
• Intuitive navigation and learning flow

Audio Processing

• Dual-language audio content management
• Native speaker pronunciation integration
• Custom audio playback controls

Project Structure

• index.html: Main dashboard with progress tracking
• day.html: Daily lesson interface with audio and text content
• supplementary.html: Additional learning resources and practice materials
• reading.html: Interactive reading practice with comprehension exercises
• writing.html: Character writing practice with canvas-based drawing
• css/: Stylesheets for the web interface
  • styles.css: Main stylesheet
  • reading.css: Styles for reading practice interface
  • writing.css: Styles for writing practice interface
• js/: JavaScript functionality and interactive features
  • script.js: Core application functionality
  • character-drawing.js: Canvas-based drawing system for character practice
• audio_files/:
  • Daily lesson audio files in both English (day{n}_en.mp3) and Mandarin (day{n}_zh.mp3)
  • Supplementary audio content in the supplementary/ subdirectory
  • Reading practice audio in the reading/ subdirectory
  • Writing practice audio in the writing/ subdirectory
• text_files/: Text transcripts for each lesson:
  • Simplified Chinese (day{n}_zh.txt)
  • Pinyin (day{n}_pinyin.txt)
  • English (day{n}_en.txt)
• timing/: Karaoke-style cue files for synced playback with transcripts:
  • Daily lessons: timing/day{n}_zh.json, timing/day{n}_en.json
  • Supplementary categories: timing/supplementary/{category}_zh.json (and _en)
  • Reading passages: timing/reading/{level}_{topic_slug}_zh.json (and _en)
  • Writing activity intros (title + description): timing/writing/{type}_{level_slug}_zh.json (and _en)
  • Chinese vs Latin UI: Mandarin timings are generated against Chinese sentences. Reading with lang=pinyin loads _zh audio + timings alongside the romanized transcript (segmented like English), so cues track the same passages as _zh; per-token granularity is weaker than hanzi spans. Supplementary behaves the same (pinyin text + _zh.json cues). Writing with lang=pinyin plays the _zh intro clip (aligned to description_zh); the romanized heading uses phrase-level highlighting on those two cues (no .lesson-token children) because syllable timing differs from Mandarin speech.
  • Writing lang=zh: Karaoke and _zh TTS match the Chinese title plus description_zh on each block in writing_activities.py. Mandarin stitching lives in scripts/audio_timings.py; generate_writing_file writes description_zh into zh text files only. _en intros use English copy.
  • Manifests regenerate with their MP3s when you run the Python generators.
• reading_files/: Text content for reading practice exercises
• writing_files/: Character practice content and writing exercises
• manifest.json: PWA configuration for installable app features
• sw.js: Service Worker for offline functionality and caching
• icons/: PWA icons for various device sizes and resolutions
  • icon-72x72.png to icon-512x512.png: Progressive sizes for different devices
  • icon.svg: Scalable vector icon
• Python content generation scripts:
  • mandarin_phrases_days_01_07.py: Days 1-7 content
  • mandarin_phrases_days_08_14.py: Days 8-14 content
  • mandarin_phrases_days_15_22.py: Days 15-22 content
  • mandarin_phrases_days_23_30.py: Days 23-30 content
  • mandarin_phrases_days_31_40.py: Days 31-40 content
  • mandarin_phrases_supplementary.py: Additional practice content
  • reading_activities.py: Reading practice content generator
  • writing_activities.py: Writing practice content generator
  • video_search.py: Stub only (embedded YouTube was removed); kept so old references exit gracefully

Course Structure (40 Days)

Foundations (Days 1–7)

• Pinyin system, tones, and pronunciation
• Greetings, numbers, time, and basic Q&A
• Introduction to characters

Essential Daily Phrases (Days 8–14)

• Shopping, transportation, dining, and directions
• Basic sentence patterns and grammar
• Survival Mandarin for travelers

Cultural Context & Daily Life (Days 15–22)

• Family, social interactions, and etiquette
• Chinese festivals and traditions
• Everyday communication at home and in public

Professional Communication (Days 23–30)

• Workplace vocabulary and business etiquette
• Remote work and online meetings
• Emails, presentations, and technical phrases

Advanced Fluency & Real-World Use (Days 31–40)

• Idioms, slang, and formal expressions
• Debates, storytelling, and persuasive speech
• Practice dialogues and role-play

Features

Progressive Web App (PWA)

• Install as a standalone app on desktop and mobile devices
• Offline access to lessons, audio, and practice materials
• Push notifications for daily lesson reminders
• Automatic updates when new content is available
• Fast loading and smooth performance
• Home screen icon for quick access
• Full-screen immersive experience
• Works across all modern browsers and devices

Interactive Learning Interface

• Dual audio tracks (English explanation + native Mandarin pronunciation)
• Interactive transcripts (Simplified, Pinyin, English)
• Daily progress tracker with lesson completion badges
• Mobile-friendly, offline-capable web interface

Mandarin-Specific Tools

• Tone practice and audio drills
• Pinyin-to-Hanzi recognition games
• Cultural tips embedded in lessons

Reading Practice

• Leveled reading materials (Beginner, Intermediate, Advanced)
• Interactive vocabulary lists with pronunciation
• Comprehension questions with self-assessment
• Audio narration by native speakers
• Multi-language support (Simplified Chinese, Pinyin, English)

Character Writing Practice

• Canvas-based drawing system for authentic character practice
• Works with both mouse and touch screen devices
• Grid system for proper character proportions
• Stroke order guidance and hints
• Multiple difficulty levels:
  • Basic strokes and radicals
  • HSK-leveled characters (HSK 1-6)
  • Thematic character groups (Family, Food, Travel, etc.)
• Clear, Undo, and Hint functionality for learning support

Why Mandarin?

1. Global Importance

• Spoken by over 1 billion people
• Key to accessing China's economic, cultural, and technological landscape

2. Career & Business Edge

• High demand in diplomacy, tech, import/export, and finance
• Opens doors in international business, academia, and NGOs

3. Cultural & Intellectual Access

• Dive into Chinese philosophy, literature, and modern media
• Enhanced understanding of cross-cultural dynamics

Development Setup

Requirements

• Python 3.12+

• ffmpeg on your PATH (required by pydub when stitching per-phrase TTS into audio_files/day{n}_*.mp3 and writing timing/day{n}_*.json)

• Required Python packages:

  pip install gtts edge-tts pandas pydub

  Or install from the pinned list:

  pip install -r requirements.txt

  Regenerating Mandarin lesson audio builds one stitched MP3 per day/voice plus cue files under timing/ so the web day lesson can sync highlights with playback.

Generate Lessons

# Generate content for each section
python mandarin_phrases_days_01_07.py
python mandarin_phrases_days_08_14.py
python mandarin_phrases_days_15_22.py
python mandarin_phrases_days_23_30.py
python mandarin_phrases_days_31_40.py

# Generate supplementary content
python mandarin_phrases_supplementary.py

Run the Site

For basic usage and PWA features:

# Using Python's built-in server
python -m http.server 8000

Then open http://localhost:8000 in your browser.

Note: Running through a local server is required to enable PWA features:

1. Use Chrome or another modern browser that supports PWAs
2. Look for the install prompt in the address bar to install as a standalone app
3. Test offline functionality by disabling network in DevTools
4. Enable notifications in your browser to receive daily reminders
5. Clear site data in browser settings to test the service worker update process

Project Standards & Best Practices

This project follows industry best practices for open source repositories:

• MIT License (LICENSE)
• Contribution guidelines (CONTRIBUTING.md)
• Code of Conduct (CODE_OF_CONDUCT.md)
• Changelog (CHANGELOG.md)
• Issue and PR templates (.github/ISSUE_TEMPLATE/, .github/PULL_REQUEST_TEMPLATE.md)
• EditorConfig (.editorconfig)
• .gitignore and Dependabot (.gitignore, .github/dependabot.yml)
• Funding options (.github/FUNDING.yml)

Usage Guide

1. Open index.html and select your lesson
2. Listen to both English explanation and native Mandarin pronunciation
3. Read along with Pinyin and Hanzi
4. Repeat, record, and shadow the audio
5. Practice reading comprehension with leveled texts and vocabulary support
6. Master character writing with the interactive drawing system
7. Complete your daily badge and track your fluency gains

Storage

Uses localStorage to save:

• Completed lessons
• Last visited day
• Audio playback preferences (e.g. slow speed, loop)
• Custom notes and bookmarks
• Completed reading exercises
• Completed writing exercises