Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
158 changes: 39 additions & 119 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,9 +9,9 @@
</p>

<p align="center">
<a href="https://github.com/hubo1989/TransFrame/releases"><img src="https://img.shields.io/badge/version-1.0.0-blue.svg" alt="Version"></a>
<a href="https://github.com/hubo1989/TransFrame/releases"><img src="https://img.shields.io/github/v/release/hubo1989/TransFrame?include_prereleases" alt="Version"></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"></a>
<a href="https://www.apple.com/macos/"><img src="https://img.shields.io/badge/macOS-13.0%2B-brightgreen.svg" alt="macOS"></a>
<a href="https://www.apple.com/macos/"><img src="https://img.shields.io/badge/macOS-15.0%2B-brightgreen.svg" alt="macOS"></a>
<a href="https://swift.org/"><img src="https://img.shields.io/badge/Swift-6.0-orange.svg" alt="Swift"></a>
</p>

Expand All @@ -28,37 +28,38 @@
- **Multi-Monitor Support** - Automatic detection and support for multiple displays
- **Retina Display Optimized** - Perfect support for high-resolution displays

### 🆕 Text Translation
### Text Translation
- **Text Selection Translation** - Select any text and translate with a popup result window
- **Translate and Insert** - Replace selected text with translation (bypasses input method)
- **Translate and Insert** - Safely replace selected text with the translation (target revalidation + paste fallback, no input-method conflicts)
- **Independent Language Settings** - Separate target language configuration for translate-and-insert

### OCR Text Recognition
- **Apple Vision** - Native OCR, no additional configuration required
- **PaddleOCR** - Optional external engine with better Chinese recognition

### Multi-Engine Translation
Two converged modes: **ordered fallback chain** (up to 5 engines, try in order until one succeeds) and **parallel compare** (2–4 engines side by side with per-engine latency).
- **Apple Translation** - Built-in system translation, works offline
Two converged modes: **ordered fallback chain** (up to 5 engines, tried in order until one succeeds — a failing engine automatically falls through to the next) and **parallel compare** (2–4 engines translate simultaneously; switch between per-engine results with latency, no re-translation).
- **Apple Translation** - Built-in system translation, works offline (requires macOS 26; on older systems the chain automatically uses your next engine)
- **MTranServer** - Self-hosted translation server for high-quality translation
- **OpenAI-compatible** - OpenAI official / Ollama local / custom endpoints
- **OpenAI-compatible** - One card for OpenAI official / Ollama local / custom endpoints (keyless local endpoints supported)
- **Claude / Gemini / Google / DeepL / Baidu** - Cloud translation APIs
- Real availability probing: status dots reflect actual engine reachability
- **Real availability probing** - Status dots reflect actual engine reachability (green/red/orange/gray), never consuming paid API quota on automatic checks
- **Lossless migration** - Upgrading from the old four-mode configuration keeps your engines, keys, and selections

### Annotation Tools
- Rectangle selection
- Arrow annotation
- Freehand drawing
- Text annotation
- Screenshot cropping
- Rectangle, ellipse, line, arrow, freehand, and text annotations
- **Smart Mosaic / Privacy Redaction** - One-click redaction of detected sensitive regions
- **In-place Results Drawer** - OCR text and bilingual results docked inside the preview window
- Screenshot cropping, undo/redo, ⌘-drag constraints, draggable text

### Other Features
- **Translation History** - Save translation records with search and export
- **Bilingual Display** - Side-by-side original and translated text
- **Overlay Display** - Translation results displayed directly on the screenshot
- **Bilingual Display** - Original and translation side by side, grouped by visual line
- **Overlay Display** - Translation results rendered directly on the screenshot
- **Auto Update** - Built-in Sparkle updater (appcast channel)
- **Custom Shortcuts** - Global hotkeys for quick capture and translation
- **Menu Bar Quick Access** - All features accessible from menu bar
- **Multi-Language Support** - Support for 25+ languages
- **Menu Bar Quick Access** - All features accessible from the menu bar
- **Multi-Language UI** - Interface localized in 10 languages; follows the system language

## ⌨️ Keyboard Shortcuts

