English Vocabulary Learning Program

1. Purpose

This project is a desktop application designed to help users learn English vocabulary in an effortless and non-intrusive way. It periodically displays a dialog box with a new vocabulary word, its meaning, pronunciation, and an example sentence. The goal is to facilitate passive learning by exposing the user to new words throughout the day.

This project was created with the assistance of the Google Gemini CLI.

2. Features

• Periodic Word Display: Shows a new vocabulary word at configurable intervals.
• Interactive Dialog:
  • Displays the word, phonetic pronunciation, meaning, and an example sentence.
  • In-place Translation: Toggle between the English word and its translation without a disruptive pop-up.
  • Natural Pronunciation: Click the speaker icon to hear the word pronounced with a natural-sounding voice.
• Customizable:
  • Easily add your own words by creating vocabulary*.json files.
  • Configure the display interval, dialog duration, and translation language via conf.json.
• Smart Display:
  • Remembers which words you've chosen to "hide" so you only see the words you want to learn.
  • Automatically centers on your primary monitor.

3. Setup

The project includes a setup script to automate the installation of all necessary dependencies.

1. Make the script executable:

   chmod +x setup.sh

2. Run the setup script:

   ./setup.sh

   The script will:
   • Install system-level dependencies (like python3-tk).
   • Create a Python virtual environment in the venv/ directory.
   • Install all required Python packages from requirements.txt.

4. How to Use

After the setup is complete, you can run the application with the following command:

./venv/bin/python displayWord.py

The application will run in the background, and a vocabulary dialog will appear on your screen based on the interval set in your configuration. To stop the application, you can press Ctrl+C in the terminal where it is running.

5. Generating New Vocabulary

The project includes a powerful script, generate.py, to automatically create new vocabulary files from a simple word list.

a. API Key Setup

The script uses the Google Gemini API to fetch definitions, pronunciations, and example sentences. You will need an API key to use it.

1. Get your API key from Google AI Studio.
2. In the project's root directory, rename the .env.example file to .env.
3. Open the .env file and paste your API key into it:

   GEMINI_API_KEY="your_api_key_here"
   

b. Create a Word List

Create a simple text file (e.g., my_words.txt) and add one English word per line.

resilience
ephemeral
ubiquitous

c. Run the Script

Execute the generate.py script from your terminal, providing the path to your source word list and the desired name for the output JSON file.

./venv/bin/python generate.py my_words.txt vocabulary_new.json

The script will process each word and create a vocabulary_new.json file in the correct format, ready to be used by the main application.

Intelligent Updating: The script is designed to be run multiple times on the same files.

• Adds New Words: If you add new words to your .txt file, the script will only process the new words and add them to your existing .json file without creating duplicates.
• Completes Missing Info: If any existing words in your .json file are missing a meaning, pronunciation, or example sentence, the script will automatically detect this and attempt to generate the missing information. This makes it a useful tool for both creating and maintaining your vocabulary lists.

6. Configuration

You can customize the application's behavior by editing the following files:

conf.json

This file controls the application's settings.

• interval: The time in seconds between showing new words (e.g., 1800 for 30 minutes).
• duration: The time in seconds the dialog stays on screen. Set to a negative number to disable auto-close.
• title: The title of the dialog window.
• translation: The target language for translation. Supported values: "traditional chinese", "simplified chinese", "japanese", "korean".

vocabulary*.json

You can add your own vocabulary lists by creating one or more JSON files with names like vocabulary_1.json, vocabulary_custom.json, etc. The application will automatically load all files that match the vocabulary*.json pattern.

Each file should contain a list of word objects with the following structure:

[
  {
    "display": "true",
    "word": "Allocate",
    "meaning": "To distribute (resources or duties) for a particular purpose.",
    "pronunciation_kk": "/ˈæləkeɪt/",
    "example_sentence": "The budget committee needs to allocate funds carefully."
  },
  {
    "display": "true",
    "word": "Resilience",
    "meaning": "The capacity to recover quickly from difficulties; toughness.",
    "pronunciation_kk": "/rɪˈzɪliəns/",
    "example_sentence": "The team showed great resilience after losing the first game."
  }
]

• display: Set to "true" to include the word in the random selection, or "false" to exclude it. The "Hide" button in the app automatically sets this to "false".