FluencyPal：基于 OpenAI GPT-4 的 AI 语言学习对话练习应用

Your AI-Powered Language Learning Companion

FluencyPal is an AI-powered conversation practice application that helps intermediate and advanced language learners improve their speaking fluency, pronunciation, and confidence through realistic conversations and instant feedback.

🌟 Features

Core Learning Features

🎯 Personalized Learning Plans - AI-generated practice plans based on your goals, proficiency level, and interests
🗣️ Voice Conversations - Real-time AI conversations with natural speech recognition and text-to-speech
📹 Webcam Feedback (Optional) - Practice with an AI avatar for more realistic conversation experiences
✅ Instant Corrections - Get immediate feedback on grammar, pronunciation, and vocabulary
📊 Progress Tracking - Visualize your daily progress and improvements over time
🎮 Interactive Games - Alias word game and other gamified learning experiences
📝 Vocabulary Building - Personalized vocabulary tailored to your conversational needs
🎭 Role-Play Scenarios - Practice real-life situations like job interviews, business meetings, travel, and more

Learning Modes

Casual Conversation - Uninterrupted speaking practice for fluency building
Role-Play - Simulated real-world scenarios (interviews, business, travel, etc.)
Grammar Practice - Focused exercises on specific grammar concepts
Vocabulary Practice - Topic-specific word learning and usage
Personalized plan - Take only the steps necessary to achieve your goal.

Supported Languages

English, Spanish, French, German, Italian, Portuguese, Russian, Chinese, Japanese, Korean, and more

🛠️ Technology Stack

Framework: Next.js 16 (App Router)
Language: TypeScript
UI Framework: Material-UI (MUI)
3D Graphics: Three.js, @react-three/fiber
AI Integration: OpenAI GPT-4
Authentication: Firebase Authentication
Database: Google Cloud Firestore
Payment Processing: Stripe
Internationalization: Lingui
Testing: Jest, Playwright
Error Tracking: Sentry
Deployment: Vercel
Telegram Integration: Telegram Mini Apps SDK

🚀 Getting Started

Prerequisites

Node.js 18+ or compatible runtime
pnpm (recommended) or npm/yarn
Firebase project setup
OpenAI API key
Stripe account (for payments)

Installation

Clone the repository:

git clone <repository-url>
cd dark-eng

Install dependencies:

pnpm install

Set up environment variables: Create a .env.local file in the root directory. See .env.example for reference.

Required environment variables:

# OpenAI
OPENAI_API_KEY=your_openai_key

# Enable database emulator locally
IS_FIREBASE_EMULATOR=true
NEXT_PUBLIC_IS_FIREBASE_EMULATOR=true

# or use firebase credentials
NEXT_PUBLIC_FIREBASE_API_KEY=your_firebase_key
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your_auth_domain
NEXT_PUBLIC_FIREBASE_PROJECT_ID=your_project_id
FIREBASE_ADMIN_CREDENTIALS=your_admin_credentials

# Stripe
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=your_stripe_publishable_key
STRIPE_SECRET_KEY=your_stripe_secret_key
STRIPE_WEBHOOK_SECRET_TEST=your_webhook_secret

# Telegram (optional)
TELEGRAM_BOT_TOKEN=your_telegram_bot_token

Run the development server:

pnpm dev

Open http://localhost:3000 in your browser

HTTPS Development (Optional)

For testing features that require HTTPS (like webcam):

pnpm dev:https

📝 Available Scripts

Development

pnpm dev                # Start development server with Turbopack
pnpm dev:https          # Start with HTTPS enabled
pnpm build              # Build for production
pnpm start              # Start production server
pnpm lint               # Type checking with TypeScript

Testing

pnpm test               # Run all tests (unit + e2e)
pnpm test:unit          # Run Jest unit tests
pnpm test:unit:watch    # Run Jest in watch mode
pnpm test:e2e           # Run Playwright e2e tests
pnpm test:e2e:ui        # Run Playwright with UI
pnpm test:e2e:headed    # Run Playwright in headed mode