Expand Down Expand Up @@ -89,31 +90,16 @@ Two converged modes: **ordered fallback chain** (up to 5 engines, try in order u

## 📦 Requirements

- macOS 13.0 (Ventura) or later
- macOS 15.0 (Sequoia) or later
- Universal binary: runs natively on Apple Silicon and Intel Macs
- Screen Recording permission (prompted on first use)
- Accessibility permission (required for text translation features)

## Download & Installation

Download the latest version from the [Releases](../../releases) page.

> ⚠️ **Note: The app is not signed by Apple Developer**
>
> Since there's no Apple Developer account, the app is not code-signed. On first launch, macOS may show "cannot be opened" or "developer cannot be verified".
>
> **Solutions** (choose one):
>
> **Method 1 - Terminal Command (Recommended)**
> ```bash
> xattr -rd com.apple.quarantine /Applications/TransFrame.app
> ```
>
> **Method 2 - System Settings**
> 1. Open "System Settings" → "Privacy & Security"
> 2. Find the notification about TransFrame under "Security"
> 3. Click "Open Anyway"
>
> Either method only needs to be done once, after which the app can be used normally.
Download the latest `TransFrame-<version>.dmg` from the [Releases](../../releases) page and drag TransFrame to Applications.

> ✅ The app is signed with a Developer ID certificate, notarized, and stapled — it opens on first launch without Gatekeeper workarounds. Updates are delivered in-app via Sparkle.

## 🔧 Tech Stack

Expand All @@ -122,6 +108,7 @@ Download the latest version from the [Releases](../../releases) page.
- **ScreenCaptureKit** - System-level screen recording and capture
- **Vision** - Apple native OCR text recognition
- **Translation** - Apple system translation framework
- **Sparkle 2** - Signed, notarized auto-updates
- **CoreGraphics** - Image processing and rendering

## 📁 Project Structure
Expand All @@ -136,92 +123,25 @@ TransFrame/
│ └── HotkeyCoordinator.swift
├── Features/ # Feature modules
│ ├── Capture/ # Screenshot capture
│ ├── Preview/ # Preview and annotation
│ ├── TextTranslation/ # Text translation
│ ├── Overlay/ # Translation overlay
│ ├── BilingualResult/ # Bilingual result display
│ ├── History/ # Translation history
│ ├── Settings/ # Settings UI
│ └── MenuBar/ # Menu bar control
├── Services/ # Business services
│ ├── Protocols/ # Service protocols (dependency injection)
│ ├── OCREngine/ # OCR engines
│ ├── Translation/ # Translation services
│ └── VLMProvider/ # Vision-language models
├── Models/ # Data models
└── Resources/ # Resource files
│ ├── Preview/ # Preview, annotation & results panel
│ ├── TextTranslation/ # Text selection translation & insertion
│ ├── TranslationFlow/ # Translation pipelines
│ ├── Settings/ # Settings UI (engine cards, chain & compare editors)
│ └── MenuBar/ # Menu bar integration
├── Services/ # Business logic
│ ├── Translation/ # Engine registry, providers, ordered/compare dispatch
│ ├── Pipelines/ # Analysis / translation / render pipelines
│ ├── EngineHealthChecker.swift # Real availability probing
│ └── ... # Keychain, hotkeys, text insertion, etc.
├── Models/ # Data models (settings, engine selection V2, results)
├── Resources/ # Assets and 10-language localizations
└── TransFrameTests/ # XCTest suite incl. PRD acceptance tests
```

## 🛠️ Build from Source

```bash
# Clone the repository
git clone https://github.com/hubo1989/TransFrame.git
cd TransFrame

# Open in Xcode
open TransFrame.xcodeproj

# Or build from command line
xcodebuild -project TransFrame.xcodeproj -scheme TransFrame
```

## 📝 Changelog

### v1.0.0 (TransFrame Initial Release)
- 🎉 Rebranded the application from **ScreenTranslate** to **TransFrame**
- ✨ Changed default Bundle Identifier to `com.transframe.app`
- ⚙️ Completely restructured project directories and files to match the new brand
- 🧪 Upgraded unit tests to be fully isolated from local environments

### v1.4.1
- 🐛 Fixed duplicate text segments in VLM responses
- 🐛 Simplified toolbar UI
- 🐛 Fixed CGColorSpace compatibility for older macOS versions
- ✨ Added new annotation tools (shapes, highlighter)
- ✨ Added pinned window feature for annotation mode

### v1.3.0
- ✨ Added About menu with version, license, and acknowledgements
- ✨ Integrated Sparkle auto-update framework
- ✨ Added GitHub Actions CI/CD for automated releases
- 📚 Translated README to English

### v1.2.0
- ✨ Added unified EngineIdentifier for standard and compatible engines
- ✨ Added multi-instance support for OpenAI-compatible engines
- ✨ Optimized engine selection UI and added Gemini support
- ✨ Improved prompt editor UX with copyable variables
- ✨ Improved engine config UX with API key links
- ✨ Moved prompt configuration to dedicated sidebar tab
- ✨ Implemented multi-translation engine support
- 🐛 Fixed quick switch order editing
- 🐛 Improved multi-engine settings interface
- 🌐 Added Chinese localization for multi-engine settings

### v1.1.0
- ✨ Added text selection translation feature
- ✨ Added translate and insert feature
- ✨ Menu bar shortcuts synced with settings
- 🏗️ Architecture refactoring: AppDelegate split into 3 Coordinators
- 🧪 Added unit test coverage
- 🐛 Fixed Retina display issues
- 🐛 Fixed translate-and-insert language settings not applying

### v1.0.2
- 🐛 Deep fix for Retina display scaling issues

### v1.0.1
- 🎉 Initial release

## 🤝 Contributing

Issues and Pull Requests are welcome!
Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## 📄 License

MIT License - See [LICENSE](LICENSE) file for details

---

Made with Swift for macOS
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
Loading
Loading