From 60bb85f829286c3bf846989ef46d49c19cc347eb Mon Sep 17 00:00:00 2001
From: Hubert
Date: Sun, 1 Nov 2026 19:28:00 +0800
Subject: [PATCH] docs: rewrite README for v1.0.4 (signing, engine convergence,
universal build)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Reflects the v1.0.3–v1.0.4 iterations:
- requirements: macOS 15.0+ universal (was 13.0); badges now track the
latest release instead of a hardcoded 1.0.0
- removed the obsolete 'unsigned app' Gatekeeper section — releases are
Developer ID signed, notarized, and stapled since v1.0.2; Sparkle
auto-update mentioned
- multi-engine section rewritten around the two converged modes
(ordered fallback chain / parallel compare), OpenAI-compatible card,
four-state health probing, paid-quota safety, lossless migration,
and the macOS 26 caveat for the Apple engine
- annotation tools updated with smart mosaic/privacy redaction, the
in-place results drawer, and the expanded tool set from v1.0.3
- project structure refreshed to current layout (V2 engine selection,
EngineHealthChecker, results panel)
- language follows the system by default (self-lock fix in v1.0.4)
---
README.md | 158 +++++++++++++--------------------------------------
README_CN.md | 153 ++++++++++++++++---------------------------------
2 files changed, 87 insertions(+), 224 deletions(-)
diff --git a/README.md b/README.md
index 93c24e6..f9d3072 100644
--- a/README.md
+++ b/README.md
@@ -9,9 +9,9 @@
-
+
-
+
@@ -28,9 +28,9 @@
- **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
@@ -38,27 +38,28 @@
- **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
@@ -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-.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
@@ -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
@@ -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.
diff --git a/README_CN.md b/README_CN.md
index 40c38f5..015309b 100644
--- a/README_CN.md
+++ b/README_CN.md
@@ -9,12 +9,16 @@
-
+
-
+
+
+ English
+
+
## ✨ 功能特性
### 截图功能
@@ -24,9 +28,9 @@
- **多显示器支持** - 自动识别并支持多显示器环境
- **Retina 屏幕优化** - 完美支持高分辨率显示器
-### 🆕 文本翻译功能
+### 文本翻译
- **文本选择翻译** - 选中任意文本,一键翻译并弹出结果窗口
-- **翻译并插入** - 选中文本翻译后,自动替换为译文(绕过输入法)
+- **翻译并插入** - 目标复核 + 粘贴兜底,安全地将选中文本替换为译文(绕过输入法)
- **独立语言设置** - 翻译并插入支持独立的目标语言配置
### OCR 文字识别
@@ -34,44 +38,45 @@
- **PaddleOCR** - 可选外部引擎,中文识别更准确
### 多引擎翻译
-两种收敛模式:**顺序退避**(最多 5 个引擎按序尝试,失败自动降级)与**并行对比**(2–4 个引擎同时翻译,逐引擎延迟对比)。
-- **Apple 翻译** - 系统内置,离线可用
-- **MTranServer** - 自建翻译服务器
-- **OpenAI 兼容** - OpenAI 官方 / Ollama 本地 / 自定义端点
+两种收敛模式:**顺序退避**(最多 5 个引擎按序尝试,某引擎失败自动降级到下一个)与**并行对比**(2–4 个引擎同时翻译,按引擎切换查看结果与延迟,切换不重新翻译)。
+- **Apple 翻译** - 系统内置,离线可用(需 macOS 26;旧系统上自动使用链中下一个引擎)
+- **MTranServer** - 自建翻译服务器,高质量翻译
+- **OpenAI 兼容** - 一张卡片覆盖 OpenAI 官方 / Ollama 本地 / 自定义端点(支持无密钥本地端点)
- **Claude / Gemini / Google / DeepL / 百度** - 云翻译 API
-- 真实可用性探测:状态点反映引擎实际可达性
+- **真实可用性探测** - 状态点反映引擎实际可达性(绿/红/橙/灰四态),自动检查绝不消耗付费 API 配额
+- **无损迁移** - 从旧版四模式配置升级,引擎、密钥与选择全部保留
### 标注工具
-- 矩形框选
-- 箭头标注
-- 手绘涂鸦
-- 文字注释
-- 截图裁剪
+- 矩形、椭圆、直线、箭头、手绘、文字标注
+- **智能马赛克 / 隐私擦除** - 一键擦除自动识别的敏感区域
+- **内嵌结果面板** - OCR 文本与双语对照结果停靠在预览窗口内
+- 截图裁剪、撤销重做、⌘ 拖拽约束、文字提交后可拖动
### 其他功能
- **翻译历史** - 保存翻译记录,支持搜索和导出
-- **双语对照** - 原文译文并排显示
-- **覆盖层显示** - 翻译结果直接显示在截图上方
+- **双语对照** - 原文译文并排显示,按视觉行分组
+- **覆盖层显示** - 翻译结果直接渲染在截图上方
+- **自动更新** - 内置 Sparkle 更新通道
- **自定义快捷键** - 支持全局快捷键快速截图和翻译
- **菜单栏快捷操作** - 所有功能均可通过菜单栏访问
-- **多语言支持** - 支持 25+ 种语言翻译
+- **多语言界面** - 界面本地化 10 种语言,默认跟随系统语言
## ⌨️ 快捷键
| 快捷键 | 功能 |
-|--------|------|
+|----------|--------|
| `Cmd+Shift+3` | 全屏截图 |
-| `Cmd+Shift+4` | 区域截图翻译(默认) |
+| `Cmd+Shift+4` | 区域截图(默认) |
| `Cmd+Shift+T` | 翻译模式(截图后直接翻译) |
| `Cmd+Shift+Y` | 文本选择翻译 |
| `Cmd+Shift+I` | 翻译并插入 |
> 所有快捷键均可在设置中自定义
-## 预览窗口操作
+## 预览窗口快捷键
| 快捷键 | 功能 |
-|--------|------|
+|----------|--------|
| `Enter` / `Cmd+S` | 保存截图 |
| `Cmd+C` | 复制到剪贴板 |
| `Escape` | 关闭窗口 / 取消裁剪 |
@@ -85,31 +90,16 @@
## 📦 安装要求
-- macOS 13.0 (Ventura) 或更高版本
+- macOS 15.0 (Sequoia) 或更高版本
+- Universal 双架构二进制:Apple Silicon 与 Intel Mac 均可原生运行
- 屏幕录制权限(首次使用时会提示)
- 辅助功能权限(文本翻译功能需要)
## 下载安装
-从 [Releases](../../releases) 页面下载最新版本。
-
-> ⚠️ **注意:应用未经过 Apple 开发者签名**
->
-> 由于目前没有 Apple Developer 账号,应用未进行代码签名。首次运行时 macOS 会提示「无法打开」或「开发者无法验证」。
->
-> **解决方法**(二选一):
->
-> **方法 1 - 终端命令(推荐)**
-> ```bash
-> xattr -rd com.apple.quarantine /Applications/TransFrame.app
-> ```
->
-> **方法 2 - 系统设置**
-> 1. 打开「系统设置」→「隐私与安全性」
-> 2. 在「安全性」部分找到关于 TransFrame 的提示
-> 3. 点击「仍要打开」
->
-> 两种方法都只需要执行一次,之后可以正常使用。
+从 [Releases](../../releases) 页面下载最新的 `TransFrame-.dmg`,将 TransFrame 拖入「应用程序」即可。
+
+> ✅ 应用已使用 Developer ID 证书签名、公证并 staple——首次打开无需任何 Gatekeeper 绕过操作。更新通过内置 Sparkle 自动送达。
## 🔧 技术栈
@@ -118,6 +108,7 @@
- **ScreenCaptureKit** - 系统级屏幕录制与截图
- **Vision** - Apple 原生 OCR 文字识别
- **Translation** - Apple 系统翻译框架
+- **Sparkle 2** - 签名公证的自动更新
- **CoreGraphics** - 图像处理与渲染
## 📁 项目结构
@@ -131,74 +122,26 @@ TransFrame/
│ ├── TextTranslationCoordinator.swift
│ └── HotkeyCoordinator.swift
├── Features/ # 功能模块
-│ ├── Capture/ # 截图功能
-│ ├── Preview/ # 预览与标注
-│ ├── TextTranslation/ # 文本翻译
-│ ├── Overlay/ # 翻译覆盖层
-│ ├── BilingualResult/ # 双语结果展示
-│ ├── History/ # 历史记录
-│ ├── Settings/ # 设置界面
-│ └── MenuBar/ # 菜单栏控制
-├── Services/ # 业务服务
-│ ├── Protocols/ # 服务协议(依赖注入)
-│ ├── OCREngine/ # OCR 引擎
-│ ├── Translation/ # 翻译服务
-│ └── VLMProvider/ # 视觉语言模型
-├── Models/ # 数据模型
-└── Resources/ # 资源文件
-```
-
-## 🛠️ 构建源码
-
-```bash
-# 克隆仓库
-git clone https://github.com/hubo1989/TransFrame.git
-cd TransFrame
-
-# 用 Xcode 打开
-open TransFrame.xcodeproj
-
-# 或命令行构建
-xcodebuild -project TransFrame.xcodeproj -scheme TransFrame
+│ ├── Capture/ # 截图捕获
+│ ├── Preview/ # 预览、标注与结果面板
+│ ├── TextTranslation/ # 文本选择翻译与插入
+│ ├── TranslationFlow/ # 翻译管线
+│ ├── Settings/ # 设置界面(引擎卡片、链与对比编辑器)
+│ └── MenuBar/ # 菜单栏集成
+├── Services/ # 业务逻辑
+│ ├── Translation/ # 引擎注册表、Provider、顺序/对比分发
+│ ├── Pipelines/ # 分析 / 翻译 / 渲染管线
+│ ├── EngineHealthChecker.swift # 真实可用性探测
+│ └── ... # 钥匙串、快捷键、文本插入等
+├── Models/ # 数据模型(设置、引擎选择 V2、结果)
+├── Resources/ # 资源与 10 语言本地化
+└── TransFrameTests/ # XCTest 测试套件(含 PRD 验收测试)
```
-## 📝 更新日志
-
-### v1.0.0 (TransFrame 首次发布)
-- 🎉 应用品牌从 **ScreenTranslate** 彻底更名为 **TransFrame**
-- ✨ 默认 Bundle Identifier 变更为 `com.transframe.app`
-- ⚙️ 全面重构并重命名了项目目录、文件和底层配置,以适配新品牌名称
-- 🧪 升级并重构单元测试,实现完全的环境独立性验证
-
-### v1.3.0
-- ✨ 新增关于菜单(版本、许可证、致谢)
-- ✨ 集成 Sparkle 自动更新框架
-- ✨ 添加 GitHub Actions CI/CD 自动发布
-- 📚 README 翻译为英文
-
-### v1.1.0
-- ✨ 新增文本选择翻译功能(选中任意文本一键翻译)
-- ✨ 新增翻译并插入功能(自动替换选中文本为译文)
-- ✨ 菜单栏快捷键与设置同步
-- 🏗️ 架构重构:AppDelegate 拆分为 3 个 Coordinator
-- 🧪 添加单元测试覆盖
-- 🐛 修复 Retina 屏幕显示问题
-- 🐛 修复翻译并插入语言设置不生效问题
-
-### v1.0.2
-- 🐛 深度修复 Retina 屏幕缩放问题
-
-### v1.0.1
-- 🎉 首次发布
-
## 🤝 贡献指南
-欢迎提交 Issue 和 Pull Request。
+欢迎贡献!请先阅读 [CONTRIBUTING.md](CONTRIBUTING.md)。
## 📄 许可证
-MIT License - 详见 [LICENSE](LICENSE) 文件
-
----
-
-Made with Swift for macOS
+本项目基于 MIT 许可证开源,详见 [LICENSE](LICENSE) 文件。