Easydict Documentation

Technical Documentation: tisfeng/Easydict

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (README.md) Copy Section

Easydict Copy Chapter

Easydict is a concise and easy-to-use translation dictionary macOS App that allows you to easily and elegantly look up words or translate text.

Easydict is ready to use out of the box, can automatically recognize the language of the input text, supports input translate, select translate, and OCR screenshot translate, and can query multiple translation services results at the same time.

Supported services: 20+ dictionary, translation, AI, local-model, and CLI services, including
Apple Dictionary, MDict, Apple Translate, OpenAI, Gemini, Claude, DeepSeek, Ollama, Claude Code,
Codex CLI, DeepL, Google, and Bing. See the services overview for
the complete list and access requirements.

Features Copy Chapter

• 🚀 Out of the box, automatic language recognition
• 🖱️ Auto select with mouse and shortcut key
• 📸 OCR screenshot translation and silent screenshot OCR
• 🔊 Multiple TTS voice services
• 📚 Support 🍎 Apple Dictionary and Apple Translate
• 🌐 Support 20+ dictionary, translation, AI, local-model, and CLI services
• 🗣️ Support 52 selectable translation languages

If you like this app, please consider giving it a Star ⭐️, thanks! (^-^)

Contributing Copy Chapter

Contributions through issues and pull requests are welcome. Read the Chinese
contribution guide for the development workflow and pull
request requirements.

AI Coding Copy Section

We welcome contributions assisted by programming agents such as Codex and
Claude. Prefer the latest available GPT or Claude model suitable for complex
coding tasks, and carefully review and test the final changes. See the Chinese
contribution guide for the Agent workflow and
review requirements.

Issue/PR Triage Notes Copy Chapter

The maintainer has been quite busy recently and usually only has time to triage issues on weekends. PRs (especially bugfix PRs) are prioritized. Also, due to an overloaded inbox and notifications, some messages may not be seen or replied to promptly. Thanks for your understanding.

Installation Copy Chapter

Homebrew Installation (Recommended) Copy Section

brew install --cask easydict

Manual Installation Copy Section

Download the latest release.

[!NOTE]
Latest version supports macOS 13.0+, for older systems please use 2.7.2

Usage Copy Chapter

Documentation Copy Chapter

• 📖 Complete Usage Guide - Detailed features, configuration and tips
• 🌐 Services Overview - Complete service list and access requirements
• 🔧 Developer Build Guide - Build and run from source code
• 🍎 How to use Apple Dictionary
• 📚 How to use MDict
• 🍎 How to use Apple Translate
• 🌍 How to translate Easydict

Acknowledgements Copy Chapter

• This project was inspired by saladict and Bob, and the initial version was made based on Bob (GPL-3.0). Easydict has made many improvements and optimizations on the original project, and many features and UI are referenced from Bob.
• Screenshot feature is based on isee15's Capture-Screen-For-Multi-Screens-On-Mac, and optimized on this project.
• Select text feature is referenced from PopClip.

Statement Copy Chapter

Easydict is licensed under the GPL-3.0 open source license, which is for learning and communication only. Anyone can get this product and source code for free. If you believe that your legal rights have been violated, please contact the author immediately. You can use the source code freely, but you must attach the corresponding license and copyright.

Sponsor Copy Chapter

Easydict is a free and open source project, currently mainly developed and maintained by the author. If you like this project and find it helpful, you can consider sponsoring this project to support it, so that it can go further.

Thanks to @CanglongCl for providing the Apple Developer account, which solved the app signature issue, allowing more people to use Easydict conveniently.

Thanks to all sponsors for their generous support. For details, please see the Sponsor List.

Star History Copy Chapter

References README (`docs/references/README.md`) Copy Section

Agent 规则参考

本目录保存长期使用的外部来源证据。参考资料只提供证据，不定义 Easydict 的执行规则；
Skills 的来源基线与同步命令由 docs/agents/skills.md 统一维护。

当前参考 Copy Chapter

• astra-agent-guidance.md：保留 Astra 指令适配的历史来源。

Histories README (`docs/histories/README.md`) Copy Section

变更历史

本目录保存执行模式下最终产生仓库文件差异的任务记录：

• YYYY-MM/：按完成月份归档的历史记录。
• template.md：新记录模板。

创建与归档 Copy Chapter

• 执行任务产生仓库差异时，在 YYYY-MM/ 使用 template.md 记录结果；
  没有差异时不创建空记录。
• 新记录从当前模板创建，保留模板中的必填字段、章节和顺序。

命名与 slug Copy Chapter

• 记录与计划共用 YYYY-MM-DD-<slug>.md 文件名，同一任务共享 slug 并跨轮复用。
• <slug> 使用小写 kebab-case；其中完整的标准标识可保留点号（如 release-0.1.1、
  upgrade-skills-v0.3.8）。不使用空格、下划线、大写字母、斜杠、反斜杠或冒号。

内容与交付 Copy Chapter

• history 记录已落地结果与关键决策，不复制完整对话。
• 存在 plan 时，history 链接归档后的 plan。
• 计划的创建时机、生命周期和内容要求见
  ../exec-plans/README.md。

Exec Plans README (`docs/exec-plans/README.md`) Copy Section

执行计划

本目录保存执行模式下的多步骤、跨模块或高风险任务计划：

• active/：进行中的计划。
• completed/YYYY-MM/：按计划文件名月份归档的已完成计划。
• templates.md：新计划模板。

创建与归档 Copy Chapter

• 多步骤、跨模块或高风险的执行任务在 active/ 使用 templates.md；
  完成后按文件名月份移动到 completed/YYYY-MM/。
• 新计划从当前模板创建，保留模板中的必填字段、章节和顺序。

内容 Copy Chapter

• plan 记录目标、范围、步骤、风险和验证。
• 文件命名与 slug 规则（含同一任务与 history 共享 slug）见
  ../histories/README.md。

active/swift-migration.md 是长期的 Objective-C-to-Swift 迁移路线图，不适用按任务命名规则。
保持其中的已完成历史和剩余工作与当前源码同步；如果某个迁移切片需要单独的里程碑或验证，
为它创建聚焦的计划。

Design Docs README (`docs/design-docs/README.md`) Copy Section

设计文档

本目录统一保存 Easydict 的产品与技术设计，以及需要长期维护的设计决策。当前 Agent 执行规则
仍以根 AGENTS.md 和 docs/agents/ 为权威；任务进度和完成结果分别位于
docs/exec-plans/ 与 docs/histories/。

产品与技术设计 Copy Chapter

• application-architecture.md：当前源码布局、运行时边界和
  验证入口。
• app-path-management.md：应用本地文件的目录布局、所有权、迁移和
  日志导出边界。
• select-text-flow.md：文本选择的回退流程。

产品与技术设计随实现更新；长期设计决策保留状态、日期、背景、取舍和重新评估条件。本目录
不保存任务日志或公共使用说明，也不作为第二套 Agent 任务路由。

Histories Template (`docs/histories/template.md`) Copy Section

YYYY-MM-DD | 任务：<简短动作> Copy Chapter

Links:

执行上下文 Copy Section

• Agent Name: <name or Unknown>
• Model: <model-id, alias, base-model, or Unknown>
• Environment: macOS <version or Unknown> / Xcode <version or Unknown> ()

用户请求 Copy Section

<对请求进行简洁且已脱敏的总结。>

变更 Copy Section

• <主要变更>
• <文档或测试变更>

设计意图 Copy Section

<说明为什么采用这种方案，以及它保留了哪个边界。>

验证 Copy Section

• <command>：<结果>
• 手动检查：<结果>

受影响文件 Copy Section

• ``

后续事项 Copy Section

• <已知限制或下一步；如果没有则填写 None>

Agents Build And Test (`docs/agents/build-and-test.md`) Copy Section

构建与测试

测试与验证原则 Copy Chapter