Internationalization

pnpm lang               # Extract, translate, and compile language files
pnpm ai-translate       # AI-powered translation of new strings

Code Quality

pnpm format             # Format code with Prettier
pnpm format:check       # Check code formatting

Deployment

pnpm prod               # Build and deploy to Vercel

🔧 Development Tools

Stripe Webhook Testing

Start Stripe webhook simulator (update STRIPE_WEBHOOK_SECRET_TEST in .env):

pnpm stripe-hook
# or manually:
stripe listen --forward-to localhost:3000/api/webhooks/stripe

Regenerate Stripe local key:

stripe login

Update Stripe CLI:

brew upgrade stripe/stripe-cli/stripe

Telegram Integration

Set webhook:

curl -X POST "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/setWebhook" \
  -d "url=https://your-domain.com/api/telegram/webhook"

Verify webhook:

curl "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getWebhookInfo"

Start ngrok tunnel:

pnpm tg    # Using custom domain
pnpm tg2   # Random domain

Video Conversion

Convert MP4 videos to WebM format for web optimization:

ffmpeg -i input.mp4 -c:v libvpx-vp9 -crf 32 -b:v 0 -pix_fmt yuv420p -an output.webm

📁 Project Structure

dark-eng/
├── src/
│   ├── app/                    # Next.js App Router pages
│   │   ├── [lang]/            # Internationalized routes
│   │   ├── api/               # API routes
│   │   ├── practice/          # Practice page
│   │   └── ...
│   ├── features/              # Feature-based modules
│   │   ├── Ai/               # AI integration
│   │   ├── Auth/             # Authentication
│   │   ├── Chat/             # Chat interface
│   │   ├── Conversation/     # Conversation logic
│   │   ├── RolePlay/         # Role-play scenarios
│   │   ├── Landing/          # Landing page components
│   │   └── ...
│   ├── common/               # Shared utilities
│   ├── libs/                 # Library functions
│   └── locales/              # Translation files
├── public/                   # Static assets
├── e2e/                      # End-to-end tests
├── __mocks__/               # Test mocks
└── ...config files

🌐 Deployment

The project is configured for deployment on Vercel with automatic builds from the main branch.

Environment Setup

Configure all required environment variables in Vercel dashboard
Set up Firebase, OpenAI, and Stripe integrations
Configure custom domain and SSL
Set up Sentry for error tracking

🧪 Testing

Unit Tests

Tests are written using Jest and React Testing Library:

pnpm test:unit

E2E Tests

End-to-end tests use Playwright:

pnpm test:e2e

Test files are located in the e2e/ directory and include:

Alias game functionality
Internationalization
Lighthouse performance tests

🤝 Contributing

Contributions are welcome ❤️

If you’d like to contribute:

Open an issue to discuss ideas, bugs, or improvements
Submit a pull request with a clear description
Follow existing code style and project structure

By contributing, you agree that your contributions will be licensed under the same license as this project.

📄 License

This project is open source and licensed under the MIT License.

You are free to:

use
copy
modify
merge
publish
distribute
sublicense
and/or sell copies of the software

subject to the conditions outlined in the LICENSE file.

Important note:
This repository contains application source code only.
Running FluencyPal in production requires your own API keys, infrastructure, and compliance with third-party service terms (OpenAI, Firebase, Stripe, etc.).

🔗 Links

Website: https://www.fluencypal.com
Support: Contact via website

🙏 Acknowledgments

Built with:

OpenAI GPT-4 for conversational AI
Firebase for authentication and database
Stripe for payment processing
Material-UI for UI components
Next.js for the web framework

™ Trademark

“FluencyPal” is a trademark of the project author.

You may fork and deploy this software under a different name, but you may not use the “FluencyPal” name, logo, or branding for derivative or commercial offerings without explicit permission.

Made with ❤️ for language learners worldwide