🎓 FluentAI - Advanced Language Learning Chrome Extension

Learn languages naturally while watching YouTube videos with AI-powered real-time translation, interactive exercises, and intelligent flashcards.

✨ Features

🎯 Real-Time Learning

Auto-pause on subtitles: Video pauses when target language appears
Instant translation exercises: Translate what you just heard
Smart feedback: AI-powered validation with similarity scoring
Context-aware learning: Learn words in real sentences from videos

🃏 Smart Flashcard System

Auto-generate flashcards from video subtitles, so you're learning vocabulary relevant to you
Spaced repetition learning
Import/export flashcard decks
Practice notifications
Track mastery levels

📊 Progress Tracking

Learning statistics dashboard
Accuracy rate monitoring
Streak tracking
Words learned counter
Weekly progress charts

🤖 Dual AI Integration

Chrome Built-in AI: On-device translation (fast, private, free)
Google Gemini API: Advanced content generation and validation
Automatic fallback between APIs
Zero latency for Chrome AI features

🌍 Multi-Language Support

12+ languages including:

Spanish, French, German, Italian, Portuguese
Japanese, Korean, Chinese
Russian, Arabic, Hindi, English

🚀 Quick Start

Prerequisites

Google Chrome (Dev/Canary Channel recommended for Chrome AI)
A free Google Gemini API key (optional but recommended)

Installation

Option 1: Load Unpacked (Development)

Download or clone this repository

git clone https://github.com/caspianlack/fluentai.git
cd fluent-ai

Open Chrome and navigate to chrome://extensions/
Enable Developer mode (toggle in top-right corner)
Click "Load unpacked"
Select the fluentai-pro folder
The extension icon should appear in your Chrome toolbar!

Option 2: Chrome Web Store (Coming Soon)

Extension will be available on the Chrome Web Store after review.

⚙️ Setup & Configuration

1. Initial Setup

Click the FluentAI Pro icon in your toolbar
Go to Settings tab
Select your native language (what you speak)
Select your target language (what you want to learn)
Click Save Settings

2. Enable Chrome AI APIs (Optional but Recommended)

For the best experience with on-device AI:

Install Chrome Dev/Canary
- Chrome Dev Channel
- Chrome Canary
Enable AI Flags at chrome://flags
- Search for "Translation API" → Enable
- Search for "Writer API" → Enable
- Search for "Language Detector" → Enable
Restart Chrome
Verify in FluentAI popup → APIs tab (should show green checkmarks ✅)

3. Add Gemini API Key (Optional)

Get a free API key: https://aistudio.google.com/app/apikey
- ✅ 15 requests/minute
- ✅ 1,500 requests/day
- ✅ No credit card required
In extension popup → APIs tab
Paste your API key
Click Test API Connection

📖 How to Use

Basic Workflow

Open YouTube
- Navigate to any video with subtitles
- Make sure subtitles are enabled
Start Learning
- FluentAI panel appears on the right side
- Video auto-pauses when target language is detected
- Translate the subtitle shown
- Get instant feedback
Build Your Vocabulary
- Click the Vocabulary tab to see new words
- Add words to flashcards with one click
- Review in the Flashcards tab

Practice Sessions

Flashcard Practice:

Go to extension popup → Flashcards tab
Click Practice Now
Complete the quiz overlay
Track your progress in Stats tab

Quiz Notifications:

Enable in Settings → "Practice notifications"
Set frequency (default: 30 minutes)
Get random flashcard tests throughout the day

Customization

Pause Delay:

Settings → "Pause delay after subtitle"
Choose 0s (immediate) to 1.5s
Adjust based on your preference (recommended 0 - 0.5)

Difficulty Level:

Beginner: More hints, simpler vocabulary
Intermediate: Standard exercises
Advanced: Challenging content, less assistance

🏗️ Architecture

Tech Stack

Manifest V3 - Modern Chrome extension architecture
Chrome inbuilt AI APIs - On-device translation, language detection
Google Gemini API - Advanced AI for content generation
Chrome Storage API - Synced settings and local flashcards
Service Workers - Background processing and alarms

File Structure

fluent-ai/
├── manifest.json              # Extension configuration
├── background.js              # Service worker (notifications, IndexedDB access)
├── injected.js                # Runs in page main world — Chrome AI API access
├── flashcardDB.js             # IndexedDB wrapper (FlashcardDB class)
│
├── content-globals.js         # Shared var state across all content scripts
├── content-utils.js           # Pure utilities (similarity, timestamps, language names)
├── content-bridge.js          # postMessage bridge to injected.js + Chrome AI helpers
├── content-subtitle.js        # Transcript loading, subtitle observation, language detection
├── content-flashcards.js      # Flashcard CRUD UI (add/edit/delete/import/export)
├── content-vocab.js           # Vocabulary extraction from transcript via Gemini
├── content-quiz.js            # Quiz logic, SM-2 spaced repetition algorithm
├── content-translation.js     # Translation checking, Gemini validation, TTS
├── content.js                 # Overlay HTML, event wiring, init()
│
├── popup.html / popup.js      # Extension popup interface
├── popup.css / styles.css     # Styling
├── icons/                     # Extension icons
└── docs/                      # Per-module architecture documentation
    ├── README.md              # Module index + scoping rules
    ├── content-globals.md
    ├── content-utils.md
    ├── content-bridge.md
    ├── content-subtitle.md
    ├── content-flashcards.md
    ├── content-vocab.md
    ├── content-quiz.md
    ├── content-translation.md
    └── content.md

