Skip to content

Developer Setup

This guide covers installation for developers who want to work with the source code or contribute to the project.

Prerequisites

  • Python 3.9+
  • Git
  • pip

Installation from Source

  1. Clone the repository: bash git clone https://github.com/working-backwards/srt_translator.git cd srt_translator

  2. Create a virtual environment (recommended): ```bash # Windows python -m venv venv venv\Scripts\activate

# macOS/Linux python -m venv venv source venv/bin/activate ```

  1. Install the package: ```bash # CLI only (lightweight) pip install -e .

# With GUI support pip install -e '.[gui]'

# With development dependencies (testing, linting) pip install -e '.[dev]'

# Everything pip install -e '.[gui,dev]' ```

  1. Configure environment: bash cp examples/env_example .env # Edit .env and add your OPENAI_API_KEY

  2. Run the application: bash srtx # GUI srtx-cli # CLI

Building Executables

To create standalone executables with PyInstaller:

pip install pyinstaller

Quick Build (Recommended):

python scripts/build_gui.py

Manual Build:

  • Windows: bash pyinstaller --noconsole --name SRT-Translator \ --add-data "srt_translator/config/languages.json;srt_translator/config" \ srt_translator/gui/main_window.py

  • macOS: bash pyinstaller --windowed --name SRT-Translator \ --add-data "srt_translator/config/languages.json:srt_translator/config" \ srt_translator/gui/main_window.py

  • Linux: bash pyinstaller --windowed --name SRT-Translator \ --add-data "srt_translator/config/languages.json:srt_translator/config" \ srt_translator/gui/main_window.py

Output is created in dist/.

Note: The --add-data syntax uses ; on Windows and : on macOS/Linux.

macOS Rebuilding

  • Rebuild Terminal binary (fast): bash rm -rf dist/SRT-Translator build pyinstaller build_specs/srt_translator_gui.spec --noconfirm --clean

  • Rebuild Finder app (.app bundle): bash rm -rf dist/SRT-Translator.app build pyinstaller --windowed --name SRT-Translator \ --clean --noconfirm \ --add-data "srt_translator/config/languages.json:srt_translator/config" \ srt_translator/gui/main_window.py open dist/SRT-Translator.app

Running Tests

python -m pytest tests/

Build Scripts

All build and utility scripts are in scripts/:

scripts/
├── build_gui.py          # PyInstaller wrapper for GUI executable
├── build_release.py      # Standard Python package building
├── smoke_test.py         # Testing utilities
└── lint.py               # Linting utilities

CLI/GUI Architecture

The SRT Translator has clean separation between CLI and GUI:

  • CLI (srtx-cli): Lightweight, works on headless servers
  • GUI (srtx): Full graphical interface, requires PySide6
  • Core Engine: Shared translation logic used by both
srt_translator/
├── core/           # Pure translation logic (no GUI/CLI dependencies)
├── cli/            # CLI-specific code
├── gui/            # GUI-specific code
└── config/         # Configuration files

Troubleshooting

"Module not found" errors - Ensure you ran pip install -e . - Check you're in the correct virtual environment

zsh: no matches found: .[dev] - Quote the extras: pip install -e '.[dev]'

GUI doesn't start - Verify PySide6: pip install PySide6 - Check display server on Linux

For contributing guidelines, see CONTRIBUTING.md.