• 只有用户在当前任务中明确要求添加测试，才允许新增或扩写测试，包括测试文件、suite、用例、断言、
  fixture、mock、helper 和仅为测试引入的生产代码 hook；修复 bug、新增功能、修改复杂逻辑和回归
  风险都不构成授权。
• 未获授权时可以运行和分析现有测试，认为需要补充时只在结果中提建议；获授权后优先更新现有用例，
  遵循最小范围，不为测试简单实现增加生产抽象、mock 或 hook。
• 新增服务时，必须新增该服务专属的验证测试文件。服务验证可以依赖实现者本机的 CLI、登录态、密钥或
  其他配置；实现者必须在自己的开发环境中运行并通过该验证。此类环境依赖测试不要求每位开发者或 CI
  持续运行，应通过非默认 test plan 或 Xcode 的精确测试选择运行，且不得将其误认为默认离线回归测试。
• 优先运行直接覆盖变更风险的检查，影响范围不明确时再扩大；只修改已授权的测试与 fixture，不把
  未运行、失败或环境阻塞的检查写成通过。

测试与工程文件组织 Copy Chapter

• 测试目录按领域对应源码模块，Swift 测试以 Easydict/Swift/ 为映射根，例如 Service/OpenAI/
  对应 EasydictTests/Service/OpenAI/；跨模块测试按主要业务归属放置，现有目录按任务范围渐进调整。
• 每个测试文件聚焦一个主要被测类型或行为领域，最多声明一个 @Suite；接近文件规模限制时按职责
  拆分 suite 和 fixture，保留原有覆盖和标签、actor 隔离、共享状态恢复、串行边界。独立 suite 的
  .serialized 不提供跨 suite 串行保证。
• 单文件 helper 保持局部，同领域共享工具就近放置，跨目录复用的 fixture 或工具放入
  EasydictTests/Support/<Domain>/，资源放入对应测试资源目录。
• 新增、移动或删除由 Xcode 管理的源码文件或运行时资源时，同步
  Easydict.xcodeproj/project.pbxproj 中的 group、文件和 build phase 引用，测试文件同时同步测试
  target 的 Sources，删除文件不保留悬空引用。仓库治理 Markdown、plan、history、skill、参考资料
  和 docs/ 下的公共 Markdown 不需要工程引用，除非作为运行时资源发布。

选择验证 Copy Chapter

根据变更需要证明的结果选择最小且充分的验证，不按变更行数设置硬阈值。

• 纯治理 Markdown、plan、history、注释，以及不进入 Xcode 构建图的脚本或配置，只运行相应静态
  检查：Markdown 的格式、相对链接、锚点和规则语义检查。
• 生产源码、工程/workspace、target、build setting、build phase、依赖、entitlement、Info.plist
  或运行时资源发生实质变化时，运行覆盖受影响配置的 xcodebuild build；修复 bug、修改可测试
  行为或测试源码及其 target 引用时，运行覆盖相应行为、suite 或方法的 xcodebuild test。
• xcodebuild build 只证明构建集成；相同配置的成功测试已覆盖编译，不重复运行 build，测试未覆盖
  的 Release、Archive、签名或其他配置另行验证。重复运行兼容的测试时先 build-for-testing，再
  用 test-without-building，前者本身不构成测试通过证据。
• 每次变更运行 git diff --check；对变更的 .xcstrings 或 JSON 运行 jq -e .，对变更的 Shell
  脚本运行 bash -n。
• 并发判据是构建目录而不是构建入口：同一 workspace 与同一 DerivedData 的并发构建，无论来自
  Xcode IDE 还是 xcodebuild，都会互相破坏增量状态和 build database；DerivedData 不同可以并行。
• 因此 agent 运行 xcodebuild 时始终显式指定 -derivedDataPath，指向按 checkout 派生、与 Xcode
  默认目录不相交的 ~/Library/Developer/Xcode/DerivedData/Easydict-Agent/<checkout-id>；损坏时
  删除该目录重建，不切换到 Xcode 默认 DerivedData。
• xcodebuild test 会启动同 bundle id 的 Easydict-debug.app 测试宿主，不要与 Xcode 的 Run/Test
  同时运行；构建与 Archive 不受此限制。

常用命令 Copy Chapter

# 每个 checkout 一个 agent 专用 DerivedData，与 Xcode 默认目录互不相交
set -o pipefail
checkout_id="$(git rev-parse --show-toplevel | sed -e "s|^$HOME/||" -e 's|^\.||' -e 's|/|_|g')"
agent_dd="$HOME/Library/Developer/Xcode/DerivedData/Easydict-Agent/$checkout_id"

# 构建
xcodebuild build \
  -workspace Easydict.xcworkspace \
  -scheme Easydict \
  -derivedDataPath "$agent_dd" | xcbeautify

# 运行测试
xcodebuild test \
  -workspace Easydict.xcworkspace \
  -scheme Easydict \
  -derivedDataPath "$agent_dd" | xcbeautify

# 构建可复用的测试产物
xcodebuild build-for-testing \
  -workspace Easydict.xcworkspace \
  -scheme Easydict \
  -derivedDataPath "$agent_dd" | xcbeautify

# 复用已构建产物运行指定 suite 或方法，-only-testing 支持 <Suite> 与 <Suite>/<test>
xcodebuild test-without-building \
  -workspace Easydict.xcworkspace \
  -scheme Easydict \
  -derivedDataPath "$agent_dd" \
  -only-testing:EasydictTests/UtilityFunctionsTests | xcbeautify

xcbeautify 依赖 pipefail 才能保留 xcodebuild 的真实退出状态。重建时只删除当前 checkout 的
agent_dd，不动 Xcode 默认目录或其他 checkout。

Agents Skills (`docs/agents/skills.md`) Copy Section

外部 Skill 资产

背景与设计 Copy Chapter

Easydict 直接从仓库运行共享 Skills，安装内容需要可离线审查和历史复现；只引用外部目录缺少
稳定证据，项目各自修改副本又会产生行为和安全差异。

• 外部仓库统一维护通用内容；skills-lock.json 登记的目录是外部权威内容的完整项目快照，
  可离线读取和运行。
• lock 记录来源、ref、入口路径和内容哈希，通过重算检查本地漂移，不替代实际安装内容。
• Swift/Xcode、本地化和发布等项目政策写入宿主规则；通用 Git、Review 和交付算法由受管
  Skill 维护，不通过本地修补或 fork 改写。
• 独立第三方 Skill 保持自身来源；项目专属 Skill 由 Easydict 维护。

取舍：仓库保存较大的第三方快照，换取离线可用、可审查和可回滚；跟踪可移动分支时需额外
记录同步 commit，上游提供稳定 tag 后优先采用 tag。重新评估条件：安装器改变 lock、hash 或
安装目录；上游改变仓库、发布方式或 Skill 路径；项目差异无法继续由宿主规则表达。

操作规则 Copy Chapter

• 普通任务不得修改受管快照或手工调整 hash；只有用户明确要求升级时才使用安装器同步。
• 不同来源分别同步，并按下方来源基线的版本和命令核验，不递归复制上游工作目录。
• fireworks-tech-graph 保持独立来源；release-easydict 是不进入 lock 的项目专属 Skill。
• .claude/skills 指向 .agents/skills，不是独立副本。
• 同步后核对来源 tree、目录 hash、lock、项目专属 Skill 和符号链接，并运行风险匹配的静态
  检查与 Skill 测试。

来源基线：tisfeng/skills Copy Chapter

• 核对日期：2026-09-27；来源：https://github.com/tisfeng/skills；安装器 [email protected]。
• 采用版本：v0.7.2；annotated tag 4040ed8b87a26c8c89530362f285270fd0912b73（unsigned），
  peeled commit f979c5ddc4e9eab6ae04bad912ed95c7ecdde344；核验时同时固定 tag 和 peeled
  commit。
• 采用范围：code-simplifier、git-commit、review、review-pr、submit-pr、
  worktree-rebase-merge 六个完整 Skill 目录，不采用其他上游内容。

