🌍 LanguageLab

A modern, interactive language-learning platform for English 🇬🇧 and French 🇫🇷
_{Structured CEFR learning • Smart answer checking • Progress tracking • Verb practice • Exam preparation}

▶ Live: languages-lab.vercel.app

✨ What is LanguageLab?

LanguageLab is a personal language-learning platform designed to turn a static curriculum into an interactive learning journey.

Instead of simply reading grammar rules, learners move through a structured path:

📚 Learn → ✍️ Practice → 🧩 Get checked → 📈 Track progress → 📝 Take the exam → 🔓 Unlock the next level

The project currently contains two language experiences inside one scalable application:

Language	Path	Exam section
🇬🇧 English	A1 → A2	ECRF Exams
🇫🇷 French	A1 → A2	DELF Exams

The architecture is intentionally language-aware, so additional languages can be introduced without rebuilding the entire application.

🎯 Core Features

🗺️ Learning Path

A structured progression through CEFR levels with:

A1 foundation
A2 everyday communication
Sequential section unlocking
Completion tracking
Revisit mode
Final-level assessments
Reserved space for future B1 → C1 expansion

✍️ Sentence Practice

Every curriculum section contains practical sentence-production exercises.

The learner:

Reads the prompt.
Writes an answer.
Gets checked locally first.
Uses AI only when the deterministic check cannot resolve the answer.
Receives feedback.
Advances only after an accepted answer.

🧠 Smart Answer Checking

The answer-checking pipeline is deliberately local-first.

                 Student Answer
                       │
                       ▼
              ┌──────────────────┐
              │ Normalize Answer │
              └────────┬─────────┘
                       │
                       ▼
              ┌──────────────────┐
              │ Exact Comparison │
              └────────┬─────────┘
                       │
                  Match? ────────► ✅ Correct
                       │
                      No
                       ▼
              ┌──────────────────┐
              │ Typo Tolerance   │
              └────────┬─────────┘
                       │
                  Match? ────────► ✅ Correct
                       │
                      No
                       ▼
              ┌──────────────────┐
              │ Gemini AI Check  │
              └────────┬─────────┘
                       │
                       ▼
                🧾 Feedback

This means straightforward answers do not need an AI request.

If Gemini is unavailable, the backend still performs the deterministic comparison before returning a fallback result.

📖 Rules

Grammar content is loaded from language-specific curriculum data and organized around the learning path.

🔤 Verb Bank

A dedicated A1/A2 verb-learning experience with:

Search
Level filtering
Conjugation/practice support
English meanings
French meanings where applicable
Weak-point tracking

📝 Exams

The application includes dedicated exam areas:

🇬🇧 ECRF Exams for English
🇫🇷 DELF Exams for French

The A1/A2 assessment flow connects to the same curriculum and progression system.

📊 Progress

Progress is stored locally in the browser and includes:

Completed sentences
Current question
Maximum reached question
Level completion
Final-test pass status
Verb practice state

No account is required for the current local-progress system.

🌓 Theme System

Two complete visual themes:

🌙 Dark — deep blue/navy learning environment
☀️ Light — soft white, blue-gray and pastel surfaces

The light theme intentionally avoids harsh black text and flat white panels.

How the AI checking works

Every free-text answer goes to a server-side route (/api/check-answer, /api/french/check-answer, /api/german/check-answer, /api/vocabulary/check-answer). The route tries a cheap deterministic check first and calls Gemini only when that check can't decide.

flowchart LR
    A[Student answer] --> N[Normalize: case, accents, punctuation, spaces]
    N --> L{Exact match or small edit distance?}
    L -- yes --> OK[Accepted locally, no LLM call]
    L -- no --> P[Prompt: exercise + reference answer + student answer + CEFR level]
    P --> G[Gemini with a JSON response schema]
    G --> V[Structured verdict: correct, score, feedback, correction, errorType, levelFit]
    V --> F[Feedback shown to the learner]
    G -. error or all models fail .-> FB[Local fallback verdict]
    FB --> F

