Skip to content

Commit f8ae9a5

Browse files
andreisuguandreisugu
authored
Update README.md
Initial Readme
1 parent 98a0474 commit f8ae9a5

1 file changed

Lines changed: 264 additions & 2 deletions

File tree

‎README.md‎

Lines changed: 264 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,264 @@
1-
# TerminaLingo
2-
Interactive Terminal Application for Language Learning
1+
# TerminaLingo: Interactive Language Learning CLI
2+
3+
## 📚 About TerminaLingo
4+
5+
TerminaLingo is a console-based Java application designed to facilitate foreign language learning through interactive lessons. It provides a structured environment for users to practice vocabulary and translation skills, track their progress, and manage their learning journey directly from the command line.
6+
7+
## ✨ Key Features
8+
9+
* **User Management**: Secure registration and login system with password hashing (jBCrypt).
10+
11+
* **Progress Tracking**: Records completed lessons, scores, unique learned words, and daily login streaks.
12+
13+
* **Dynamic Lessons**: Loads multi-part lessons from customizable JSON files.
14+
15+
* **Varied Exercises**: Supports different test types, including:
16+
17+
* Translation with provided word banks.
18+
19+
* Free-form translation.
20+
21+
* Word matching exercises.
22+
23+
* Informative text displays.
24+
25+
* **Intuitive CLI**: Menu-driven navigation for selecting languages, chapters, and lessons.
26+
27+
* **Data Persistence**: All user data and progress are saved locally in JSON files (Gson).
28+
29+
* **Text Normalization**: Robust handling of accents and punctuation for accurate answer comparison.
30+
31+
## 🚀 Getting Started
32+
33+
To get TerminaLingo up and running on your local machine, follow these steps:
34+
35+
### Prerequisites
36+
37+
* **Java Development Kit (JDK) 17 or newer**: Ensure JDK 17+ is installed and configured in your system's PATH. You can download it from [Oracle](https://www.oracle.com/java/technologies/downloads/) or [Adoptium (OpenJDK)](https://adoptium.net/).
38+
39+
* **Git** (optional, for cloning): If you prefer to clone the repository.
40+
41+
### Installation & Setup
42+
43+
1. **Clone the repository (or download the source code):**
44+
45+
```
46+
git clone https://github.com/andreisugu/TerminaLingo/
47+
cd TerminaLingo
48+
```
49+
50+
2. **Configure Lesson Content:**
51+
52+
* Create a folder named `MasterLessons` in the root directory of the project (next to the `src` folder).
53+
54+
* Inside `MasterLessons`, create subfolders for each language (e.g., `English`, `Romanian`).
55+
56+
* Within each language folder, create subfolders for chapters (e.g., `Basics`, `Verbs`).
57+
58+
* Place your lesson JSON files (e.g., `Lesson1.json`, `Lecția1.json`) inside these chapter folders. Refer to the Data Structure section below for JSON format examples.
59+
60+
```
61+
TerminaLingo/
62+
├── src/
63+
│ └── ... (Java files)
64+
├── MasterLessons/
65+
│ ├── English/
66+
│ │ ├── Basics/
67+
│ │ │ └── Lesson1.json
68+
│ │ └── Advanced/
69+
│ │ └── Lesson2.json
70+
│ └── Romanian/
71+
│ ├── Basics/
72+
│ │ └── Lecția1.json
73+
│ └── Verbs/
74+
│ └── Lecția2.json
75+
└── users.json (generated on first run)
76+
77+
```
78+
79+
3. **Dependencies:**
80+
TerminaLingo uses Google Gson for JSON processing and jBCrypt for password hashing.
81+
82+
* **Maven:** `pom.xml`:
83+
84+
```
85+
<dependencies>
86+
<dependency>
87+
<groupId>com.google.code.gson</groupId>
88+
<artifactId>gson</artifactId>
89+
<version>2.10.1</version> <!-- Use the latest stable version -->
90+
</dependency>
91+
<dependency>
92+
<groupId>org.mindrot</groupId>
93+
<artifactId>jbcrypt</artifactId>
94+
<version>0.4</version> <!-- Use the latest stable version -->
95+
</dependency>
96+
</dependencies>
97+
98+
```
99+
100+
### Running the Application
101+
102+
1. **Compile:**
103+
Open your terminal in the project's root directory (`TerminaLingo/`) and compile the Java files.
104+
105+
* **With Maven:**
106+
107+
```
108+
mvn clean install
109+
110+
```
111+
112+
2. **Execute:**
113+
114+
* **With Maven:**
115+
116+
```
117+
mvn exec:java -Dexec.mainClass="org.RestlessTech.TerminaLingo.Main"
118+
119+
```
120+
121+
122+
## 🎮 Usage
123+
124+
Once the application is running, follow the on-screen prompts in your console:
125+
126+
### Authentication:
127+
128+
* Choose to **Register Account (1)** or **Login (2)**.
129+
130+
* Follow the prompts to enter your username and password.
131+
132+
### Navigation:
133+
134+
* After logging in, you'll enter the language selection menu.
135+
136+
* Enter the number corresponding to your desired language, chapter, or lesson.
137+
138+
### Special Commands (available in most selection menus):
139+
140+
* **B** (or **0**): Go back to the previous menu.
141+
142+
* **S**: Display your personal statistics (login streak, completed lessons, learned words). Press Enter to continue.
143+
144+
* **L**: Log out and return to the authentication screen.
145+
146+
* **E**: Exit the program.
147+
148+
### Lesson Progression:
149+
150+
* Each lesson presents various test types. Read the instructions carefully.
151+
152+
* Enter your answers in the console. The application will provide immediate feedback (correct/incorrect) and, if needed, the correct answer.
153+
154+
* Press Enter after each response to proceed.
155+
156+
## 📂 Project Structure
157+
158+
The project is organized into a single main Java package, `org.RestlessTech.TerminaLingo`, containing all core classes:
159+
160+
* `Main.java`: Application entry point.
161+
162+
* `InterfaceManager.java`: Handles the command-line interface, user navigation, and overall application flow.
163+
164+
* `AccountManager.java`: Manages user accounts, authentication, and user data persistence.
165+
166+
* `LessonParser.java`: Parses lesson JSON files and orchestrates the interactive testing logic.
167+
168+
* `User.java`: Data model for a user, including progress and learned words.
169+
170+
* `UserLessonProgress.java`: Records a user's score for a specific lesson.
171+
172+
* `Lesson.java`: Data model for a lesson, containing its name, difficulty, and a list of tests.
173+
174+
* `Test.java`: Data model for an individual test within a lesson, defining its type and content.
175+
176+
## 📝 Data Structure (JSON Examples)
177+
178+
### `users.json`
179+
180+
This file stores a list of `User` objects, including their progress.
181+
182+
```
183+
[
184+
{
185+
"lessonsCompleted": [
186+
{
187+
"lessonPath": "MasterLessons\\Romanian\\Basics\\Lesson1.json",
188+
"score": 95
189+
}
190+
],
191+
"learnedWords": [
192+
"salut",
193+
"bună"
194+
],
195+
"userName": "testuser",
196+
"password": "$2a$10$abcdefghijklmnopqrstuvw.xyz1234567890", // Hashed password
197+
"dailyLoginStreak": 2,
198+
"lastLoginDate": "09072025",
199+
"lessonsTotal": 1
200+
}
201+
]
202+
203+
```
204+
205+
### Lesson JSON File (e.g., `Lesson1.json`)
206+
207+
Lesson files are located in `MasterLessons/{Language}/{Chapter}/{LessonName}.json`. Each file represents a `Lesson` object and contains a list of `Test` objects.
208+
209+
```
210+
{
211+
"numeLectie": "Introduction to Romanian",
212+
"dificultate": "Easy",
213+
"cuvinteInvatate": [
214+
"hello",
215+
"good",
216+
"day"
217+
],
218+
"teste": [
219+
{
220+
"tip": 1,
221+
"propozitie": "Hello, how are you?",
222+
"raspunsCorect": "Salut, ce mai faci?",
223+
"leftWords": [],
224+
"rightWords": []
225+
},
226+
{
227+
"tip": 3,
228+
"propozitie": null,
229+
"raspunsCorect": null,
230+
"leftWords": ["dog", "cat"],
231+
"rightWords": ["câine", "pisică"]
232+
}
233+
]
234+
}
235+
236+
```
237+
238+
## 🔮 Future Enhancements
239+
240+
* **Graphical User Interface (GUI)**: Transition from CLI to a more intuitive GUI (e.g., JavaFX, Swing).
241+
242+
* **Relational Database**: Replace JSON persistence with a robust database solution (e.g., MySQL, PostgreSQL) and ORM (e.g., Hibernate, JPA).
243+
244+
* **More Test Types**: Introduce new exercise formats (e.g., sentence completion, multiple choice, listening comprehension).
245+
246+
* **Lesson Customization**: Allow users to create or modify lessons.
247+
248+
* **Advanced Statistics**: Implement detailed progress tracking with visualizations.
249+
250+
* **Gamification**: Add game-like elements (badges, leaderboards) to enhance engagement.
251+
252+
* **Internationalization**: Support multiple interface languages.
253+
254+
* **Unit Tests**: Implement comprehensive automated unit tests for core logic.
255+
256+
* **Online Synchronization**: Enable user progress synchronization across devices.
257+
258+
## 🤝 Contributing
259+
260+
Contributions are welcome! If you have suggestions for improvements or new features, please open an [issue](https://www.google.com/search?q=https://github.com/YourUsername/TerminaLingo/issues) or submit a [pull request](https://www.google.com/search?q=https://github.com/YourUsername/TerminaLingo/pulls).
261+
262+
## 📄 License
263+
264+
This project is licensed under the GNUV3.0 - see the `LICENSE` file for details.

0 commit comments

Comments
 (0)