npx -y [email protected] add \
  https://github.com/tisfeng/skills/tree/v0.7.2 \
  --skill code-simplifier git-commit review review-pr submit-pr worktree-rebase-merge \
  --agent codex --yes --copy --full-depth

• 安装器没有 --cwd 选项，必须从仓库根目录执行；npm 默认缓存可能包含 root-owned 文件并
  返回 EPERM，用独立的 npm_config_cache 运行安装器。
• skills-lock.json 的内容哈希为 sha256：把 Skill 目录内全部文件按相对路径排序后拼接路径
  与内容再哈希。
• v0.6.3 强制双语提交的本地语言与英文标题分别使用对应语言，并保持相同的 Angular
  type、scope 与 breaking 语义，避免两个区块复用同一英文标题。
• 上游仓库级格式校验不随安装器复制，升级时另行核对 frontmatter、agents/openai.yaml 和
  相对链接。
• code-simplifier 同时包含 Electron 与 Swift 条件规则，不删减不适用部分，任务中按 Skill
  路由读取适用内容。
• 上游 .agents/skills/<name> -> ../../skills/<name> 链接是上游自用的源码发现机制，快照
  继续使用 --copy --full-depth 保存完整目录，不引入这些链接。
• submit-pr 需要 Python 3.10 或更高版本；同一任务的 plan 与 apply 使用同一个已核验解释
  器，项目命令示例优先使用 Python 3.12；不通过本地修改受管脚本绕过运行时依赖。
• 重新核对条件：发布新的统一版本；安装器版本、lock 格式或技能集合变化；上游重新引入平台
  专属资产。

来源基线：fireworks-tech-graph Copy Chapter

• 核对日期：2026-09-13；来源：
  https://github.com/yizhiyanhua-ai/fireworks-tech-graph；上游 Skill 路径
  skills/fireworks-tech-graph；本地安装路径 .agents/skills/fireworks-tech-graph/。
• 采用 ref main，同步时 commit 31fea364eda5f1852b1175f3d9e29ea31d22dcb4；安装器
  [email protected]；完整同步上游 Skill 目录，不接受本地内容修改。

npx -y [email protected] add \
  https://github.com/yizhiyanhua-ai/fireworks-tech-graph/tree/main/skills/fireworks-tech-graph \
  --skill fireworks-tech-graph --agent codex --yes --copy --full-depth

• 命令只选择该来源和 Skill；同步后检查 .agents/skills/fireworks-tech-graph/ 与
  skills-lock.json 中对应条目，不用跨来源的整项目更新代替，也不手工调整 computed hash。
  Easydict 直接从 .agents/skills/ 读取该 Skill，不维护根 skills/ 兼容别名。
• 大小写不敏感文件系统上，仓库 ignore 规则可能误匹配并静默排除受管文件（如 Icon? 匹配
  assets/icons/）；为受管路径保留精确的 ignore 例外，同步后核对目录哈希与上游 tracked
  tree 一致。
• 重新核对条件：main 指向新 commit 且用户明确要求同步；上游发布稳定 tag 或移动、拆分
  Skill 路径；安装器改变复制内容、hash 或 lock 字段。

User Docs En GUIDE (`docs/user-docs/en/GUIDE.md`) Copy Section

Easydict Complete Usage Guide

Easydict is a macOS dictionary and translation app with typed input, text selection, OCR, speech,
local dictionaries, and multiple online or AI services.

Feature overview Copy Chapter

• Automatic input-language detection and 52 selectable translation languages; availability varies
  by service.
• Typed input, mouse selection, selection shortcuts, screenshot translation, and silent OCR.
• Apple Vision OCR with an optional Youdao OCR fallback.
• Apple, Baidu, Bing, Google, and Youdao TTS.
• 20+ dictionary, translation, AI, local-model, and CLI services; see the
  services overview.
• Separate service selections for the main, floating, and mini windows.
• Query history, favorites, export and cleanup, plus Markdown rendering for AI results.

Installation Copy Chapter

The latest version requires macOS 13.0 or later. Users on macOS 11/12 can install the older
2.7.2 release, which does not include
current features.

Homebrew (recommended) Copy Section

brew install --cask easydict

Manual installation Copy Section

Download the latest version from GitHub Releases.

Developer build Copy Section

The current source requires macOS 13+, Xcode 16+, and CocoaPods.

1. Clone the repository and switch to the dev branch.
2. Run pod install in the repository directory.
3. Open Easydict.xcworkspace in Xcode, not Easydict.xcodeproj.
4. Select the Easydict scheme and press Command + R to build and run.

When frequently debugging selection or OCR, use your own Apple Development certificate. Ad-hoc
signing can cause macOS to reset permissions after each rebuild. The project script creates a local,
Git-ignored signing configuration:

chmod +x scripts/setup-team.sh
./scripts/setup-team.sh

If the Team ID cannot be detected, run ./scripts/setup-team.sh ABC123DE45. Without a development
certificate, use ./scripts/setup-team.sh --adhoc. Remove the local configuration with
./scripts/setup-team.sh --uninstall.

Basic usage Copy Chapter

Settings → Shortcuts also lets you assign global shortcuts for clipboard translation, screenshot
OCR, clipboard OCR, the OCR window, translate-and-replace, polish-and-replace, and other actions.
Some of these actions have no default shortcut.

Permissions Copy Chapter

macOS requests permissions according to the features you use:

• Accessibility: reads selected text in other apps and performs replacement actions.
• Screen Recording: captures screenshots for translation and OCR.
• Automation: controls browsers, Shortcuts, or other apps when required.

Grant them under System Settings → Privacy & Security. After changing the app signature, moving the
app, or rebuilding it, macOS may treat it as a new app and ask again.

Selection and input Copy Chapter

Easydict chooses an appropriate text-selection method for the frontmost app. If it cannot read a
selection:

1. Check Accessibility permission.
2. Use Command + C to verify that the text can be copied.
3. Use the input window or clipboard translation instead.
4. Use OCR for images, scanned PDFs, or text that cannot be selected.

General settings include automatic queries while typing and reverse translation. Select the source
language manually when automatic detection is inaccurate.

OCR Copy Chapter

Easydict uses Apple Vision OCR by default. If Youdao OCR fallback is enabled, it tries Youdao when
system recognition fails. Available recognition languages depend on your macOS version; newer
systems generally offer more languages.

• Screenshot translation: runs enabled query services after OCR.
• Silent screenshot OCR: recognizes and copies text without showing translation results.
• Screenshot/clipboard OCR and OCR window: use them from the menu or assign global shortcuts.

System OCR also extracts QR code payloads. When an image contains both text and QR codes, the QR code content is appended after the recognized text.

For better results, capture a smaller area, improve text/background contrast, and select the correct
recognition language in settings.

Text to speech Copy Chapter

Easydict supports Apple, Baidu, Bing, Google, and Youdao TTS, with Youdao selected by default. TTS
settings control the service and automatic playback. You can also disable the preference that uses
Youdao first for English words.

Online TTS depends on the network and upstream service. System voices and languages depend on voices
installed in macOS.

Service settings Copy Chapter

New installations enable Youdao, DeepL, and Built-in AI by default. Open Settings → Services to:

• add, remove, enable, disable, and reorder services;
• see whether a service uses no key, built-in access, a user key, or a CLI;
• enter an API key, App ID, or secret where required;
• select services separately for the main, floating, and mini windows;
• add multiple custom OpenAI-compatible services.

See the services overview for the complete list, access requirements, and guidance.
Focused setup guides:

• Apple Dictionary
• MDict
• Apple Translate

GitHub Copilot translate Copy Section

The GitHub Copilot service uses the official copilot CLI installed on your machine, so install and
sign in to it first:

1. Install it via Homebrew (brew install --cask copilot-cli) or another official method.
2. Run copilot login in a terminal to authorize GitHub.
3. In Settings → Services, add GitHub Copilot and confirm the status row shows the detected CLI path.

