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
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ All notable changes are documented here. Versions follow Semantic Versioning.
### Added

- macOS desktop shell with global selection translation shortcut.
- A desktop setting to disable or customize the selection translation shortcut, defaulting to `Option + K`.
- GitHub pull request, CI, security scanning, dependency updates, and beta release workflows.
- Automated API and browser smoke coverage.

Expand Down
10 changes: 5 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,8 +13,8 @@

## 功能

- macOS 中选中文字后按 `⌥ + T`,打开客户端并立即翻译
- 自动、Ollama 本地模型、OpenAI 兼容 API、极速词典四种引擎
- macOS 中选中文字后按默认快捷键 `⌥ + K`,打开客户端并立即翻译;可在设置中关闭或修改
- 自动、Ollama、OpenAI 兼容 API、极速词典四种引擎
- 整段中文译文与逐词、数字、标点对齐结果
- TXT、Markdown、DOCX、PDF 文本提取
- 桌面与手机响应式 Web 界面
Expand All @@ -41,7 +41,7 @@ npm ci
npm run tauri dev
```

全局划词需要在“系统设置 → 隐私与安全性 → 辅助功能”中允许逐词。客户端会优先通过 macOS Accessibility API 读取选区;不支持该属性的应用会使用保留剪贴板内容的复制回退
全局划词需要在“系统设置 → 隐私与安全性 → 辅助功能”中允许逐词。客户端会优先通过 macOS Accessibility API 读取选区;不支持该属性的应用会使用复制回退,尝试恢复原来的文本剪贴板,并可能请求“自动化 → System Events”权限。关闭选区快捷键只会取消全局快捷键注册,不会撤销已经授予的系统权限

生成本地 `.app`:

Expand All @@ -52,7 +52,7 @@ npm run desktop:build:app
## 翻译引擎

- `自动选择`:优先使用可用的 Ollama;未检测到本地模型时使用已配置的云端 API。两者都不可用时会提示配置,不会把基础词典冒充成语境翻译。
- `Ollama 本地`:内容不离开电脑,建议使用 `qwen3:4b` 或更大的 Qwen 模型。
- `Ollama`:默认连接本机服务,建议使用 `qwen3:4b` 或更大的 Qwen 模型;改为远程地址时,内容会发送到该服务
- `云端模型`:支持 OpenAI 及兼容 `/chat/completions` 的 API。
- `极速词典`:完全离线、即时返回,只用于逐词查义,不提供可靠的整句语境翻译。

Expand All @@ -71,7 +71,7 @@ OPENAI_BASE_URL=https://api.openai.com/v1 \
OPENAI_API_KEY=... OPENAI_MODEL=gpt-5-mini npm run dev
```

API Key 不会写入浏览器存储。公共云端凭据不得编译到前端或桌面安装包中。
API Key 不会写入浏览器存储。使用云端模型或远程 Ollama 地址时,选中文字、手动输入内容或提取出的文档文字会发送给用户配置的服务;使用默认本机 Ollama 地址或极速词典时不会发送到云端。公共云端凭据不得编译到前端或桌面安装包中。
Web 服务只会请求上述服务端环境变量配置的模型地址,页面中地址为只读;这可防止浏览器借用本地 API 访问其他内网服务。macOS 客户端直接在本机发起模型请求,仍允许用户在设置中修改兼容 API 地址。

## 质量门禁
Expand Down
11 changes: 6 additions & 5 deletions docs/building-en.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,9 +49,9 @@ Start the desktop app:
npm run tauri dev
```

Wordwise opens as a native desktop window. Select English in another macOS app and press `Option + T` to capture it.
Wordwise opens as a native desktop window. Select English in another macOS app and press the default `Option + K` shortcut to capture it. You can disable selection translation or record another key combination in Settings.

The first selection capture requires permission in **System Settings -> Privacy & Security -> Accessibility**. Wordwise first tries the macOS Accessibility API. When an app does not expose its selection there, Wordwise uses a copy fallback and restores the previous clipboard contents.
The first selection capture requires permission in **System Settings -> Privacy & Security -> Accessibility**. Wordwise first tries the macOS Accessibility API. When an app does not expose its selection there, Wordwise uses a copy fallback, attempts to restore the previous text clipboard, and may also request permission under **Automation -> System Events**. Disabling the shortcut only unregisters the global shortcut; remove Wordwise in macOS System Settings to revoke the permissions themselves.

## Configure a translation engine

Expand All @@ -66,15 +66,16 @@ Local mode needs no API key. Install and start Ollama from the [macOS download p
ollama pull qwen3:4b
```