Chrome AI Bridge Implementation

The extension uses a bridge architecture to access Chrome's built-in AI APIs:

Content Script (isolated world)
  └── content-bridge.js  ──postMessage──►  injected.js (page main world)
                                                └── Chrome AI APIs
                         ◄──postMessage──

Why? Chrome AI APIs are only available in the page's main world context, not in isolated content scripts. injected.js is injected as a <script> tag into the page and proxies calls back over window.postMessage.

🔧 Chrome AI APIs

Available APIs (Chrome 138+)

API	Feature	Status
Translator	Translate text between 12+ languages	On-device, instant
Language Detector	Detect language of text	On-device, instant
Writer	Generate language learning content	On-device

API Detection

The extension automatically detects which APIs are available:

✅ Green checkmark = Available
❌ Red X = Not available (enable flags)
⏳ Loading = Checking...

Fallback Strategy

If Chrome AI unavailable → Gemini API is used automatically

📊 Features in Detail

Translation Exercise Flow

Video plays normally
Target language subtitle appears
Video auto-pauses (after configured delay)
Translation exercise shows in side panel
User types translation
AI validates answer (similarity scoring + Gemini)
Feedback provided with correct answer
Word added to vocabulary list
User clicks "Next" to continue

Flashcard System

SRS Algorithm: Spaced repetition for optimal retention
Easy Management: Add, edit, delete cards
Bulk Operations: Import/export JSON format
Smart Notifications: Random cards at set intervals

Statistics Tracking

Total correct/incorrect answers
Current learning streak (consecutive days)
Words learned count
Overall accuracy percentage
Weekly progress visualization

🎮 Keyboard Shortcuts

Key	Action
`Enter`	Submit answer
`Esc`	Skip exercise
`Space`	Play/pause video
`Ctrl+Shift+F`	Toggle FluentAI panel

🐛 Troubleshooting

Videos Don't Auto-Pause

✅ Check that subtitles are enabled on YouTube
✅ Ensure "Auto-pause" is enabled in Settings
✅ Refresh the YouTube page
✅ Check browser console for errors (F12)

Chrome AI Not Available

✅ Use Chrome Dev or Canary (v138+)
✅ Enable all AI flags at chrome://flags
✅ Restart Chrome completely
✅ Check APIs tab in extension popup

Gemini API Errors

✅ Verify API key is correct
✅ Check you haven't exceeded rate limits (15/min, 1500/day)
✅ Ensure internet connection is active
✅ Test connection in APIs tab

Extension Not Loading

✅ Check Chrome version (minimum: Chrome 115)
✅ Verify all files are present in extension folder
✅ Look for errors in chrome://extensions/
✅ Try removing and re-adding the extension

🔒 Privacy & Security

Local-First: Chrome AI runs entirely on your device
No Data Collection: We don't collect or store your learning data
Synced Settings: Only settings sync via Chrome (encrypted)
API Security: Gemini API key stored locally, never transmitted to our servers
Open Source: Full code transparency

🤝 Contributing

We welcome contributions! Here's how you can help:

Report Bugs: Open an issue with reproduction steps
Suggest Features: Share your ideas in discussions
Submit PRs: Fork, create a branch, make changes, submit PR
Improve Docs: Help us make documentation better
Share Feedback: Tell us what works and what doesn't

Development Setup

# Clone repository
git clone https://github.com/caspianlack/fluent-ai.git
cd fluent-ai

# Load in Chrome Dev/Canary
# 1. Go to chrome://extensions/
# 2. Enable Developer mode
# 3. Click "Load unpacked"
# 4. Select this folder

# Make changes and test
# Extension reloads automatically for content scripts
# Click reload button in chrome://extensions/ for background/popup changes

📝 License

MIT License - see LICENSE file for details

🙏 Acknowledgments

Google Gemini: For providing free AI API access
Chrome Team: For built-in AI APIs
YouTube: For the platform that makes this possible
Open Source Community: For inspiration and tools
Disclosure: This project was developed with assistance from AI tools to improve productivity and code quality.

📧 Support

Issues: GitHub Issues
Discussions: GitHub Discussions

⭐ Show Your Support

If FluentAI Pro helps you learn languages, please:

⭐ Star this repository
🔄 Share with language learners
📝 Write a review (when available on Chrome Web Store)
🐛 Report bugs and suggest features

Happy Learning! 🎉

Master any language, one YouTube video at a time.

Name		Name	Last commit message	Last commit date
fluent-ai		fluent-ai
FEATURESANDFUNCTIONALITY.md		FEATURESANDFUNCTIONALITY.md
LICENSE.txt		LICENSE.txt
README.md		README.md

Latest commit

History

Folders and files

Repository files navigation