{"id":48501607,"url":"https://github.com/lianye-scythe/ocrtranslator","last_synced_at":"2026-04-20T13:01:31.948Z","repository":{"id":349392300,"uuid":"1198491059","full_name":"Lianye-Scythe/OCRTranslator","owner":"Lianye-Scythe","description":"Portable Windows OCR / AI desktop tool with screenshot, selected-text, and manual-input workflows.","archived":false,"fork":false,"pushed_at":"2026-04-07T13:39:22.000Z","size":9300,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-07T15:33:25.278Z","etag":null,"topics":["ai","desktop-app","gemini-compatible","ocr","openai-compatible","productivity","pyside6","python","reading-tool","screenshot","translation","windows"],"latest_commit_sha":null,"homepage":"https://github.com/Lianye-Scythe/OCRTranslator/releases","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Lianye-Scythe.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":"SUPPORT.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":null,"patreon":null,"open_collective":null,"ko_fi":"lianye","tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":null,"thanks_dev":null,"custom":null}},"created_at":"2026-04-01T13:26:18.000Z","updated_at":"2026-04-07T13:39:29.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Lianye-Scythe/OCRTranslator","commit_stats":null,"previous_names":["lianye-scythe/ocrtranslator"],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/Lianye-Scythe/OCRTranslator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Lianye-Scythe%2FOCRTranslator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Lianye-Scythe%2FOCRTranslator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Lianye-Scythe%2FOCRTranslator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Lianye-Scythe%2FOCRTranslator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Lianye-Scythe","download_url":"https://codeload.github.com/Lianye-Scythe/OCRTranslator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Lianye-Scythe%2FOCRTranslator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32048444,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-20T11:35:06.609Z","status":"ssl_error","status_checked_at":"2026-04-20T11:34:48.899Z","response_time":94,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","desktop-app","gemini-compatible","ocr","openai-compatible","productivity","pyside6","python","reading-tool","screenshot","translation","windows"],"created_at":"2026-04-07T15:00:44.418Z","updated_at":"2026-04-20T13:01:31.942Z","avatar_url":"https://github.com/Lianye-Scythe.png","language":"Python","funding_links":["https://ko-fi.com/lianye"],"categories":[],"sub_categories":[],"readme":"# OCRTranslator\n\n繁體中文｜[简体中文](docs/README.zh-CN.md)｜[English](docs/README.en.md)\n\n[![CI](https://github.com/Lianye-Scythe/OCRTranslator/actions/workflows/ci.yml/badge.svg)](https://github.com/Lianye-Scythe/OCRTranslator/actions/workflows/ci.yml)\n[![Platform](https://img.shields.io/badge/platform-Windows-0078D6)](docs/packaging.md)\n[![Release](https://img.shields.io/badge/release-v1.0.10-2563EB)](https://github.com/Lianye-Scythe/OCRTranslator/releases)\n[![License](https://img.shields.io/badge/license-GPLv3-4F46E5)](LICENSE)\n\nOCRTranslator 是一款以 **桌面即時閱讀** 為核心的 **便攜式 OCR / AI 請求工具**。\n\n它不是單純的截圖翻譯器，而是一個圍繞三種入口打造的桌面 AI 工作台：\n\n1. **螢幕框選**：把截圖交給多模態模型做 OCR / 翻譯 / 解答 / 潤色\n2. **選取文字**：擷取目前選取的文字，直接走文字請求\n3. **手動輸入**：打開輸入框，把一段內容直接送給 AI\n\n## 介面預覽\n\n如果你想先快速掌握產品外觀，可以先看目前主視窗與翻譯浮窗的實際效果，再往下看功能總覽。\n\n### 動態預覽\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/images/screenshots/ocrtranslator-preview.gif\" width=\"88%\" alt=\"OCRTranslator 動態預覽\" /\u003e\n\u003c/p\u003e\n\n### 靜態截圖\n\n#### 主視窗\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/images/screenshots/main-window-light.png\" width=\"49%\" alt=\"淺色主題主視窗\" /\u003e\n  \u003cimg src=\"docs/images/screenshots/main-window-dark.png\" width=\"49%\" alt=\"深色主題主視窗\" /\u003e\n\u003c/p\u003e\n\n#### 翻譯浮窗\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/images/screenshots/overlay-light-manga.png\" width=\"49%\" alt=\"淺色主題翻譯浮窗（漫畫）\" /\u003e\n  \u003cimg src=\"docs/images/screenshots/overlay-light-novel.png\" width=\"49%\" alt=\"淺色主題翻譯浮窗（小說）\" /\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/images/screenshots/overlay-dark-novel.png\" width=\"49%\" alt=\"深色主題翻譯浮窗（小說）\" /\u003e\n  \u003cimg src=\"docs/images/screenshots/overlay-dark-manga.png\" width=\"49%\" alt=\"深色主題翻譯浮窗（漫畫）\" /\u003e\n\u003c/p\u003e\n\n## 特色總覽\n\n- 支援 **截圖 / 選取文字 / 手動輸入** 三種請求入口\n- 支援 **Prompt Preset** 方案系統，內建 `翻譯 (Translate)`、`解答 (Answer)`、`潤色 (Polish)`、`OCR 原文 (Raw OCR)` 四組預設方案\n- 支援多個 API Profile，可接入 `Gemini Compatible` / `OpenAI Compatible`\n- 支援多 Key 輪替、失敗重試與模型切換\n- 流式回應預設啟用，可在進階設定中關閉；`Test API` 也會沿用相同模式驗證實際後端行為\n- 手動輸入視窗現在可為單次請求單獨指定目標語言，支援常用語言建議，且會記住上一次手動輸入使用的語言\n- 第三方 Compatible 後端若不支援流式，會提示目前狀態並自動回退為非流式；流式中斷時也會保留部分結果與狀態標記\n- 設定頁採用「連線與模型 → 翻譯方式與快捷鍵 → 介面與進階」三段式流程，較容易完成首次配置\n- 應用內選取文字現在會優先直接讀取目前焦點控件的文字選區；若沒有可用的應用內選字，才回退到原本的系統剪貼簿擷取路徑\n- 螢幕框選現在會先凍結桌面快照再裁切選區，降低高 DPI / 多螢幕偏移、hover 新 UI 混入與主視窗殘影\n- 每次截圖都會重建新的選取遮罩，降低 Windows 上偶發閃出上一張截圖背景的機率\n- 設定頁中的 `Fetch Models` / `Test API` / `Save Settings` 等動作按鈕已補上更穩定的焦點處理，避免 busy 狀態切換時把頁面自動捲到底\n- 左右模式下的結果浮窗現在會更準確地量測標題與工具列寬度，首次顯示時更不容易壓到選區\n- 流式圖片翻譯的浮窗更新策略已進一步穩定：首次 partial 會先根據選區可用空間預估寬度，降低冷啟動第一次截圖時的橫向跳位，持續更新時也會盡量避免靠近底部時的抖動\n- 請求流程盡量維持非阻塞，並以應用內短時氣泡 / 系統匣通知回饋目前狀態\n- 結果浮窗支援：\n  - 複製、圖釘固定 / 取消固定\n  - 只調整表面背景的透明度（文字保持清晰）\n  - 直接輸入透明度百分比\n  - 拖曳移動與角落拖曳改尺寸\n  - `Ctrl + 滑鼠滾輪` 縮放字體\n- 已 Pin 的結果浮窗可保留位置與尺寸；未 Pin 狀態則會根據當前場景動態展開，手動調整的寬度只在本次執行期間保留，不會跨重啟寫回設定檔\n- 內建 `翻譯 (Translate)` 預設方案已更新為更中性的 OCR / 翻譯提示詞，若後端安全規則僅攔截局部內容，會以 `[REDACTED]` 替換觸發片段並盡量完成其餘翻譯\n- 支援 `淺色 / 深色 / 跟隨系統` 三態主題切換\n- 支援全域快捷鍵、系統匣、單實例喚回與 `--capture` 快速啟動\n- 進階設定新增可切換的除錯 Log；預設只保留一般使用者可理解的執行紀錄，開啟後才會額外顯示定位診斷、截圖規劃與 API 底層重試細節\n- 提供版本化 ZIP 發佈、`SHA256SUMS.txt` 校驗與完整三語文件\n\n## 發佈與信任資訊\n\n- 官方桌面發佈以 GitHub Releases 的版本化 ZIP 為準：`OCRTranslator-v\u003cversion\u003e-windows-x64.zip`\n- 推送 `v*` annotated tag 後，GitHub Actions 會自動建置 Release，並優先沿用 tag annotation 作為 Release 正文\n- 目前公開 Windows 發佈包 **尚未簽名**；倉庫已預留 SignPath / Trusted Build 整合，後續計畫導入正式簽名流程\n- 公開 Release 不會額外上傳獨立 `.exe`，而是只提供版本化 ZIP 與 GitHub 自帶 source archives\n- Release 也會額外附上 `SHA256SUMS.txt`，方便手動校驗下載的 ZIP 檔案\n- 若要私下回報敏感安全問題，請寄信到 `po12017po@gmail.com`\n\n## 預設快捷鍵\n\n當 `config.json` 不存在或欄位缺失時，預設快捷鍵如下：\n\n| 動作 | 預設快捷鍵 |\n|---|---|\n| 螢幕框選 | `Shift + Win + X` |\n| 選取文字 | `Shift + Win + C` |\n| 手動輸入 | `Shift + Win + Z` |\n\n\u003e 實際使用時仍以你的 `config.json` 為準。\n\n## 快速開始\n\n### 1. 安裝依賴\n\n```bash\npython -m venv .venv\n.venv\\Scripts\\activate\npip install -r requirements.txt\n```\n\n如果你還需要打包或維護開發工具：\n\n```bash\npip install -r requirements-dev.txt\n```\n\n### 2. 啟動應用\n\n#### 方式 A：推薦雙擊啟動\n\n直接執行：\n\n- `start.bat`\n\n它會自動：\n\n1. 檢查 `.venv`\n2. 按需安裝執行依賴\n3. 透過 `launcher.pyw` 啟動 GUI\n4. 啟動期若出錯，優先顯示錯誤對話框\n\n#### 方式 B：命令列啟動\n\n```bash\npython launcher.pyw\n```\n\n或：\n\n```bash\npython -m app.main\n```\n\n#### 方式 C：要求既有實例直接進入截圖\n\n```bash\npython -m app.main --capture\n```\n\n支援參數：\n\n- `--capture`\n- `/capture`\n- `capture`\n\n## 使用流程\n\n### 1. 先完成目前設定檔的連線與模型測試\n\n設定頁現在會優先引導你完成「連線與模型」區塊，至少需填寫：\n\n- Provider\n- Base URL\n- API Keys\n- Model\n\n建議順序：\n\n1. 選擇或新增一個 API Profile\n2. `Fetch Models`\n3. `Test API`\n4. `Save Settings`\n\n等連線完成後，再視需求補上：\n\n- Target Language\n- Global Hotkeys\n- Prompt Preset\n- Overlay 偏好\n- Theme / UI Language\n\n### 2. 從三種入口發起請求\n\n你可以透過這些入口觸發：\n\n- 主畫面的 `Start Capture`\n- 主畫面的 `Open Input Box`\n- 選取文字快捷鍵\n- 托盤選單中的截圖 / 輸入框入口\n- 手動輸入對話框可直接覆寫本次請求的目標語言；若主設定欄位暫時留白，也能先打開輸入框後再填寫\n- 對應的全域快捷鍵\n- 選取文字快捷鍵在擷取期間不會再同步卡住主視窗；若擷取尚未完成，也可用 `取消目前操作` 中止\n- `--capture` 啟動參數\n\n### 3. 查看結果\n\n- 截圖流程會在 `Preview \u0026 Log` 頁面顯示最近一次預覽\n- 結果會以浮窗形式顯示在原文附近或觸發點附近\n- 近期版本的圖片請求日誌會額外輸出 PNG 大小與 `capture / request / total` 耗時，方便確認性能瓶頸\n- 執行過程會寫入記憶體日誌，可在介面中查看或匯出\n\n## Prompt Preset\n\n每組方案都包含：\n\n- `image_prompt`\n- `text_prompt`\n\n支援變數：\n\n- `{target_language}`\n\n文字模式會把正文自動附加到提示詞後方，因此你只需要維護「指令部分」。\n\n### 內建方案\n\n| 方案 | 用途 |\n|---|---|\n| `翻譯 (Translate)` | 把圖片或文字翻譯成目標語言 |\n| `解答 (Answer)` | 對題目、問題、說明直接作答或解釋 |\n| `潤色 (Polish)` | 把文字改寫成更自然流暢的目標語言 |\n| `OCR 原文 (Raw OCR)` | 只回傳 OCR 原文，不翻譯、不潤色 |\n\n\u003e 內建方案不可直接刪除；若要做可刪除版本，建議先複製成自訂方案。\n\n## 設定檔\n\n預設會優先使用便攜設定檔 `config.json`。\n\n路徑解析規則：\n\n- 原始碼模式：若專案根目錄已有 `config.json`，就沿用它；若根目錄可寫且尚未存在設定檔，也會直接在根目錄建立\n- 打包 exe：若 exe 同層已有 `config.json`，就沿用它；若 exe 目錄可寫且尚未存在設定檔，也會直接在 exe 同層建立\n- 若便攜位置沒有設定檔，且當前執行目錄不可寫，則自動回退到使用者設定目錄：\n  - Windows：`%LOCALAPPDATA%\\OCRTranslator\\config.json`\n  - 其他環境 fallback：`~/.ocrtranslator/config.json`\n\n只要便攜設定檔存在，就會優先使用便攜路徑。\n\n主要保存內容：\n\n- Target Language / UI Language\n- Theme Mode\n- 三組全域快捷鍵\n- 手動輸入最近一次使用的目標語言\n- Overlay 字型 / 字級 / 透明度 / Pin / 預設尺寸 / Pin 幾何\n- 是否按 X 最小化到系統匣\n- 目前啟用的 API Profile\n- 目前啟用的 Prompt Preset\n- 所有 Profiles / Presets\n\n參考範例：\n\n- `config.example.json`\n\n\u003e `config.json` 可能包含 API Keys 與私有 Base URL，請勿直接分享。\n\u003e crash log 仍會優先寫回專案根目錄或 exe 同層，不跟著 fallback 設定檔路徑移動。\n\n## 托盤、單實例與錯誤處理\n\n### 單實例\n\n應用會用鎖檔與本地 server 保證單實例。\n\n重複啟動時：\n\n- 普通啟動：喚回既有主視窗\n- `--capture`：喚回既有實例並直接開始截圖\n\n### 托盤\n\n托盤選單提供：\n\n- 顯示主視窗\n- 開始截圖\n- 開啟輸入框\n- 取消目前操作\n- 退出程式\n\n\u003e 「選取文字」流程更適合透過全域快捷鍵觸發。\n\u003e 因為一旦從主視窗或托盤點擊，焦點通常會被本程式搶走，反而破壞外部應用原本的選取狀態。\n\n預設情況下，右上角 `X` 會直接退出程式。\n若希望 `X` 改成最小化到系統匣，可在設定頁啟用對應選項。\n\n### 日誌與 Crash Log\n\n- 執行日誌預設只保存在記憶體中\n- 最多保留最近 100 筆\n- 可從介面匯出\n\n若程式遇到未處理例外，會在根目錄或 exe 同層生成：\n\n```text\nocrtranslator-crash-YYYYMMDD-HHMMSS-xxxxxxxxx.log\n```\n\n## 測試與檢查\n\n執行測試：\n\n```bash\npython -m unittest discover -v\n```\n\n基本編譯檢查：\n\n```bash\npython -m compileall app tests launcher.pyw\n```\n\n## 文件導覽\n\n- [文件總覽](docs/index.md)\n- [架構說明](docs/architecture.md)\n- [開發指南](docs/development.md)\n- [打包與發佈](docs/packaging.md)\n- [常見問題 FAQ](docs/FAQ.md)\n- [Code of Conduct](CODE_OF_CONDUCT.md)\n- [Support](SUPPORT.md)\n- [貢獻指南](CONTRIBUTING.md)\n- [安全性回報](SECURITY.md)\n- [變更記錄](CHANGELOG.md)\n\n## 已知邊界\n\n- 辨識與輸出品質高度依賴所接入的多模態模型\n- 目前不內建離線 OCR 引擎\n- 選取文字流程採用「模擬複製並盡量還原剪貼簿」策略，少數應用可能不響應標準複製行為\n- 工程與啟動腳本主要面向 Windows 使用情境\n- 浮窗定位以「盡量不遮擋閱讀」為優先，而非嚴格排版系統\n- 執行日誌預設不做長期審計保存\n\n## 授權條款\n\n- 本專案採用 **GNU General Public License v3.0（GPLv3）** 發佈\n- 詳細條款請見根目錄的 `LICENSE`\n- 若你修改後再對外分發衍生版本，請一併提供對應原始碼並維持 GPLv3 授權\n\n對外提交 Pull Request、補丁或其他程式碼貢獻時，預設也會以 GPLv3 納入本專案。\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flianye-scythe%2Focrtranslator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flianye-scythe%2Focrtranslator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flianye-scythe%2Focrtranslator/lists"}