Skip to content

USER_GUIDE.md

Latest commit

 

History

History
524 lines (382 loc) · 13.5 KB

USER_GUIDE.md

File metadata and controls

524 lines (382 loc) · 13.5 KB

LinguaChat User Guide

Welcome to LinguaChat! This guide will help you get the most out of your language learning experience.

Table of Contents

  1. Getting Started
  2. Selecting Your Language
  3. Choosing Difficulty Level
  4. Practice Scenarios
  5. Having a Conversation
  6. Using Corrections
  7. Managing Your Vocabulary
  8. Tips for Effective Learning
  9. Frequently Asked Questions
  10. Troubleshooting

Getting Started

First Visit

  1. Open LinguaChat in your web browser
  2. You'll see the landing page with language options
  3. Select your target language
  4. Choose your difficulty level
  5. Click "Start Learning" to proceed to scenarios

System Requirements

  • Modern web browser (Chrome, Firefox, Safari, Edge)
  • Internet connection
  • JavaScript enabled
  • Recommended: Desktop or tablet for best experience (mobile supported)

Selecting Your Language

LinguaChat currently supports 5 languages:

Language Level Best For
Spanish (Español) All levels Most widely spoken, great for beginners
French (Français) All levels Romance language, popular for travel
German (Deutsch) Intermediate+ Business and academic contexts
Italian (Italiano) All levels Cultural immersion, food, art
Japanese (日本語) All levels Unique writing system, cultural depth

To select a language:

  1. Click on any language card on the home page
  2. The card will highlight with a colored ring
  3. Proceed to select your difficulty level

Choosing Difficulty Level

Beginner

Best for: Never studied the language, or learned years ago

What to expect:

  • Simple sentence structures
  • Present tense focus
  • Common, everyday vocabulary
  • Short, clear responses from AI
  • Basic grammar corrections

Example conversation:

You: "Hello, my name is Alex." AI: "Hello Alex! Nice to meet you. What is your favorite food?"

Intermediate

Best for: 1-3 years of study, can hold basic conversations

What to expect:

  • More complex sentences
  • Past, present, and future tenses
  • Broader vocabulary range
  • Longer exchanges
  • Detailed grammar explanations

Example conversation:

You: "Yesterday I went to the market and bought fresh vegetables." AI: "That sounds wonderful! Which vegetables did you choose? Do you enjoy cooking?"

Advanced

Best for: 3+ years of study, comfortable with complex grammar

What to expect:

  • Native-like complexity
  • Idioms and colloquial expressions
  • Subjunctive and advanced tenses
  • Cultural references
  • Nuanced corrections

Example conversation:

You: "I've been thinking about the implications of remote work on urban development." AI: "That's a fascinating topic! The pandemic accelerated trends that were already emerging. What aspects interest you most?"

Practice Scenarios

Choose from 7 real-world scenarios to practice:

1. Casual Introduction & Small Talk

Level: All Use for: Meeting new people, networking, making friends Topics: Name, hobbies, weather, weekend plans

2. Ordering at a Restaurant

Level: Beginner-Intermediate Use for: Dining out, food vocabulary, dietary restrictions Topics: Menu items, preferences, allergies, paying the bill

3. Shopping & Asking for Directions

Level: Beginner-Intermediate Use for: Navigating cities, buying items, tourist situations Topics: Locations, prices, sizes, getting around

4. Travel & Hotel Check-in

Level: Intermediate Use for: Business or leisure travel preparation Topics: Reservations, room preferences, amenities, complaints

5. Job Interview Practice

Level: Intermediate-Advanced Use for: Career preparation, business language Topics: Experience, skills, goals, salary negotiation

6. Everyday Conversations

Level: All Use for: General fluency, mixed topics Topics: Work, family, current events, opinions

7. Free-form Chat

Level: All Use for: Flexible practice, exploring interests Topics: Anything you want to discuss!

Having a Conversation

Starting Your Chat

  1. After selecting scenario, you'll see the chat interface
  2. The AI will greet you in your target language
  3. Type your response in the text box at the bottom
  4. Click the send button (→) or press Enter

Chat Interface Guide

