University of Ottawa Email Translator

Built for: Darlene Vail
Purpose: Personal French/English email translation
Scope: Single-user Windows-first Streamlit tool, not an enterprise service Current package: V1.2 UI-focused release; runtime contract inherited from V1.1.3

Privacy boundary

This application lets Darlene paste email text into a local browser interface and translate it with Hugging Face MarianMT models after those models are installed.

Important qualifications:

• First setup installs Python machine-translation packages and may download several GB of dependencies.
• First model preparation or first real translation may download model files from Hugging Face and cache them in models/.
• The application code is not designed to send pasted email text to a translation API.
• The application code is not designed to save pasted email text to disk or log email content.
• Model files are cached locally; pasted email text is not intentionally cached by this project.
• If the user downloads translated text from the browser, the browser will save a local file.

Recommended Python version

For Windows, use Python 3.11 or Python 3.12.

The app code itself is Python 3.9+ compatible, but the practical Windows runtime depends on ML package wheels. Python 3.11 or 3.12 is the recommended path for easiest dependency compatibility.

First-time Windows setup

1. Extract the ZIP to a normal folder, such as Desktop or Documents.
2. Install Python 3.11 or 3.12 if needed.
3. Double-click setup.bat.
4. Wait for dependency installation to finish.
5. Double-click PREPARE_MODELS.bat to download and verify both translation models.
6. Double-click START_TRANSLATOR.bat.
7. Use the browser page that opens at localhost.

The first setup and first model preparation can take time. Large packages and model files may download.

Normal use

After setup and model preparation:

1. Double-click START_TRANSLATOR.bat.
2. Paste the email text.
3. Select the translation direction.
4. Click Translate email.
5. Review the result before sending.
6. Use the editable translated-output box for final corrections.
7. Use the download option only if you want your browser to save a local text file.

Runtime checks

Use these scripts if something does not work:

• diagnose_runtime.py — checks Python, packages, Streamlit, model imports, and local environment.
• smoke_translate.py — performs one real French→English and one real English→French translation.
• PREPARE_MODELS.bat — prepares both translation models before regular use.

Verification completed before release

The V1.2 UI package was verified from a fresh extraction with:

• Python compilation
• Pytest suite
• Ruff lint
• Black formatting check
• Mypy type check
• Streamlit localhost smoke launch
• No packaged cache/build artifacts
• No runtime-file regression from V1.1.3

Remaining real-machine gate

The package should still be verified on the target Windows machine with:

• setup.bat
• PREPARE_MODELS.bat
• diagnose_runtime.py
• smoke_translate.py
• START_TRANSLATOR.bat
• One real French→English translation
• One real English→French translation

Not included

This is not:

• an Outlook add-in
• a Microsoft Graph integration
• a cloud translation service
• a multi-user app
• a database-backed system
• a compliance-certified institutional system

Future V2 work should focus on installer-grade packaging, managed Windows runtime, diagnostics UI, model manager, repair/reset flows, and release evidence.

Files

• app.py — Streamlit interface
• translator.py — translation engine and entity preservation
• setup.bat — Windows dependency setup
• PREPARE_MODELS.bat — model preparation / smoke translation helper
• START_TRANSLATOR.bat — Windows app launcher
• diagnose_runtime.py — runtime diagnostics
• smoke_translate.py — real translation smoke test
• WINDOWS_LIVE_TEST_CHECKLIST.md — final target-machine checklist
• QUICK_REFERENCE.md — short user-facing reference
• RUNBOOK.md — support/operator runbook
• UI_RELEASE_NOTES.md — V1.2 UI release notes

Support posture

If translation fails, run:

python diagnose_runtime.py
python smoke_translate.py

If the app shell opens but translation fails, the likely cause is dependency installation, model download, model cache corruption, or blocked network access during model preparation.

For production-style packaging, move to V2 installer/runtime-managed architecture instead of expanding the current ZIP handoff.

V1.2 design note

V1.2 is intentionally still a Streamlit package. It improves the user workflow and polish without changing the runtime contract. It should be treated as the final UI candidate for the ZIP-based product line, not as an enterprise deployment architecture.

Future V2 productization should focus on truthful privacy boundaries, Windows runtime reproducibility, installer-grade setup, diagnostics, and non-technical usability rather than enterprise scalability patterns.

Repository baseline and V2 productization plan

This repository was initialized from uottawa_email_translator_v1_2_ui.zip as the V1.2 UI baseline.

V2 productization is tracked in GitHub issue #1: #1

This repository is standalone for the uOttawa Email Translator project and is not Harbourview or WURX product code.