Return to Wordwise and keep **Automatic** selected, or choose **Local Ollama**. Select `What's under the hood?` in any app and press `Option + T`. A successful first run shows a full Chinese translation, token-aligned results, and the `Ollama · qwen3:4b` engine label.
Return to Wordwise and keep `自动选择` selected, or choose `Ollama`. Select `What's under the hood?` in an app that supports text selection or copying, then press the default `Option + K` shortcut. A successful first run shows a full Chinese translation, token-aligned results, and the `Ollama · qwen3:4b` engine label.

Automatic mode uses an available Ollama model first, then a configured cloud API. It reports a setup error when neither is available. The offline dictionary is an explicit word-lookup mode and is not presented as contextual sentence translation.

API keys remain in application memory and are not written to browser storage or committed to the repository. Never include keys, selected text, or private documents in a public GitHub issue.
API keys remain in application memory and are not written to browser storage or committed to the repository. With a cloud model or remote Ollama URL, selected text, manual input, and extracted document text are sent to the configured service; the default localhost Ollama URL and dictionary mode do not send that content to the cloud. Never include keys, selected text, or private documents in a public GitHub issue.

## Common blockers

- The shortcut cannot read the selection: check Wordwise under **System Settings -> Privacy & Security -> Accessibility**, then restart the development app.
- The shortcut does not respond: confirm that selection translation is enabled in Settings and that another app has not reserved the key combination.
- The shortcut cannot read the selection: check Wordwise under **System Settings -> Privacy & Security -> Accessibility**. The copy fallback also needs Wordwise to control System Events under **Automation**. Restart the development app after changing either permission.
- Automatic mode reports that no engine is configured: make sure Ollama is running and use `ollama list` to confirm that the model was downloaded.
- A development port is already in use: stop the existing Wordwise development process and try again.

Expand Down
11 changes: 6 additions & 5 deletions docs/building.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,9 +49,9 @@ npm ci
npm run tauri dev
```

逐词会以原生桌面窗口打开。在其他 macOS 应用中选中英文,按下 `Option + T` 即可读取选区。
逐词会以原生桌面窗口打开。在其他 macOS 应用中选中英文,按下默认快捷键 `Option + K` 即可读取选区。可以在设置中关闭选区快捷键,或录入新的组合键

第一次划词时,需要在“系统设置 -> 隐私与安全性 -> 辅助功能”中允许逐词。客户端会优先使用 macOS Accessibility API;应用没有暴露选区时,才会使用复制回退,并在读取后恢复原来的剪贴板内容
第一次划词时,需要在“系统设置 -> 隐私与安全性 -> 辅助功能”中允许逐词。客户端会优先使用 macOS Accessibility API;应用没有暴露选区时,才会使用复制回退,尝试恢复原来的文本剪贴板,并可能要求在“自动化”中允许逐词控制 System Events。关闭选区快捷键只会取消全局快捷键注册;如需撤销读取权限,请在 macOS 系统设置中移除逐词

## 配置翻译引擎

Expand All @@ -66,15 +66,16 @@ npm run tauri dev
ollama pull qwen3:4b
```

回到逐词,保留“自动选择”或选择“Ollama 本地”。在任意应用中选中 `What's under the hood?`,按下 `Option + T`。首次成功时应同时看到完整中文译文、逐词结果,以及 `Ollama · qwen3:4b` 引擎标签。
回到逐词,保留“自动选择”或选择“Ollama”。在支持文本选择或复制的应用中选中 `What's under the hood?`,按下默认快捷键 `Option + K`。首次成功时应同时看到完整中文译文、逐词结果,以及 `Ollama · qwen3:4b` 引擎标签。

自动模式会先使用可用的 Ollama,再使用已配置的云端 API。两者都不可用时,客户端会提示配置。离线词典是单独的查词模式,不会被冒充成语境整句翻译。

API Key 只保存在应用运行内存中,不会写入浏览器存储或提交到仓库。不要在公开 GitHub Issue 中提交 API Key、选中文字或私有文档。
API Key 只保存在应用运行内存中,不会写入浏览器存储或提交到仓库。选择云端模型或远程 Ollama 地址时,选中文字、手动输入内容或提取出的文档文字会发送给所配置的服务;使用默认本机 Ollama 地址或极速词典时不会发送到云端。不要在公开 GitHub Issue 中提交 API Key、选中文字或私有文档。

## 常见阻塞

- 快捷键没有读到选区:检查“系统设置 -> 隐私与安全性 -> 辅助功能”中的逐词权限,然后重新启动开发客户端。
- 快捷键没有响应:确认设置中的选区快捷键已启用且没有被其他应用占用。
- 快捷键没有读到选区:检查“系统设置 -> 隐私与安全性”中逐词的“辅助功能”权限;复制回退还需要在“自动化”中允许逐词控制 System Events。修改后重新启动开发客户端。
- 自动模式提示没有引擎:确认 Ollama 应用正在运行,并用 `ollama list` 检查模型是否已经下载。
- 端口被占用:退出已有的逐词开发进程后重试。