This service does not use OAuth, private endpoints, or proxy workarounds, and it never reads, stores,
or logs your Copilot token. The official CLI keeps your credentials in the system keychain, and your
available usage depends on your Copilot plan.

Each translation spawns an independent CLI process, so no conversation state carries over. To reduce
risk, Easydict runs it with isolation flags: no tools are available, built-in MCP is disabled, custom
instructions from the working directory are not loaded, remote control is off, and CLI auto-update is
disabled. It also runs with a disposable configuration directory, so translated text does not remain
in the session records under ~/.copilot. That directory holds only this request's temporary data
and is deleted once the process exits.

Use the refresh button in GitHub Copilot service settings to retrieve and save the available models
and their reasoning levels. When Copilot is enabled in any query window, Easydict also refreshes
in the background about five seconds after launch, then every 24 hours while the app is running.
Settings and query windows use the saved list immediately, including after restarting Easydict;
opening a menu or starting a translation does not refresh it. You can refresh manually after
upgrading the CLI or changing accounts. A failed refresh keeps the previous list until the next
scheduled or manual refresh. Quitting the app stops the timer; the next launch schedules it again.

Selecting "CLI default model" uses the model saved in the CLI's current local settings. The reasoning
picker offers the levels saved for the selected model; "Default" leaves the choice to the CLI.
If a model or reasoning level is no longer available, refresh the list in settings. If the service
reports that the CLI is missing or not signed in, complete the install and login steps above.

If the CLI requests a tool during a translation, Easydict aborts that request immediately and reports
an error. That indicates the isolation guarantee no longer holds, which usually means the CLI changed
its behavior, so please report it.

History and results Copy Chapter

• Query history keeps recent items for re-querying, favoriting, exporting, or clearing.
• Favorites keep entries you want to revisit.
• Markdown returned by AI services is rendered as rich text; copied content remains available as text.
• Service cards can be retried, copied, or collapsed depending on the current window and state.

In-app shortcuts Copy Chapter

These shortcuts work while an Easydict window is in the foreground:

Change global shortcuts under Settings → Shortcuts. If a shortcut does not respond, check for a
conflict with another app or a macOS shortcut.

URL scheme Copy Chapter

Use this URL to start a query from another app. The text value must be URL-encoded:

easydict://query?text=hello%20world

The older easydict://text form can fail in some contexts, so always prefer the complete
query?text= form.

Use with PopClip Copy Section

After installing PopClip, install this AppleScript action as an extension:

-- #popclip
-- name: Easydict
-- icon: iconify:ri:translate
-- language: applescript
tell application "Easydict"
  launch
  open location "easydict://query?text={popclip text}"
end tell

Troubleshooting Copy Chapter

• Selection does not work: check Accessibility permission and confirm that the target app lets
  you select or copy text.
• Screenshot capture does not work: check Screen Recording permission and restart Easydict.
• Only one service fails: check whether it is enabled, then verify credentials, CLI login, local
  URL, and network status.
• A language is unsupported: switch services; translation, OCR, and TTS coverage differ.
• A setting does not apply: quit and reopen Easydict, then check whether multiple versions are
  running.

Contributing Copy Chapter

• See the contribution guide for development and code contributions.
• See How to translate Easydict for localization contributions.
• Report bugs and ideas in GitHub Issues.

User Docs En How To Translate Easydict (`docs/user-docs/en/How-to-translate-Easydict.md`) Copy Section

Getting Started on Localization

Easydict uses Xcode String Catalog to manage translations, so the following steps are what you need to get started on localizing the app.

Installing Xcode 16+ Copy Section

You can install Xcode from the Mac App Store or its beta versions on Apple Developer.

Cloning and building the project Copy Section

1. Use git to clone the project from GitHub to your Mac. You can do this by using the git command line tool or GitHub Desktop.
2. Make sure to base your changes on the dev branch, this is where localization work takes place.
3. Open the project and build it. Detailed instructions are available in the
   developer build guide.

Adding your language to String Catalog Copy Section

Now you can start to add your own language!

1. Navigate to Easydict -> Easydict -> App -> Localizable.xcstrings. This catalog contains the main app strings. Also open Easydict/App/InfoPlist.xcstrings for app metadata and permission descriptions.
2. Click on the Localizable.xcstrings file and click the + button to find a list of available options. If you don't see the language you want to localize on the list (e.g. Canadian English). Scroll all the way down to the bottom of the menu to find More Languages.
3. After you add a language, you can start translating. Add the same language to InfoPlist.xcstrings and translate its strings as well.

Previewing your translations Copy Section

After you are done with your translations, it's nice to run the app and go over your work. You can set the app language to the one that you did with a simple few clicks.

1. Find Easydict's icon on the top toolbar of Xcode and click on it
2. Click on Edit Scheme...
3. Select the RUN tab on the left sidebar and go to Options
4. Scroll down to find App Language, then choose the one you localized for
5. Close the tab and use ⌘R to run the app and see your translations

Pushing your changes to GitHub Copy Section

After you finish checking your localization, it's time to push the changes to GitHub and start a pull request.

• Start a Pull Request.
• Remember to set the merge target to the dev branch

Now you can wait for a maintainer's review and get your translations adopted in the next release version.

Additional Resources Copy Section

• Localization - Apple Developer
• Localizing and varying text with a string catalog - Apple Developer
• Discover String Catalogs - WWDC23 Videos
• Apple Localization Glossaries
• Sample Pull Request for Easydict

User Docs En How To Use MacOS System Dictionary In Easydict (`docs/user-docs/en/How-to-use-macOS-system-dictionary-in-Easydict.md`) Copy Section

Use Apple Dictionary in Easydict

Easydict can query system dictionaries and .dictionary bundles enabled in the macOS Dictionary
app. This makes them available even in apps that do not support the system three-finger lookup.

Enable system dictionaries Copy Chapter

1. Open the macOS Dictionary app.
2. Open Dictionary → Settings, enable the dictionaries you need, and arrange their order.
3. Open Easydict Settings → Services, then add or enable Apple Dictionary.
4. Look up a word and confirm that Apple Dictionary results appear.

Dictionary content and language availability are controlled by macOS and the Dictionary app, so
they may differ between system versions and regions.

Add a `.dictionary` bundle Copy Chapter

If you have a legally obtained Apple .dictionary bundle:

1. In the Dictionary app, choose File → Open Dictionaries Folder.
2. Put the .dictionary bundle in that folder.
3. Reopen Dictionary and enable the new dictionary in its settings.
4. Restart Easydict so it reloads the dictionary list.

Do not use dictionary files from unknown or unauthorized sources. Easydict does not provide
third-party dictionary downloads.

Use MDX/MDD dictionaries Copy Chapter

MDX/MDD files are not Apple .dictionary bundles. Easydict now includes a native MDict service, so
you can import them without conversion. See Use MDict in Easydict.

Troubleshooting Copy Chapter

• A new dictionary is missing in Easydict: enable it in Dictionary settings, then restart
  Easydict.
• Lookup returns no result: confirm that the dictionary contains the entry and try moving it
  earlier in the Dictionary app's list.
• You only want selected dictionaries: disable the others in Dictionary settings.

User Docs En How To Use MacOS System Translation In Easydict (`docs/user-docs/en/How-to-use-macOS-system-translation-in-Easydict.md`) Copy Section

Use Apple Translate in Easydict

The Apple Translate service has two execution paths:

• macOS 15 and later: optionally use Apple's Translation framework for offline translation
  between languages supported by the system.
• Shortcut fallback: when offline translation is disabled or macOS is earlier than 15,
  Easydict calls system translation through a specific macOS Shortcut.

macOS 15 and later: offline translation Copy Chapter

1. In Easydict Settings → Services, add or enable Apple Translate, then select it in the service
   list.
2. Enable Apple Offline Translation in its settings. Use the manage downloaded languages link
   in the description to open translation language settings and download the languages you need.
3. Test with a source and target language supported by the system.

