docs/en/GUIDE.md
This document contains detailed feature descriptions, configuration methods, and usage tips for Easydict.
You can install it using one of the following two methods.
The latest version of Easydict supports macOS 13.0+, if the system version is macOS 11.0+, please use 2.7.2.
Download the latest release of the app.
Thanks to BingoKingo for the initial installation version.
brew install --cask easydict
If you are a developer, or you are interested in this project, you can also try to build and run it manually. The whole process is very simple, even without knowing macOS development knowledge.
<details> <summary> Build Steps </summary> <p>Easydict.xcworkspace file with Xcode (⚠️⚠️⚠️ Note that it is not Easydict.xcodeproj ⚠️⚠️⚠️).Cmd + R to compile and run.The following steps are optional and intended for development collaborators only.
If you often need to debug permission-related features, such as word fetching or OCR, you can choose to run it with your own Apple account, change DEVELOPMENT_TEAM`` in the Easydict-debug.xcconfig file to your own Apple Team ID (you can find it by logging in to the Apple developer website) and `CODE_SIGN_IDENTITY to Apple Development.
Be careful not to commit the `Easydict-debug.xcconfig`` file; you can ignore local changes to this file with the following git command
git update-index --skip-worktree Easydict-debug.xcconfig
Xcode 13+, macOS Big Sur 11.3+. To avoid unnecessary problems, it is recommended to use the latest Xcode and macOS version https://github.com/tisfeng/Easydict/issues/79
[!NOTE] Since the latest code uses the String Catalog feature, Xcode 15+ is required to compile. If your Xcode version is lower, please use the xcode-14 branch, note that this is a fixed version branch, not maintained.
If the run encounters the following error, try updating CocoaPods and then pod install.
</p> </details>DT_TOOLCHAIN_DIR cannot be used to evaluate LD_RUNPATH_SEARCH_PATHS, use TOOLCHAIN_DIR instead
Once Easydict is launched, in addition to the main window (hidden by default), there will be a menu icon, and clicking on the menu option will trigger the corresponding actions, as follows:
<div> </div>| Ways | Description | Preview |
|---|---|---|
| Mouse select translate | The query icon is automatically displayed after the word is selected, and the mouse hovers over it to query | |
| Shortcut select translate | After selecting the text to be translated, press the shortcut key (default ⌥ + D) | |
| Screenshot translate | Press the screenshot translate shortcut key (default ⌥ + S) to capture the area to be translated | |
| Input translate | Press the input translate shortcut key (default ⌥ + A, or ⌥ + F), enter the text to be translated, and Enter key to translate | |
| Silent Screenshot OCR | Press the Silent Screenshot shortcut key（default ⌥ + ⇧ + S）to capture the area, the OCR results will be copied directly to the clipboard |
Currently, multiple mouse quick word selection methods are supported: double-click word selection, mouse drag word selection, triple-click word selection (paragraph) and Shift word selection (multiple paragraphs). In some applications, mouse drag word selection and Shift word selection may fail, in which case you can switch to other word selection methods.
The shortcut key to select words can work normally in any application. If you encounter an application that cannot select words, you can open an issue to solve it https://github.com/tisfeng/Easydict/issues/84
The flow of the crossword function: Accessibility > AppleScript > simulated shortcuts, giving priority to the secondary function Accessibility fetching, and if Accessibility fetching fails (unauthorized or not supported by the application), if it is a browser application (e.g. Safari, Chrome), it will try to use AppleScript fetching. If the AppleScript fetching still fails, then the final forced fetching is done - simulating the shortcut Cmd+C to fetch the word.
Therefore, it is recommended to turn on the Allow JavaScript in Apple events option in your browser to avoid event blocking on certain web pages, such as those with forced copyright information, and to optimize the word fetching experience.
For Safari users, it is highly recommended that this option be turned on, as Safari does not support Accessibility fetching, and AppleScript fetching is far superior to simulating shortcuts.
<div> </div>Select Translate requires the Auxiliary Accessibility. The mouse stroke function only triggers the application of auxiliary accessibility permission when it is used for the first time, and the automatic stroke translation function can only be used normally after authorization.
For screenshot Translate, you need to enable Screen Recording permission. The application will only automatically pop up a permission application dialog box when you use Screenshot Translation for the first time. If the authorization fails, you need to turn it on in the system settings manually.
Currently, only the system OCR is supported. OCR supported languages: Simplified Chinese, Traditional Chinese, English, Japanese, Korean, French, Spanish, Portuguese, German, Italian, Russian, Ukrainian.
Currently support macOS system TTS, Bing, Google, Youdao, and Baidu online TTS service.
By default, the application uses Youdao TTS, but users have the option to select their preferred TTS service in the settings.
Due to its impressive performance with English words, Youdao TTS is the recommended choice for such content, while the default TTS service remains in use for other languages.
It's worth noting that, apart from the system TTS, all other TTS services are unofficial interfaces and may experience instabilities from time to time
Easydict seamlessly integrates with the dictionaries available in the macOS Dictionary App, including popular options like the Oxford English-Chinese-Chinese-English Dictionary (Simplified Chinese-English) and the Modern Chinese Standard Dictionary (Simplified Chinese). To use these dictionaries, simply enable them through the Dictionary App settings page.
Furthermore, Apple Dictionary offers support for custom dictionaries, allowing you to import third-party options such as the Concise English-Chinese Dictionary, Longman Dictionary of Contemporary Advanced English, and more. These can be added to your system by importing dictionaries in the .dictionary format.
For detailed information, please see How to use macOS system dictionary in Easydict
<table> <td> <td> <td> </table>Version 1.3.0 starts to support OpenAI translation, which requires an OpenAI API key.
If you don't have your own OpenAI APIKey, you can use some open source projects to convert third-party LLM interfaces to standard OpenAI interfaces, so that you can use them directly in Easydict.
For example, one-api, one-api is a good OpenAI interface management open source project, supports many LLM interfaces, including Azure, Anthropic Claude, Google Gemini, ChatGLM, Baidu Wenwen, and so on. ChatGLM, Baidu Wenxin Yiyin, Xunfei Starfire Cognition, Ali Tongyi Thousand Questions, 360 Intelligent Brain, Tencent Mixed Meta, Moonshot AI, Groq, Zero-One Everything, Step Star, DeepSeek, Cohere , etc., can be used for the secondary distribution of the management key, only a single executable file, has been packaged with a good Docker image, one-key deployment, out-of-the-box .
[!IMPORTANT] 2.6.0 version implements a new SwiftUI settings page (macOS 13+ support), which supports configuring the service API key in a GUI way, other system verions need to be configured using commands in Easydict's input box.
[!TIP] If your computer hardware supports it, it is recommended to upgrade to the latest macOS system to enjoy a better user experience.
Currently, OpenAI translation supports three query modes: word lookup, sentence translation, and long-text translation. They are all enabled by default, while words and sentences can be disabled.
<table> <td> <td> <td> </table>A quick tip: If you only want to exclude occasional sentence analysis without turning off the Sentence mode, simply append a tilde (~) after [Sentence]. This will convert it into the Translation mode.
Currently, some LLM service vendors provide free AI models with restrictions, such as Groq, Google Gemini, and so on.
To make it easier for new users to get a taste of using these big model AI translations, we have added a built-in AI translation service, which can be used directly without the need to configure the API key.
However, please note that the built-in models have some limitations (mainly on the free amount), we do not guarantee that they can be used stably all the time, and we recommend users to use AxonHub to build their own LLM service.
Gemini Translation requires an API key, which can be obtained for free on the official website Console.
DeepL free version web API has a frequency limit for single IP, frequent use will trigger 429 too many requests error, so version 1.3.0 adds support for DeepL official API, but the interface has not been written yet, and needs to be enabled through command.
If you have DeepL AuthKey, it is recommended to use personal AuthKey, so as to avoid frequency limits and improve user experience. If not, you can use the way of switching proxy IP to avoid 429 error.
[!NOTE] Using a new proxy IP is a generic solution that works for other frequency-limited services.
If you don't have your own AuthKey and need to use DeepL translation a lot, you can consider deploying your own interface service that supports DeepL, or using a third-party service that supports DeepL.
The way to customize the DeepL API URL is equivalent to the DeepL official AuthKey API form in Easydict.
Easydict supports the DeepLX API, see #464 for details.
The web version API is used by default, and the personal AuthKey will be used when the web version API fails (if any)
Use personal AuthKey first, and use web version API when it fails. If you use DeepL frequently, it is recommended to use this method, which can reduce one failed request and improve response speed.
Only use personal AuthKey
Tencent Translate requires an APIKey, for ease of use, we have built-in a key, this key has a limit on the amount, not guaranteed to be available all the time.
It is recommended to use your own APIKey, each registered user of Tencent Translate is given 5 million characters of traffic per month, which is enough for daily use.
At present, Bing Translator uses a web interface. When encountering a 429 error due to triggering rate limits, you can extend the usage by manually setting request cookies, aside from switching proxies. The exact duration of the time extension is currently unclear.
The specific steps are, to use the browser to log in Bing Translator, then get the cookie in the console by running the following command.
cookieStore.get("MUID").then(result => console.log(encodeURIComponent("MUID=" +result.value)));
[!NOTE] Bing TTS also uses a web API, which is also easy to trigger interface restrictions and does not report errors, so if you set Bing to the default TTS, it is recommended to set cookies.
Niutrans requires an API key, for ease of use, we have built-in a key, this key has a limit on the amount, not guaranteed to be available all the time.
It is recommended to use your own API key, each registered user of Niutrans is given 200,000 characters of traffic per day.
Lingocloud needs an Token, for ease of use, we have built-in a token, this token has a limit on the amount, not guaranteed to be available all the time.
It is recommended to use your own Token, each registered user of Lingocloud is given 100,000 characters of traffic per day.
Ali Translate requires an API key, for ease of use, we have built-in a key, this key has a limit on the amount, not guaranteed to be available all the time.
It is recommended to use your own API key, each registered user of Ali Translate is given 100,000 characters of traffic per day.
Doubao Translation requires an API key, which can be applied for at the Volcano Ark Platform.
It is recommended to use your own API key. Each registered user is given 500,000 characters of free translation quota.
Easydict supports fast lookup for URL scheme: easydict://query?text=xxx, such as easydict://query?text=good.
If the query content xxx contains special characters, URL encoding is needed, such as easydict://query?text=good%20girl.
[!WARNING] The old version of easydict://xxx may cause problems in some scenarios, so it is recommended to use the complete URL Scheme: easydict://query?text=xxx
You need to install PopClip first, then select the following code block, PopClip will show "Install Extension Easydict", just click it.
-- #popclip
-- name: Easydict
-- icon: iconify:ri:translate
-- language: applescript
tell application "Easydict"
launch
open location "easydict://query?text={popclip text}"
end tell
The settings page provides some preference setting modifications, such as automatically playing word pronunciation after turning on a query, modifying translation shortcut keys, turning on and off services, or adjusting the order of services, etc.
Easydict has 3 types of Windows and you can set different services for each of them.
Easydict has some in-app shortcuts to help you use it more efficiently.
Unlike the translation shortcut keys that are globally effective, the following shortcuts only take effect when the Easydict window is in the foreground.
<div style="display: flex; justify-content: space-between;"> </div>Enter: After entering the text, press Enter to start the query.Shift + Enter: Enter a new line.Cmd + ,: Open the settings page.Cmd + Q: Quit the app.Cmd + K: Clear the input text.Cmd + Shift + K: Clear the input box and query results, the same as clicking the clear button in the lower right corner of the input text.Cmd + I: Focus on the input text.Cmd + Shift + C: Copy query text.Cmd + S: Play the pronunciation of the query text.Cmd + R: Query again.Cmd + T: Toggle translation language.Cmd + P: Pin the window.Cmd + W: Close the window.Cmd + Enter: By default, the Google search engine is opened, and the content to be searched is the input text, which is equivalent to manually clicking the browser search icon in the upper right corner.Cmd + Shift + Enter: If the Eudic App is installed on the computer, an Eudic icon will be displayed to the left of the Google icon, and the action is to open the Eudic App to query.As long as the query window is activated, you can open the settings page by shortcut key Cmd + ,. If you hide the menu bar icon, you can reopen it in this way.
If you find that the OCR result is incorrect, you can correct the OCR result by clicking the "Detected xxx" button to specify the recognition language.
<div style="display:flex;align-items:flex-start;"> </div>Looking up words and translating text is a very useful function in daily life. I have used many translation dictionaries, but I was not satisfied until I met Bob. Bob is an excellent translation software, but it is not open source and no longer provides free application updates since it hit the Apple Store.
As a developer and beneficiary of a lot of open source software, I think that there should be a free open source version of Bob in the world, so I made Easydict.
Now I use Easydict a lot every day, I like it very much, and I hope more people can know it and use it.
Open source makes the world better.
If you are interested in this project, we welcome you to contribute to the project, and we will provide help as much as possible.
If you think there is room for improvement in the project, or if you have new ideas for features, please submit a PR:
feat/xxx for new features, and fix/xxx for bug fixesdev or main directly: Please create a new branch from the corresponding base branch, then submit a PRWe are planning to migrate the project from Objective-C to Swift. If you are interested in Swift/SwiftUI development, welcome to participate in this migration effort. See #194.