Header (Top)

  • Scenario name
  • Difficulty badge
  • Settings menu (⚙️)
    • Toggle Corrections
    • View Vocabulary
    • New Conversation
    • End Conversation

Message Area (Middle)

  • Your messages appear on the right (purple/blue gradient)
  • AI messages appear on the left (gray background)
  • Scroll to see older messages

Input Area (Bottom)

  • Text field (max 500 characters)
  • Character counter
  • Send button
  • Hint: Press Shift+Enter for new line

Best Practices

Do:

  • ✅ Write naturally as you would speak
  • ✅ Try to use the target language exclusively
  • ✅ Make mistakes - that's how you learn!
  • ✅ Ask the AI to explain something if confused
  • ✅ Practice regularly (10-15 minutes daily)

Don't:

  • ❌ Copy-paste from translators (defeats the purpose)
  • ❌ Write overly long messages (keep under 500 characters)
  • ❌ Switch to English mid-conversation
  • ❌ Give up on difficult words - try to express differently

Using Corrections

Viewing Corrections

Corrections appear automatically when the AI detects errors in your messages.

To open the corrections panel:

  1. Click Settings (⚙️) in the header
  2. Click "Toggle Corrections"
  3. Panel slides in from the right

To close:

  • Click the X button
  • Press Escape key
  • Click outside the panel (mobile)

Understanding Correction Cards

Each correction shows:

Original Text (red, strikethrough)

I go to store yesterday

Corrected Version (green highlight)

I went to the store yesterday

Category Badge

  • 🔤 Grammar
  • 📚 Vocabulary
  • ✏️ Spelling
  • 💬 Style

Explanation (expandable)

"Go" should be "went" (past tense) because the action happened yesterday. Also, "store" needs the article "the" in English.

Correction Categories

Grammar

  • Verb conjugation
  • Tense usage
  • Article placement
  • Word order

Vocabulary

  • Word choice
  • Inappropriate terms
  • Better alternatives

Spelling

  • Typos
  • Accent marks
  • Special characters

Style

  • More natural phrasing
  • Formal vs. informal
  • Native-like expressions

Managing Your Vocabulary

Automatic Vocabulary Tracking

When the AI responds, it automatically identifies new or important words and adds them to your vocabulary list with:

  • The word in target language
  • English translation
  • The sentence where you encountered it
  • Date learned

Viewing Your Vocabulary

  1. Click Settings (⚙️) in chat header
  2. Click "View Vocabulary"
  3. Or navigate to /vocabulary from any page

Vocabulary Dashboard Features

Stats Cards

  • Total words learned
  • Words this week
  • Words this month
  • Most practiced language

Search Bar

  • Type to search words or translations
  • Real-time filtering

Language Filter

  • Filter by specific language
  • Useful if you're studying multiple languages

Sort Options

  • By date (newest first)
  • Alphabetically (A-Z)

Vocabulary Cards

  • Click to flip between word and translation
  • Shows context sentence
  • Date learned
  • Remove button (with confirmation)

Managing Words

To remove a word:

  1. Find the word in your vocabulary list
  2. Click the trash icon
  3. Confirm deletion

To clear all vocabulary:

  1. Click "Clear All" button
  2. Confirm in dialog box
  3. This cannot be undone!

Tips for Effective Learning

Session Structure

Warm-up (2 min)

  • Review yesterday's vocabulary
  • Read previous conversation

Practice (10-15 min)

  • Focus on one scenario
  • Complete 5-8 message exchanges
  • Pay attention to corrections

Cool-down (3 min)

  • Review new vocabulary
  • Note patterns in corrections
  • Plan next session's focus

Learning Strategies

For Beginners:

  1. Start with simple sentences
  2. Focus on present tense first
  3. Build vocabulary gradually
  4. Repeat similar conversations
  5. Don't fear mistakes!

For Intermediate:

  1. Mix different tenses
  2. Try different scenarios
  3. Use more complex sentences
  4. Challenge yourself with new topics
  5. Review correction patterns

For Advanced:

  1. Aim for native-like fluency
  2. Use idioms and expressions
  3. Discuss abstract topics
  4. Focus on style refinement
  5. Practice professional contexts

Maximizing Progress

Daily Practice

  • 10-15 minutes daily > 1 hour weekly
  • Consistency builds habits
  • Morning sessions for focus