Apple offline translation is disabled by default. Language coverage and downloaded language packs
are managed by the current macOS version. The system may ask for a language download or return an
error when a pack is missing. If the Translation framework fails while enabled, Easydict reports
the error instead of automatically switching to the Shortcut.

macOS 13/14 or fallback path: install the Shortcut Copy Chapter

Open and install
Easydict-Translate-V1.2.0
with Safari:

1. Choose Get Shortcut.
2. Allow Safari to open the Shortcuts app.
3. Choose Add Shortcut.
4. Confirm that its name is Easydict-Translate-V1.2.0.

Do not rename the Shortcut or change its actions. Easydict invokes it by its expected name. On the
first run, macOS may ask for Automation permission to let Easydict control Shortcuts; allow it.

Enable the service Copy Chapter

Open Easydict Settings → Services, then add or enable Apple Translate. On macOS 15+, Easydict uses
the Translation framework when offline translation is enabled; with the option disabled or on
macOS 13/14, it uses the Shortcut path.

Troubleshooting Copy Chapter

• The Shortcut cannot be found: verify the exact name Easydict-Translate-V1.2.0 and run it
  once in the Shortcuts app.
• Offline translation returns no result: verify that you use macOS 15+, enabled the Easydict
  setting, and downloaded the required languages.
• The call is denied: check Easydict under System Settings → Privacy & Security → Automation.
• A language is unavailable: Apple controls the system language coverage; use another Easydict
  service when necessary.

User Docs En SPONSOR LIST (`docs/user-docs/en/SPONSOR_LIST.md`) Copy Section

Sponsor List

If you don't want your username to be displayed in the list, please choose anonymous.

Thank you for your support.

User Docs Zh GUIDE (`docs/user-docs/zh/GUIDE.md`) Copy Section

Easydict 完整使用指南

Easydict 是一款 macOS 词典和翻译应用，支持输入翻译、鼠标划词、快捷键划词、OCR、朗读、
本地词典和多个在线/AI 服务。

功能概览 Copy Chapter

• 自动识别输入语言，并提供 52 种可选翻译语言；实际可用范围因服务而异。
• 输入、鼠标划词、快捷键划词、截图翻译和静默截图 OCR。
• Apple Vision OCR，并可选用有道 OCR 作为失败回退。
• Apple、百度、Bing、Google 和有道 TTS。
• 20+ 词典、翻译、AI、本地模型和 CLI 服务，完整清单见服务总览。
• 主窗口、悬浮窗口和迷你窗口可分别选择服务。
• 查询历史、收藏、导出和清理；AI 结果支持 Markdown 显示。

安装 Copy Chapter

最新版本支持 macOS 13.0 及以上。macOS 11/12 用户可以使用旧版
2.7.2，但该版本不再包含最新功能。

Homebrew 安装（推荐） Copy Section

brew install --cask easydict

手动安装 Copy Section

从 GitHub Releases 下载最新版本。

开发者构建 Copy Section

当前源码需要 macOS 13+、Xcode 16+ 和 CocoaPods。

1. 克隆仓库并切换到 dev 分支。
2. 在仓库目录运行 pod install。
3. 使用 Xcode 打开 Easydict.xcworkspace，不要打开 Easydict.xcodeproj。
4. 选择 Easydict scheme，按 Command + R 构建运行。

经常调试取词或 OCR 时，建议使用自己的 Apple Development 证书，避免 ad-hoc 签名导致
macOS 在重新构建后重置权限。项目脚本可以生成被 Git 忽略的本地签名配置：

chmod +x scripts/setup-team.sh
./scripts/setup-team.sh

无法自动检测 Team ID 时，可运行 ./scripts/setup-team.sh ABC123DE45。没有开发者证书时可用
./scripts/setup-team.sh --adhoc；移除本地配置可用 ./scripts/setup-team.sh --uninstall。

基本使用 Copy Chapter

还可以在“设置 → 快捷键”中为剪贴板翻译、截图 OCR、剪贴板 OCR、显示 OCR 窗口、翻译并
替换、润色并替换等操作设置全局快捷键。这些操作默认可能没有快捷键。

权限 Copy Chapter

macOS 会根据使用方式请求权限：

• 辅助功能：读取其他应用中选中的文本，以及执行替换等操作。
• 屏幕录制：截图翻译、截图 OCR。
• 自动化：控制浏览器、快捷指令或其他应用时使用。

在“系统设置 → 隐私与安全性”中授权。如果更换签名、移动 App 或重新构建，macOS 可能把它
视为新应用，需要重新授权。

划词与输入 Copy Chapter

Easydict 会根据目标应用选择合适的取词方式。若某个应用无法读取选中文本：

1. 检查辅助功能权限。
2. 尝试用 Command + C 确认文本本身可以复制。
3. 改用输入窗口或剪贴板翻译。
4. 对图片、扫描 PDF 或不可选择内容使用 OCR。

可在通用设置中启用输入时自动查询、反向翻译等行为。自动识别不准确时，请手动选择源语言。

OCR Copy Chapter

Easydict 默认使用 Apple Vision OCR；如果启用有道 OCR 回退，系统识别失败时会尝试有道。
可用语言取决于 macOS 版本，较新的系统通常提供更多识别语言。

• 截图翻译：OCR 后立即查询已启用的服务。
• 静默截图 OCR：只识别并复制文字，不显示翻译结果。
• 截图/剪贴板 OCR 与 OCR 窗口：可从菜单使用，或自行设置全局快捷键。

系统 OCR 也会提取二维码内容。图片同时包含文字和二维码时，二维码内容会追加在识别文本之后。

OCR 结果不理想时，缩小截图范围、提高文字与背景对比度，并在设置中选择正确的识别语言。

TTS 朗读 Copy Chapter

Easydict 支持 Apple、百度、Bing、Google 和有道 TTS，默认使用有道。可以在 TTS 设置中调整
服务和自动朗读行为，也可以关闭“英语单词优先使用有道”等偏好。

在线 TTS 受网络和上游接口影响；系统 TTS 的声音和语言由 macOS 已安装语音决定。

服务设置 Copy Chapter

新安装默认启用有道词典、DeepL 和内置 AI。打开“设置 → 服务”可以：

• 添加、移除、启用、停用和排序服务；
• 查看服务是无需密钥、项目内置、用户密钥还是 CLI 类型；
• 为需要凭据的服务填写 API Key、App ID 或 Secret；
• 为主窗口、悬浮窗口和迷你窗口分别选择服务；
• 添加多个自定义 OpenAI 兼容服务。

服务清单、访问条件和配置建议见服务总览。专题配置：

• Apple Dictionary
• MDict
• Apple 翻译

Codex 翻译 Copy Section

在“设置 → 服务”添加 Codex，首次使用先点击“下载 Codex 组件”，完成后点击
“使用 ChatGPT 登录”，在官方浏览器页面完成授权。应用会按系统和芯片下载并校验官方
组件，无需自行安装命令行工具；下载可取消或失败后重试。授权成功后会独立翻译一次固定问候语
来检查连接，使用组件的默认模型；这次检查不会覆盖查询窗口内容。浏览器未打开时可点击
“重新打开浏览器”，该按钮复用当前授权，不重复创建登录。

所有窗口共用一个内置 ChatGPT 账户。取消登录后会重新检查实际状态；恢复默认设置也
不会退出账户。需要移除该登录时请使用“退出登录”。使用权限和额度取决于登录账户，
连接检查也会产生一次模型请求；内置方式不会自动使用外部 API Key。

手动点击“测试连接”时，会使用当前服务选择的模型和思考程度验证翻译。验证通过状态
只对应这组设置；修改模型、思考程度或使用方式后，需要重新测试。

“高级设置”可以切换“本机 CLI”，继续使用自己安装的 Codex 和原有配置。已有 Codex
服务升级后保留本机方式；新增服务默认使用内置方式。两种方式分别保存模型和推理强度，
切换方式不会自动重新翻译当前文字。