Prompt. A system instruction fixes the grader's role, the exercise language, the language the feedback must be written in (Arabic for English exercises, English for French and German), what to accept (synonyms, contractions, valid word order, more advanced but correct phrasing) and the learner's CEFR level. The user turn carries the task, the reference answer and the student's answer.
Gemini. src/lib/gemini.js calls the Gemini generateContent endpoint with responseMimeType: application/json and a responseSchema, so the model must return a typed object, not prose.
Structured verdict. The schema requires correct (boolean), score (0 to 100), feedback, correction, errorType and levelFit. The vocabulary route uses a smaller { correct, feedback, correction } schema.
Feedback. The app shows the verdict and only lets the learner advance on an accepted answer.

Guardrails in the code

Local-first. Exact matches and small typos (edit distance of 1 to 3, depending on answer length) are accepted without an LLM call.
Schema-constrained output. A response that isn't valid JSON is rejected as an error rather than shown to the learner.
Model fallback chain. On retryable errors (404, 429, 5xx) the call moves on to the next model in the list.
Graceful degradation. If every model fails, the route returns a deterministic checker-unavailable verdict with the reference answer instead of an error page.
Server-only key. GEMINI_API_KEY is read only inside the API routes; it is never a NEXT_PUBLIC_ variable and never reaches the browser.
Scoped acceptance rules. The vocabulary grader is told explicitly not to accept related words, broader or narrower concepts, or opposites.

🎨 Design Philosophy

LanguageLab is built around a few simple principles:

Soft, focused UI

The interface should help you study, not compete with the lesson.

Progressive disclosure

Don't show everything at once. Unlock complexity as the learner progresses.

Clear hierarchy

Prompt → answer → feedback → progress.

Language-aware branding

English and French share the same application architecture while retaining their own language, branding and curriculum.

No unnecessary visual noise

Soft surfaces, subtle borders, restrained gradients and purposeful color accents.

🧱 Tech Stack

Layer	Technology
Framework	Next.js 15
UI	React 19
Styling	Tailwind CSS 4
Language	JavaScript
AI checking	Google Gemini API
State	React state + localStorage
Data	JSON curriculum datasets
Deployment	Vercel
Runtime	Node.js 20

📁 Project Structure

LanguageLab/
├── public/
│   ├── assets/
│   │   └── images/
│   │       └── logo/
│   └── data/
│       └── languages/
│           ├── en/
│           │   ├── curriculum.json
│           │   ├── grammar.json
│           │   └── verbs.json
│           └── fr/
│               ├── curriculum.json
│               ├── grammar.json
│               └── verbs.json
│
├── src/
│   ├── app/
│   │   ├── api/
│   │   │   ├── check-answer/
│   │   │   ├── french/
│   │   │   └── generate-report/
│   │   ├── globals.css
│   │   ├── layout.jsx
│   │   └── page.jsx
│   │
│   ├── components/
│   │   └── LanguageLabApp.jsx
│   │
│   └── lib/
│       └── gemini.js
│
├── scripts/
│   └── validate-curriculum.mjs
│
├── .nvmrc
├── package.json
├── postcss.config.mjs
└── vercel.json

🧩 Multi-Language Architecture

The application is built around a language configuration registry.

Each language can define:

🏷️ Name and subtitle
🎨 Logo
🚩 Language switch target
📚 Curriculum
🔤 Verb database
📖 Grammar database
🤖 Answer-check endpoint

Conceptually:

const CONFIG = {
  en: {
    name: "English Lab",
    curriculum: "...",
    verbs: "...",
    grammar: "...",
    check: "/api/check-answer"
  },

  fr: {
    name: "Français Lab",
    curriculum: "...",
    verbs: "...",
    grammar: "...",
    check: "/api/french/check-answer"
  }
};

That makes future expansion such as:

🇩🇪 German Lab
🇪🇸 Español Lab
🇮🇹 Italiano Lab

possible without duplicating the entire application.

🤖 AI Architecture

Gemini is intentionally not the first line of defense.

Local layer

The local checker handles:

Case differences
Whitespace differences
Punctuation differences
Accent normalization
Minor spelling differences
Exact stored-answer matches

AI layer

