LingoSpeak 🌐 — Translate & Listen

LingoSpeak is a Streamlit web app that translates text into a language of your choice using Google's Gemini API, then converts the translation into speech using gTTS (Google Text-to-Speech) so you can listen to it or download it as an MP3.

You can type text directly, or upload a TXT, PDF, CSV, or Excel file and the app will extract the text for you.

---

1. Features

• Free-text input or file upload (.txt, .pdf, .csv, .xlsx, .xls)
• Translation into 30+ languages via the Gemini API
• Text-to-speech audio generation (MP3) via gTTS
• In-browser audio playback and one-click MP3 download
• Friendly error messages for bad input, missing keys, or API failures

2. Project Structure

lingospeak/
├── app.py                  # Main Streamlit app (UI + workflow)
├── utils/
│   ├── file_reader.py      # Extracts text from TXT / PDF / CSV / Excel
│   ├── translator.py       # Calls the Gemini API for translation
│   ├── tts.py               # Converts text to speech with gTTS
│   └── languages.py        # Dropdown language list + gTTS language codes
├── .streamlit/
│   └── config.toml         # App theme / server settings
├── .vscode/
│   ├── launch.json         # "Run and Debug" config for VS Code (F5)
│   └── settings.json       # Points VS Code at the project's virtualenv
├── requirements.txt        # Python dependencies
├── .env.example             # Template for your API key (copy to .env)
├── .gitignore
└── README.md                # This file

3. Prerequisites

• Python 3.9+ installed on Windows
• VS Code with the Python extension (ms-python.python)
• A free Gemini API key from Google AI Studio: https://aistudio.google.com/app/apikey

4. Setup (Windows / VS Code)

1. Open the lingospeak folder (or the lingospeak.code-workspace file) in VS Code.
2. Open a terminal in VS Code (Terminal → New Terminal) and create a virtual environment:

   python -m venv .venv
   .venv\Scripts\activate

3. Install the dependencies:

   pip install -r requirements.txt

4. Set up your API key. Copy .env.example to .env:

   copy .env.example .env

   Then open .env and paste your key:

   GEMINI_API_KEY=your_actual_key_here
   

   Alternatively, you can skip .env entirely and paste the key directly into the sidebar field when the app is running — it is only kept for your current browser session and is never written to disk by the app.
5. In VS Code, select the .venv interpreter: Ctrl+Shift+P → "Python: Select Interpreter" → choose .venv.

5. Running the App

Option A — from the terminal:

streamlit run app.py

This opens the app automatically at http://localhost:8501 in your browser.

Option B — from VS Code "Run and Debug": Press F5 (or the Run/Debug panel) and choose "Streamlit: Run LingoSpeak". This is pre-configured in .vscode/launch.json.

6. How to Use the App

1. Enter your Gemini API key in the sidebar (if not already loaded from .env).
2. Choose Type text or Upload a file as your input method.
3. Select the target language from the dropdown.
4. Click Translate. The translated text appears in a text box.
5. Click Generate Audio to synthesize speech from the translation.
6. Use the built-in player to listen, or click Download MP3 to save the file.

7. Getting a Gemini API Key

1. Go to https://aistudio.google.com/app/apikey
2. Sign in with a Google account.
3. Click Create API key and copy the generated key.
4. Paste it into .env or directly into the app's sidebar.

Google's Gemini API has a free usage tier with rate limits. If you see quota errors, wait a bit before retrying or check your usage at https://aistudio.google.com.

8. Deployment

The app can be deployed for free with Streamlit Community Cloud:

1. Push this project to a GitHub repository (the .gitignore already excludes .env so your key won't be committed).
2. Go to https://share.streamlit.io and connect your GitHub repo.
3. Set app.py as the entry point.
4. In the app's Settings → Secrets, add:

   GEMINI_API_KEY = "your_actual_key_here"
   

5. Deploy. Streamlit Cloud will install requirements.txt automatically.

(Heroku deployment follows the standard Procfile + runtime.txt approach if you prefer that platform instead.)

9. Considerations, Limitations & Known Challenges

• API key required. Translation will not work without a valid Gemini API key; the app raises a clear error if it's missing/invalid.
• Rate limits / quota. The free Gemini tier enforces rate limits. Heavy use may trigger 429 errors — the app surfaces these as a friendly message rather than crashing.
• gTTS depends on an internet connection. It calls Google's public Translate TTS endpoint; it cannot be used fully offline.
• gTTS text length. Very long text is truncated to ~5,000 characters before speech synthesis, since extremely long input can make the TTS endpoint unreliable. The full translated text is still shown and can be copied even if the audio only covers the first portion.
• Scanned/image-only PDFs contain no extractable text; the app will report that no text was found instead of guessing. OCR is not currently implemented.
• Excel/CSV translation flattens the sheet into readable lines (row by row) before translating; complex spreadsheets with many columns may produce a translation that is harder to map back to specific cells.
• Language code mismatches. A handful of languages Gemini can translate into don't have a distinct gTTS voice; utils/languages.py only lists languages that both Gemini and gTTS support well, to avoid silent failures.
• No persistent storage. Audio is generated in memory and offered as a direct download; nothing is saved permanently on the server, so refreshing the page clears the current session's results.

10. Tech Stack

Purpose	Library / Service
Web UI	Streamlit
Translation	Google Gemini API
Text-to-speech	gTTS
PDF parsing	PyPDF2
CSV / Excel parsing	pandas, openpyxl
Config	python-dotenv

---

Built as a capstone project demonstrating Streamlit UI development, LLM-powered translation, and speech synthesis integration.