macOS 13/14 使用固定的 0.134.0 组件，默认模型为 gpt-5.5。macOS 15 及以上使用
0.153.4 组件，默认 gpt-5.6-luna，可选 gpt-6-astra、gpt-5.6-sol、
gpt-5.6-terra、gpt-5.6-luna、gpt-5.5。可用性仍取决于账户权限和服务端状态。

已退役或不支持的模型不会作为可选项显示。如果原来保存的模型或思考程度不再支持，
设置页会提示重新选择，应用不会自动更改该保存值或重译当前文字。本机 CLI 保持自行
指定模型的能力。内置组件不会独立更新，模型列表随应用更新维护。

如果提示 Keychain 不可用，请检查系统钥匙串是否已解锁，然后重试；应用不会改用明文
保存登录信息。如果提示外部配置影响隔离，请检查系统级 Codex 配置或全局 skills，
也可选择本机 CLI 按原有配置使用；Easydict 不会自动删除这些配置。

GitHub Copilot 翻译 Copy Section

GitHub Copilot 服务使用你本机安装的官方 copilot CLI，因此需要先自行安装并登录：

1. 通过 Homebrew 安装（brew install --cask copilot-cli），或使用官方其他安装方式；
2. 在终端执行 copilot login 完成 GitHub 授权；
3. 在“设置 → 服务”添加 GitHub Copilot，确认状态行显示已检测到 CLI 路径。

本服务不使用 OAuth、私有接口或代理绕过，也不读取、不保存、不打印你的 Copilot token；
登录凭据由官方 CLI 自己保存在系统钥匙串中。使用权限和额度取决于你的 Copilot 订阅方案。

翻译请求每次都会启动一个独立的 CLI 进程，因此不保留会话上下文。为降低误操作风险，
Easydict 会以隔离参数运行它：不提供任何工具、关闭内置 MCP、不加载工作目录的自定义指令、
不使用远程控制，并关闭 CLI 自动更新。运行使用一次性的配置目录，翻译内容不会留在
~/.copilot 下的会话记录中。该目录只包含本次请求的临时数据，进程结束后即删除。

在 GitHub Copilot 服务设置中点击刷新按钮，获取并保存可用模型及推理等级。任一查询窗口
启用 Copilot 时，Easydict 也会在启动约 5 秒后后台刷新一次，此后在应用运行期间每 24 小时
刷新一次。设置页和查询窗口直接使用本地列表，重启后仍保留；打开菜单或开始翻译不会刷新
目录。更新 CLI 或切换账号后，可手动立即刷新。刷新失败保留旧列表，等待下一次定时或手动
刷新。退出应用时停止定时器，下次启动重新安排。

选择“CLI 默认模型”会沿用 CLI 当前本地配置中的模型；“推理程度”只展示本地目录中该模型
支持的等级，选择“默认”则由 CLI 决定。若模型或推理等级已不可用，请在设置中刷新列表。
若提示未安装或未登录，请先完成上面的安装与登录步骤。

如果 CLI 在翻译过程中请求使用工具，Easydict 会立即中止该次请求并提示错误。这是隔离预期
的异常信号，通常意味着 CLI 行为已变更，请反馈该问题。

查询记录与结果 Copy Chapter

• 查询历史会记录近期内容，可重新查询、收藏、导出或清理。
• 收藏适合保存需要长期复习或引用的词条。
• AI 服务返回的 Markdown 会按富文本显示；复制时仍可获取文本内容。
• 服务卡片可以重试、复制或折叠，实际操作取决于当前窗口和服务状态。

应用内快捷键 Copy Chapter

这些快捷键只在 Easydict 窗口位于前台时生效：

全局快捷键可在“设置 → 快捷键”中修改。若组合键没有响应，检查是否与其他应用或系统快捷键
冲突。

URL Scheme Copy Chapter

使用下面的 URL 可以从其他应用发起查询，其中 text 必须进行 URL 编码：

easydict://query?text=hello%20world

旧式 easydict://文本 形式在部分场景中可能失败，建议始终使用完整的 query?text= 格式。

配合 PopClip 使用 Copy Section

安装 PopClip 后，可将下面的 AppleScript 动作安装为扩展：

-- #popclip
-- name: Easydict
-- icon: iconify:ri:translate
-- language: applescript
tell application "Easydict"
  launch
  open location "easydict://query?text={popclip text}"
end tell

故障排查 Copy Chapter

• 划词无效：检查辅助功能权限，并确认目标应用允许选择或复制文本。
• 截图无效：检查屏幕录制权限，授权后重新启动 Easydict。
• 只有某个服务失败：检查该服务是否启用，以及凭据、CLI 登录、本地地址和网络状态。
• 语言不受支持：切换服务；不同服务、OCR 和 TTS 的语言覆盖并不相同。
• 设置没有生效：退出并重新打开 Easydict，再检查是否运行了多个版本。

参与贡献 Copy Chapter

• 开发流程和代码贡献见贡献指南。
• 本地化贡献见如何翻译 Easydict。
• 问题和建议请提交到 GitHub Issues。

User Docs Zh How To Translate Easydict (`docs/user-docs/zh/How-to-translate-Easydict.md`) Copy Section

开始翻译

Easydict 的翻译是通过 Xcode 中的 String Catalog 管理的，下面是翻译 Easydict 的详细步骤

安装 Xcode 16+ Copy Section

可以从 Mac App Store 安装Xcode，或者从 Apple Developer 获取 Beta 版本。

克隆和构建项目 Copy Section

1. 使用 git 将项目从 GitHub 克隆到本地，这里可以使用 git 命令行工具 或 GitHub Desktop
2. 切换到 dev 分支
3. 打开项目并构建，有关如何构建项目的详细说明在这里

添加语言到String Catalog Copy Section

现在可以添加新的语言了！

1. 找到 Easydict -> Easydict -> App -> Localizable.xcstrings。该目录包含应用主要文本。同时打开 Easydict/App/InfoPlist.xcstrings，翻译应用元数据和权限说明。
2. 首先打开 Localizable.xcstrings 文件，然后点+按钮添加语言，如果找不到要做翻译的语言（例如 Canadian English），滚动到菜单底部，打开二级菜单 More Languages
3. 添加语言后就可以开始翻译了。同时在 InfoPlist.xcstrings 中添加相同语言并翻译其中的字符串。

预览翻译 Copy Section

在完成翻译后可以跑一下 Easydict 做检查。

1. 在 Xcode 顶部工具栏上找到 Easydict 图标，然后点击它
2. 点击 Edit Scheme...
3. 在侧边栏中选择 RUN，然后转到 Options
4. 向下滚动找到 App Language，然后选择要检查的语言
5. 关闭选项卡，然后使用快捷键 ⌘R 运行 Easydict 并检查翻译

将更改 push 到 GitHub Copy Section

在完成本地化检查后就可以将更改 push 到 GitHub 并发起拉取请求了。

• 发起拉取请求。
• 记得将合并目标设置为dev分支

最后等待 review 完成就可以合并到主仓库，并在下一次发版看到最新的翻译啦！

其他资源 Copy Section

• Localization - Apple Developer
• Localizing and varying text with a string catalog - Apple Developer
• Discover String Catalogs - WWDC23 Videos
• Apple 本地化术语表
• Easydict 本地化示例 PR

User Docs Zh How To Use MacOS System Dictionary In Easydict (`docs/user-docs/zh/How-to-use-macOS-system-dictionary-in-Easydict.md`) Copy Section

在 Easydict 中使用 Apple Dictionary

Easydict 可以查询 macOS“词典”App 中已经启用的系统词典和 .dictionary 词典，让不支持
系统三指查询的应用也能使用这些词典。

启用系统词典 Copy Chapter

1. 打开 macOS“词典”App。
2. 打开“词典 → 设置”，勾选需要使用的词典并调整顺序。
3. 打开 Easydict“设置 → 服务”，添加或启用 Apple Dictionary。
4. 查询一个词语，确认 Apple Dictionary 结果正常显示。