Gemini handles cases where the learner gives a different but potentially valid answer, such as:

Natural synonyms
Meaning-preserving alternatives
Different valid word order
Valid contractions
More advanced but grammatically correct phrasing

This keeps the experience faster and reduces unnecessary AI requests.

🔐 Environment Variables

Create a local .env.local file:

GEMINI_API_KEY=your_api_key_here
GEMINI_MODEL=gemini-3.8-flash
GEMINI_FALLBACK_MODEL=gemini-3.7-flash

The Gemini API key is used server-side and should never be exposed in client-side code.

For Vercel, add the same variables under:

Project → Settings → Environment Variables

🚀 Run Locally

1. Clone

git clone https://github.com/Nardy11/LanguageLab.git
cd LanguageLab

2. Install

npm install

3. Configure Gemini

Create .env.local and add your Gemini credentials.

4. Validate curriculum data

npm run validate:data

5. Start development

npm run dev

Open:

http://localhost:3000

6. Production build

npm run build
npm start

☁️ Deploying to Vercel

LanguageLab is configured for Vercel/Next.js deployment.

The repository contains:

vercel.json
Node 20 configuration
Next.js build scripts
Server-side API routes
Public curriculum assets

Recommended deployment flow:

GitHub
   │
   ▼
Vercel
   │
   ├── Next.js application
   ├── Static curriculum data
   └── Server-side Gemini routes

📈 Learning Progression

Current

A1 ───────────────► A2
 │                   │
 ├─ Sections         ├─ Sections
 ├─ Rules            ├─ Rules
 ├─ Verb Bank        ├─ Verb Bank
 ├─ Practice         ├─ Practice
 └─ Final Exam       └─ Final Exam

Planned expansion

A1 → A2 → B1 → B2 → C1

B1, B2 and C1 are reserved in the learning-path architecture for future curriculum releases.

🗃️ Curriculum Data

The curriculum is kept outside the React component so content and application logic remain separate.

That makes it possible to:

Update sentences without rewriting UI code.
Add sections without rebuilding the learning engine.
Maintain separate English/French content.
Validate datasets independently.
Introduce new languages using the same application architecture.

🛠️ Development Principles

Keep curriculum data separate from UI logic.
Prefer deterministic checks before AI.
Keep API keys server-side.
Preserve local progress when changing navigation.
Keep English/French structures aligned.
Avoid duplicating language-specific application logic.
Keep the UI responsive from desktop to mobile.
Prefer reusable components and theme tokens over one-off styling.

🗺️ Roadmap

🏷️ Tags

language-learning · english-learning · french-learning · cefr · a1 · a2 · delf · ecrf · grammar · verb-bank · education · edtech · nextjs · react · tailwindcss · gemini-ai · generative-ai · vercel · javascript

💡 Why this project?

Most language-learning interfaces separate grammar, vocabulary, exercises and progress into disconnected experiences.

LanguageLab brings them together into one continuous path:

Learn → Practice → Check → Improve → Progress → Test

The goal is not to make another collection of flashcards.

The goal is to build a structured language-learning environment that feels like a real course while remaining lightweight, responsive and extensible.

👨‍💻 Author

Nardy Attalla

Computer Science & Engineering · Full-Stack Development · AI/ML

🌐 Portfolio: https://ai-interactive-portfolio.vercel.app/
💼 LinkedIn: https://www.linkedin.com/in/nardy-attallah/
🐙 GitHub: https://github.com/Nardy11

🇬🇧 LanguageLab · 🇫🇷 Français Lab
_{Learn consistently. Practice actively. Track everything. 🚀}

Name		Name	Last commit message	Last commit date
assets/images/logo		assets/images/logo
data		data
docs		docs
languages		languages
public		public
scripts		scripts
source/research		source/research
src		src
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
.nvmrc		.nvmrc
README.md		README.md
build1		build1
index.html		index.html
jsconfig.json		jsconfig.json
next.config.mjs		next.config.mjs
package.json		package.json
postcss.config.mjs		postcss.config.mjs
vercel.json		vercel.json

Latest commit

History

Folders and files

Repository files navigation