Active Review

  • Review corrections regularly
  • Practice problematic grammar
  • Use new vocabulary in next session

Set Goals

  • Learn 5 new words per session
  • Complete 1 full scenario per week
  • Achieve a 10-day streak

Frequently Asked Questions

General

Q: Is my data saved between sessions? A: Yes! Your vocabulary is saved in your browser's local storage. However, conversation history is currently ephemeral (session-only).

Q: Can I practice multiple languages? A: Yes! You can switch languages anytime from the home page. Your vocabulary is tracked separately for each language.

Q: How does the AI know my level? A: The AI adjusts its responses based on the difficulty level you select. You can change this anytime by starting a new conversation.

Q: Can I use this offline? A: No, an internet connection is required as the AI processes requests in real-time.

Corrections

Q: Why don't I see corrections for every message? A: The AI only provides corrections when it detects errors. Perfect messages won't have corrections!

Q: Can I disable corrections? A: You can hide the corrections panel, but corrections are still generated. They're valuable for learning!

Q: Are corrections available in all languages? A: Yes, corrections work for all 5 supported languages.

Vocabulary

Q: How are vocabulary words chosen? A: The AI selects important or challenging words from the conversation that are relevant to your level.

Q: Can I manually add words? A: Not yet! This feature is planned for a future update.

Q: Will I lose my vocabulary if I clear my browser data? A: Yes, vocabulary is stored locally. Be careful when clearing browser data!

Technical

Q: What browsers are supported? A: Chrome, Firefox, Safari, and Edge (latest versions).

Q: Why are responses sometimes slow? A: AI processing can take 2-3 seconds. Slow internet may also affect speed.

Q: Is there a mobile app? A: Currently web-only, but the site is mobile-optimized. A native app may come later!

Troubleshooting

Common Issues

Problem: "API key not configured" error Solution: This means the OpenAI API key is missing. If you're the developer, add it to .env.local. If you're a user, contact the administrator.

Problem: Messages not sending Solutions:

  • Check your internet connection
  • Try refreshing the page
  • Clear browser cache
  • Check if you hit the rate limit (10 messages/minute)

Problem: Corrections panel won't open Solutions:

  • Refresh the page
  • Try closing and reopening
  • Check browser console for errors

Problem: Vocabulary not saving Solutions:

  • Ensure cookies/storage are enabled
  • Check available disk space
  • Don't use private/incognito mode for persistent storage

Problem: Can't see my language Solutions:

  • Currently only 5 languages supported
  • More languages may be added in future updates
  • Request your language via GitHub issues

Getting Help

Still having issues?

  1. Check TASKS.md for known bugs
  2. Open an issue on GitHub
  3. Include:
    • Browser and version
    • Steps to reproduce
    • Screenshots if possible
    • Error messages

Keyboard Shortcuts

Shortcut Action
Enter Send message
Shift + Enter New line in message
Escape Close corrections panel
Tab Navigate between elements

Privacy & Data

What We Store

  • Vocabulary: Stored locally in your browser
  • Preferences: Theme, difficulty level
  • Analytics: Anonymous usage statistics (page views, events)

What We Don't Store

  • Conversations: Not saved beyond the current session
  • Personal info: No account required, no data collection
  • Messages: Not logged or stored on servers

Your Data Rights

  • Clear vocabulary anytime (Settings → Clear All)
  • Clear browser data to remove all local storage
  • Analytics can be blocked with browser extensions

Updates & Roadmap

LinguaChat is actively developed. Upcoming features:

  • 🔄 Conversation history (save past chats)
  • 🎤 Voice input (speak your responses)
  • 🔊 Text-to-speech (hear AI responses)
  • 📊 Progress tracking (stats & achievements)
  • 🎯 Custom scenarios
  • ➕ More languages

Check TASKS.md for the full development roadmap!

Feedback

We'd love to hear from you!

  • 🐛 Report bugs on GitHub Issues
  • 💡 Suggest features
  • ⭐ Star the repo if you find it useful
  • 🤝 Contribute via pull requests

Happy Learning! 🎉

Remember: The key to language learning is consistent practice. Even 10 minutes a day makes a difference!