词典内容和可用语言由 macOS 及“词典”App 决定，不同系统版本或地区可能有所不同。

添加 `.dictionary` 词典 Copy Chapter

如果你有合法获取的 Apple .dictionary 词典：

1. 在“词典”App 中选择“文件 → 打开词典文件夹”。
2. 将 .dictionary 文件放入打开的目录。
3. 重新打开“词典”App，在设置中启用该词典。
4. 重启 Easydict，让它重新读取词典列表。

请勿使用来源不明或没有授权的词典文件。Easydict 不提供第三方词典下载。

使用 MDX/MDD 词典 Copy Chapter

MDX/MDD 不属于 Apple .dictionary 格式。Easydict 已提供原生 MDict 服务，可以直接导入，
不需要转换。参阅在 Easydict 中使用 MDict。

常见问题 Copy Chapter

• Easydict 中没有新词典：先确认它已在“词典”App 设置中启用，再重启 Easydict。
• 查询结果为空：确认目标词典包含该词条，并尝试把它移到“词典”App 列表前面。
• 只想使用部分词典：在“词典”App 设置中停用不需要的词典。

User Docs Zh How To Use MacOS System Translation In Easydict (`docs/user-docs/zh/How-to-use-macOS-system-translation-in-Easydict.md`) Copy Section

在 Easydict 中使用 Apple 翻译

Easydict 的 Apple 翻译服务有两条调用路径：

• macOS 15 及以上：可启用 Apple Translation 框架，在系统支持的语言之间进行离线翻译。
• 快捷指令回退：关闭离线翻译或 macOS 版本低于 15 时，通过指定的
  macOS 快捷指令调用系统翻译。

macOS 15 及以上：离线翻译 Copy Chapter

1. 打开 Easydict“设置 → 服务”，添加或启用 Apple 翻译，然后在服务列表中选中它。
2. 在 Apple 翻译设置中启用“苹果离线翻译”，并点击说明里的“管理下载语言”打开翻译语言设置、
   下载需要的语言。
3. 选择系统支持的源语言和目标语言后进行测试。

Apple 离线翻译默认关闭。语言支持和语言包由当前 macOS 版本决定；如果缺少语言包，系统
可能会要求下载或返回错误。启用 Translation 框架后若翻译失败，Easydict 会返回错误，
不会自动切换到快捷指令。

macOS 13/14 或回退路径：安装快捷指令 Copy Chapter

使用 Safari 打开并安装
Easydict-Translate-V1.2.0：

1. 点击“获取快捷指令”。
2. 允许打开“快捷指令”App。
3. 点击“添加快捷指令”。
4. 确认快捷指令名称是 Easydict-Translate-V1.2.0。

不要重命名该快捷指令，也不要修改它的操作，否则 Easydict 无法按约定名称调用它。首次
调用时，macOS 可能会请求自动化权限，请允许 Easydict 控制“快捷指令”。

启用服务 Copy Chapter

打开 Easydict“设置 → 服务”，添加或启用 Apple 翻译。macOS 15+ 会在开启离线翻译时优先
使用 Translation 框架；关闭该开关或使用 macOS 13/14 时使用快捷指令路径。

常见问题 Copy Chapter

• 提示找不到快捷指令：确认名称完全是 Easydict-Translate-V1.2.0，并在“快捷指令”App
  中手动运行一次。
• 没有离线翻译结果：确认系统版本为 macOS 15+、离线翻译开关已启用，并已下载对应
  语言。
• 调用被拒绝：在“系统设置 → 隐私与安全性 → 自动化”中检查 Easydict 权限。
• 某种语言不可用：Apple 翻译的语言覆盖由 macOS 决定，可改用 Easydict 的其他服务。

User Docs Zh SPONSOR LIST (`docs/user-docs/zh/SPONSOR_LIST.md`) Copy Section

赞助列表

如果不希望用户名显示在列表中，请选择匿名方式。

感谢大家的支持！

Exec Plans Active Swift Migration (`docs/exec-plans/active/swift-migration.md`) Copy Section

Swift 迁移进度追踪

状态: active
最后复核: 2026-08-09
类型: 长期迁移路线图

迁移范围 Copy Chapter

本文记录长期迁移目标与进度。语言选择与现有 Objective-C 修复遵循
编码规范。

项目概述 Copy Chapter

Easydict 是一个 macOS 翻译和词典应用，正在进行从 Objective-C 到 Swift + SwiftUI 的逐步迁移。

✅ 已完成迁移 Copy Chapter

2024-2025 年迁移记录 Copy Section

翻译服务层

核心基类

字符串处理层

AI 服务层

基础设施层

工具扩展层

📊 迁移统计 Copy Section

• 翻译服务: 6/13 已完成 (46%)
• AI 服务: 14/14 已完成 (100%)
• 基础设施: 10/10 已完成 (100%)
• 工具扩展: 5/15 已完成 (33%)

✅ 已完成迁移 Copy Chapter

2025-01-29：NSString+EZHandleInputText Copy Section

• 目标: 成功创建 String+HandleInputText.swift
• 状态: ✅ 完成
• 实际时间: 1 天
• 成果:
  • 创建了 String+Split.swift 依赖文件
  • 创建了 String+HandleInputText.swift 主要实现
  • 创建了 String+HandleInputTextTests.swift 完整测试
  • 更新了 bridging header 移除旧 import
  • 修复了 AppleDictionary.swift 中的调用
  • 修复了所有 SwiftLint 违规和编译错误
  • 通过了所有 SwiftLint 检查（0 个问题）

2025-01-30：DarkMode 模块重构 Copy Section

• 目标: 使用 Swift 完全重写 DarkMode 模块
• 状态: ✅ 完成
• 实际时间: 1 天
• 成果:
  • 创建了 DarkModeManager.swift 统一的暗色模式管理器
  • 创建了 DarkModeProtocol.swift 提供响应式暗色模式协议
  • 创建了 NSObject+DarkMode.swift 和 NSView+DarkMode.swift 扩展
  • 使用 Combine 替代 ReactiveObjC，移除额外依赖
  • 更新了 AppDelegate.m 和 Configuration.swift 的调用
  • 移除了 4 个 Objective-C 文件和整个 DarkMode 目录
  • 更新了 PrefixHeader.pch 移除旧导入
  • 更新了 docs/exec-plans/active/swift-migration.md 记录迁移进度

2025-02-17：NSString+EZConvenience Copy Section

• 目标: 使用 Swift 重写 NSString+EZConvenience
• 状态: ✅ 完成
• 成果:
  • 新增 String+Convenience.swift，覆盖 URL 编码/解码、剪贴板操作、XML 转义、MD5、段落拆分等方法
  • 删除旧的 Objective-C 分类，更新 PCH、Bridging Header 和 Xcode 工程引用

2025-12-17：存储层重构 Copy Section

• 目标: 迁移存储相关类到 Swift
• 状态: ✅ 完成
• 成果:
  • 迁移 EZServiceInfo 到 Swift，添加 Codable 支持
  • 迁移 EZLocalStorage 到 Swift，使用现代属性访问器
  • 保持 @objcMembers 注解以兼容 Objective-C 代码
  • 更新 bridging header 移除不再需要的导入

2025-12-17：应用模型迁移 Copy Section

• 目标: 迁移 EZAppModel 到 Swift
• 状态: ✅ 完成
• 成果:
  • 从 objc/Legacy/ 迁移到 Swift/Model/
  • 添加全面的文档注释
  • 实现 NSSecureCoding 协议
  • 添加便捷的字典转换方法
  • 移除 MJExtension/KVC 依赖

2025-12-16：服务类型注册 Copy Section

• 目标: 迁移 EZServiceTypes 到 Swift
• 状态: ✅ 完成
• 成果:
  • 使用 ServiceTypes.swift 替换 EZServiceTypes.h/.m
  • 保持 API 兼容性，使用 @objc 属性
  • 保留单例模式和所有公共方法
  • 更新代码库中的所有导入语句