Expand Down
4 changes: 2 additions & 2 deletions site/en/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@
<p class="availability"><span></span>Source build available · Up to 15 signed-beta waitlist spots</p>
<h1 id="hero-title">Wordwise</h1>
<p class="hero-line">Read technical English without losing the words.</p>
<p class="hero-detail">Select text in any macOS app and press <kbd>⌥ T</kbd> to see a full Chinese translation and context-aware explanations for every word, number, and punctuation mark.</p>
<p class="hero-detail">Select text in most macOS apps and press the default <kbd>⌥ K</kbd> shortcut to see a full Chinese translation and context-aware explanations. The shortcut can be disabled or changed.</p>
<div class="hero-actions">
<a class="primary-action" href="https://github.com/fly1d/wordwise/blob/main/docs/building-en.md">Build from source now</a>
<a class="secondary-action" data-waitlist-link href="https://tally.so/r/PdZ9ze?source=product-page&amp;language=en">Join the signed-beta waitlist</a>
Expand Down Expand Up @@ -106,7 +106,7 @@ <h2>The signed build is not ready. Validate the source build first.</h2>
<aside class="privacy-note">
<span>Privacy boundary</span>
<h3>We do not need to see what you translate.</h3>
<p>The private waitlist form collects the qualification and contact details needed for the beta plus coarse source and landing-page language metadata, never selected text, documents, API keys, or full model requests. Local-model content stays on your Mac; cloud mode sends content only to the provider you choose.</p>
<p>The private waitlist form collects the qualification and contact details needed for the beta plus coarse source and landing-page language metadata, never selected text, documents, API keys, or full model requests. On-device model content stays on your Mac; a remote Ollama URL or cloud model sends content only to the service you choose.</p>
<a href="https://github.com/fly1d/wordwise/blob/main/docs/validation.md">Read the public validation rules</a>
</aside>
</section>
Expand Down
4 changes: 2 additions & 2 deletions site/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@
<p class="availability"><span></span>源码版可用 · 最多 15 个签名版候补名额</p>
<h1 id="hero-title">逐词 Wordwise</h1>
<p class="hero-line">读技术英文,不只得到一句中文。</p>
<p class="hero-detail">在 macOS 里选中文字,按下 <kbd>⌥ T</kbd>,同时查看完整译文与逐词语境解释。固定短语、冠词和标点都保持对齐。</p>
<p class="hero-detail">在 macOS 里选中文字,按下默认快捷键 <kbd>⌥ K</kbd>,同时查看完整译文与逐词语境解释。快捷键可关闭或修改。</p>
<div class="hero-actions">
<a class="primary-action" href="https://github.com/fly1d/wordwise/blob/main/docs/building.md">立即从源码试用</a>
<a class="secondary-action" data-waitlist-link href="https://tally.so/r/PdZ9ze?source=product-page&amp;language=zh">加入签名版候补</a>
Expand Down Expand Up @@ -106,7 +106,7 @@ <h2>签名版未就绪,先从源码验证价值。</h2>
<aside class="privacy-note">
<span>隐私边界</span>
<h3>我们不需要看到你翻译了什么。</h3>
<p>私密候补表单收集资格判断和联系所需的信息,以及粗粒度来源和落地页语言元数据;不收集选中文字、文档、API Key 或完整模型请求。本地模型内容留在电脑;云端模式只发送给你选择的模型服务。</p>
<p>私密候补表单收集资格判断和联系所需的信息,以及粗粒度来源和落地页语言元数据;不收集选中文字、文档、API Key 或完整模型请求。使用本机模型时内容留在电脑;配置远程 Ollama 或云端模型时,内容只发送给你选择的服务。</p>
<a href="https://github.com/fly1d/wordwise/blob/main/docs/validation.md">查看公开验证规则</a>
</aside>
</section>
Expand Down
2 changes: 1 addition & 1 deletion src-tauri/src/selection.rs
Original file line number Diff line number Diff line change
Expand Up @@ -102,7 +102,7 @@ end try

if !output.status.success() {
return Err(
"无法读取选中文字。请在“系统设置 → 隐私与安全性 → 辅助功能”中允许逐词。".into(),
"无法通过复制读取选中文字。请在“系统设置 → 隐私与安全性”中检查逐词的“辅助功能”和“自动化System Events”权限。".into(),
);
}

Expand Down
Loading