LinguaLink User Manual
======================

LinguaLink is a language-learning system with three main learning tools:
- Translation module
- Quiz module
- Flashcards module

You can use LinguaLink through:
- Web interface (`lingualink-web`)
- Console interface (`lingualink-app`)


Getting Started
---------------

1) Start one of the apps:
- Web: `.\mvnw.cmd -pl lingualink-web spring-boot:run`
- Console: `.\mvnw.cmd -pl lingualink-app exec:java`

2) Choose the feature you want:
- Translation
- Quiz
- Flashcards


System Overview
---------------

- `lingualink-core`
  Contains learning logic and models.

- `lingualink-data`
  Loads vocabulary and quiz data from packaged files.

- `lingualink-web`
  Browser-based interface for all features.

- `lingualink-app`
  Terminal-based interactive interface.


Translation Module
------------------

Purpose:
- Translate words/phrases between supported language codes.

How it works:
- First checks local vocabulary data.
- If no local match is found (web module), it can try online fallback translation.

Web usage:
1) Open `/translate`.
2) Select source language and target language.
3) Enter text.
4) Submit to view translation result.

Console usage:
1) Select option `1` in the menu.
2) Enter source language code (for example, `en`).
3) Enter target language code (for example, `es`).
4) Enter word/phrase.
5) Read result in terminal.

Expected outcomes:
- Found translation: translated text is displayed.
- Not found: message indicates no translation was found and suggests expanding data files.


Quiz Module
-----------

Purpose:
- Practice vocabulary knowledge with multiple-choice questions.

How it works:
- Questions are loaded from quiz data.
- Each answer is checked immediately and feedback is shown.
- A final summary score is shown at completion.

Web usage:
1) Open `/quiz`.
2) Start quiz.
3) Select an answer for each question.
4) View immediate feedback after each submission.
5) Review final score on completion page.

Console usage:
1) Select option `2` in the menu.
2) Enter the number for your answer choice.
3) Continue until all questions are completed.
4) Read final score summary.

Notes:
- In console mode, entering `0` during quiz answer input cancels the quiz.


Flashcards Module
-----------------

Purpose:
- Learn by topic-based term/translation cards with example usage.

How it works:
- Topics are listed first.
- Each topic contains flashcards.
- Each flashcard includes a term and translation, and may include an example sentence.

Web usage:
1) Open `/flashcards`.
2) Choose a topic.
3) Review cards in the selected deck.

Console usage:
1) Select option `3` in the menu.
2) Choose a topic number.
3) Press Enter to reveal each translation.
4) Continue through deck until complete.


Key Features Summary
--------------------

- Local-first translation data for quick lookups.
- Optional online translation fallback in web module.
- Interactive quiz flow with instant feedback and score summary.
- Topic-based flashcard study with example context.
- Two interfaces (web and console) for flexible usage.


Troubleshooting for Users
-------------------------

- No translation found:
  - Try different language codes or simpler text.
  - Ask maintainer to add missing vocabulary entries.

- Quiz not showing questions:
  - Verify quiz dataset is present and loaded.

- Web app unavailable:
  - Confirm app is running.
  - Open correct URL and port.


Tips for Best Experience
------------------------

- Use short, clear input for translation.
- Repeat quiz sessions to improve retention.
- Study flashcards by topic in small focused batches.