2025-12-18：类名规范化 Copy Section

• 目标: 重命名类以符合更清晰的命名约定
• 状态: ✅ 完成
• 成果:
  • 统一命名规范，提高代码可读性
  • 更新相关引用和文档

2025-12-17：DeepL API 清理 Copy Section

• 目标: 移除未使用的 DeepL API 枚举和相关代码
• 状态: ✅ 完成
• 成果:
  • 删除 EZDeepLTranslationAPI 枚举
  • 清理冗余代码，简化架构

2025-12-20：EZQueryResult 迁移 Copy Section

• Goal：将 EZQueryResult 及相关词条结果模型迁移到 Swift。
• Status: ✅ 已完成
• Outcome：
  • 在 Swift/Service/Model/EZQueryResult.swift 中添加 Swift 实现。
  • 移除 Objective-C EZQueryResult.h/.m，并将 ObjC 头文件更新为前置声明。
  • 更新工程引用以使用 Swift 实现。

2025-12-22：EZLog 和 EZDeviceSystemInfo 迁移 Copy Section

• Goal：将 EZLog 和 EZDeviceSystemInfo 迁移为 Swift 工具类。
• Status: ✅ 已完成
• Outcome：
  • 添加 Swift/Utility/Logging/EZLog.swift 和
    Swift/Utility/DeviceInfo/EZDeviceSystemInfo.swift。
  • 更新 ObjC 调用方以导入 Easydict-Swift.h。
  • 从 build phase 中移除遗留 ObjC 源文件。

2026-01-06：EZDetectManager 迁移 Copy Section

• Goal：将 EZDetectManager 迁移到 Swift，用于文本检测和 OCR 功能。
• Status: ✅ 已完成
• Outcome：
  • 添加包含完整实现的 Swift/Service/Model/DetectManager.swift。
  • 使用 @objc(EZDetectManager) 和 @objcMembers 保持 Objective-C 兼容性。
  • 添加方法的 async/await 版本，供 Swift 代码使用。
  • 更新 EZBaseQueryViewController.m 以导入 Easydict-Swift.h。
  • 更新 Easydict-Bridging-Header.h，注释掉旧的 Objective-C 导入。

📋 待迁移列表 Copy Chapter

⚠️ 重要提醒：以下所有 Objective-C 组件修改时必须先迁移到 Swift，禁止直接修改！

核心服务（高优先级） Copy Section

1. EZDetectManager ✅ - 文本检测管理器
   • 位置: Swift/Service/Model/DetectManager.swift
   • 影响: 语言检测和 OCR 功能
   • 优先级: 高
   • ✅ 已完成迁移到 Swift
   • 状态: ✅ 完成
   • 实际时间: 2026-01-06
   • 成果:
     • 创建了 Swift/Service/Model/DetectManager.swift 完整的 Swift 实现
     • 使用 @objc(EZDetectManager) 和 @objcMembers 保持 Objective-C 兼容性
     • 添加了 async/await 版本的方法支持 Swift 代码调用
     • 更新了 EZBaseQueryViewController.m 导入 Easydict-Swift.h
     • 更新了 Easydict-Bridging-Header.h 注释掉旧的 Objective-C 导入

应用架构（中优先级） Copy Section

2. AppDelegate - 应用代理

   • 位置: objc/AppDelegate.h/.m
   • 影响: 应用生命周期管理
   • 优先级: 中高
   • ⚠️ 重写时必须使用 Swift

3. EZWindowManager - 窗口管理器

   • 位置: objc/ViewController/Window/EZWindowManager.h/.m
   • 影响: 所有窗口功能
   • 优先级: 中高
   • ⚠️ 禁止修改，必须迁移到 Swift

4. EZLocalStorage - 本地存储 ✅

   • 已于 2025-12-17 迁移到 Swift
   • 新位置: objc/ViewController/Storage/EZLocalStorage.swift

UI 和交互（中优先级） Copy Section

5. EZBaseQueryViewController - 基础查询控制器
   • 位置: objc/ViewController/Window/BaseQueryWindow/EZBaseQueryViewController.m
   • 行数: ~1700 行
   • 影响: 核心用户界面
   • 优先级: 中
   • ⚠️ 禁止修改，必须迁移到 Swift

工具类（低优先级） Copy Section

8. NSString+EZChineseText - 中文文本处理
   • ⚠️ 禁止修改，必须迁移到 Swift
9. NSString+EZUtils - 字符串工具
   • ⚠️ 禁止修改，必须迁移到 Swift
10. NSString+EZSplit - 文本分割
    • ⚠️ 禁止修改，必须迁移到 Swift
11. NSColor+MyColors - 颜色扩展
    • ⚠️ 重写时必须使用 Swift
12. EZLanguageManager - 语言管理
    • ⚠️ 重写时必须使用 Swift
13. EZEventMonitor - 事件监控
    • ⚠️ 重写时必须使用 Swift
14. EZLog - 日志工具
    • ⚠️ 重写时必须使用 Swift
15. DarkModeManager - 深色模式
    • ⚠️ 重写时必须使用 Swift
16. MMLog - 日志框架
    • ⚠️ 重写时必须使用 Swift
17. MMCrash - 崩溃处理
    • ⚠️ 重写时必须使用 Swift

🚀 迁移计划 Copy Chapter

🚨 重要约束：禁止添加新的 Objective-C 代码，所有重写必须使用 Swift

第一阶段：核心功能 (Q1 2025) Copy Section

• Apple Dictionary
• EZQueryService (基类) - 已迁移至 Swift
• EZBaiduTranslate - 已迁移至 Swift
• EZDetectManager - 必须使用 Swift

第二阶段：应用架构 (Q2 2025) Copy Section

• EZLocalStorage - ✅ 已完成 (2025-12-17)
• AppDelegate - 必须使用 Swift
• EZWindowManager - 禁止修改，必须迁移到 Swift
• EZLanguageManager - 必须使用 Swift

第三阶段：用户界面 (Q3 2025) Copy Section

• EZBaseQueryViewController - 禁止修改，必须迁移到 Swift
• 其他 ViewController - 必须使用 Swift

第四阶段：工具和优化 (Q4 2025) Copy Section

• 所有 NSString 扩展 - 禁止修改，必须迁移到 Swift
• 日志和监控 - 必须使用 Swift
• 性能优化 - 必须使用 Swift
• 完全移除 Objective-C

📈 质量保证 Copy Chapter

代码质量 Copy Section

• ✅ SwiftLint 检查通过
• ✅ 单元测试覆盖
• ✅ 代码审查
• ✅ 性能测试

功能验证 Copy Section

• ✅ 所有原有功能保持不变
• ✅ 新增功能符合设计
• ✅ 兼容性测试
• ✅ 用户反馈收集

🚨 Objective-C 代码冻结政策 Copy Section

• ❌ 绝对禁止添加新的 Objective-C 文件
• 🔍 代码审查：拒绝任何新的 Objective-C 代码
• 🚫 Objective-C 代码仅允许 bug 修复
• 📈 Swift/SwiftUI 作为未来的唯一技术栈
• 🛡️ CI 检查：防止新的 .m/.h 文件提交

🎯 里程碑 Copy Chapter

• 2024年12月: 完成主要翻译服务迁移
• 2025年1月: 完成 Apple Dictionary 和 AI 服务
• 2025年3月: 完成核心服务层
• 2025年6月: 完成应用架构层
• 2025年9月: 完成 UI 层
• 2025年12月: 完全 Swift 化

🔗 相关资源 Copy Chapter

• GitHub Repository
• Swift 编码规范
• 应用架构
• 执行计划规范

最后更新: 2025-12-22

--- METRICS ---

• Files Extracted: 19
• Estimated Token Budget: ~18807 tokens
• Canonical Reference: https://codewiki.google/github.com/tisfeng/Easydict