Features | Quick Start | Settings | Usage Guide | Privacy | Install | FAQ | Development
Selection Translator is an Obsidian plugin for translating selected Markdown editor and PDF text with selectable AI and traditional translation providers plus automatic dictionary lookup.
- Translate selected Markdown editor or selectable PDF text from the command palette, a hotkey, the ribbon button, or the Markdown editor context menu.
- Keep the floating popover open while selecting more text; the new Markdown or PDF selection is translated automatically.
- Edit the selected source text in the popover and translate again.
- Automatically look up one selected English word with the configured dictionary provider and play UK/US pronunciations when available.
- Set default source and target languages in plugin settings.
- Use
Autoas the source language when you want a supported provider to detect the input language.
- Stream translation progress, errors, and results in a draggable and resizable popover.
- Use compact header buttons to copy the full result, retry translation, or close the popover.
- Select any part of the translation result and copy it with native keyboard or context-menu copy.
- Header layout is compact for desktop and narrow mobile screens.
- Choose the text translation provider yourself. OpenAI-compatible providers, Bing Translate (Microsoft Translator), Google Cloud Translation, DeepL, Baidu Translate, and Youdao Translate are selectable options.
- Configure the credentials required by the selected provider.
- OpenAI-compatible providers support prompt, temperature, and streaming output. Traditional translation APIs return the translated result when the provider request completes.
- One selected English word automatically uses the configured dictionary provider. Youdao Dictionary, Bing Dictionary, and Cambridge Dictionary are selectable and do not require an API key.
- Test the provider configuration before translating.
- Plugin UI follows Obsidian's app language for English and Simplified Chinese.
- Install the plugin with BRAT or manual installation.
- Open Settings -> Community plugins -> Selection Translator.
- Choose a Translation provider.
- Choose a Dictionary provider if you want a provider other than Youdao Dictionary.
- Configure the credentials required by the translation provider.
- Set default Source language and Target language.
- Select Test to verify the translation provider configuration.
- Select text in a Markdown editor or selectable PDF text in Obsidian's PDF view.
- Run Translate selection from the command palette, a hotkey, the ribbon button, or the editor context menu.
The default prompt translates from Auto into Chinese (Simplified) and returns only the translated text.
The settings page is grouped into Provider, Dictionary config, and Popover config tabs.
| Setting | Default | Description |
|---|---|---|
| Translation provider | OpenAI-compatible |
Selects which provider handles non-dictionary translation requests. |
| Source language | Auto |
Default source language. Use Auto for provider-side detection when supported. |
| Target language | Chinese (Simplified) |
Default target language. |
| OpenAI-compatible API base URL | https://api.openai.com/v1 |
Provider base URL. The plugin appends /chat/completions when needed. |
| OpenAI-compatible API key | empty | Bearer token for the configured OpenAI-compatible provider. |
| OpenAI-compatible model | empty | Model name supported by your provider. |
| OpenAI-compatible prompt | built in | Translation instruction for OpenAI-compatible providers. Use {sourceLanguage} and {targetLanguage} for the configured languages. |
| OpenAI-compatible temperature | 0.2 |
Lower values keep OpenAI-compatible translations more deterministic. |
| Maximum selection length | 4000 |
Blocks accidental large sends. This setting is shown with OpenAI-compatible options but applies before every provider request. |
| Bing/Microsoft Translator key | empty | Subscription key for the Microsoft Translator resource used by Bing Translate. |
| Bing/Microsoft Translator region | empty | Resource region, such as eastasia or global. |
| Bing/Microsoft Translator endpoint | https://api.cognitive.microsofttranslator.com |
Translator endpoint. |
| Google Cloud Translation API key | empty | API key for Google Cloud Translation Basic v2. |
| DeepL Auth Key | empty | Authentication key from your DeepL account. |
| DeepL API base URL | https://api-free.deepl.com |
Use https://api.deepl.com for DeepL Pro. |
| Baidu Translate app ID | empty | App ID from Baidu Translate Open Platform. |
| Baidu Translate secret key | empty | Secret key from Baidu Translate Open Platform. |
| Youdao Translate app key | empty | App key from Youdao Zhiyun translation service. |
| Youdao Translate app secret | empty | App secret from Youdao Zhiyun translation service. |
| Test API configuration | - | Sends a short translation request to verify the selected provider configuration. |
The public Google Translate and Bing Translator websites can be free for manual use, but this plugin uses official provider APIs for those translation providers. API access requires provider credentials even when the provider offers a free quota or free tier. Dictionary lookup is automatic for one selected English word and uses the configured dictionary website without API credentials.
| Provider | API access note | Key setup | Pricing |
|---|---|---|---|
| Bing Translate (Microsoft Translator) | Azure Translator API has an F0 free tier, but it still requires an Azure Translator resource key, endpoint, and sometimes region. | Create a Translator resource | Azure Translator pricing |
| Google Cloud Translation | Cloud Translation has monthly free usage credits, but API calls require a Google Cloud project, billing, enabled API, and credentials. | Cloud Translation setup, Create API keys | Cloud Translation pricing |
| DeepL | Requires a DeepL API account and Auth Key. Use https://api-free.deepl.com for API Free and https://api.deepl.com for API Pro. |
DeepL API authentication | DeepL API plans |
| Baidu Translate | Requires a Baidu Translate Open Platform App ID and secret key. | Baidu Translate API docs, Open Platform | Baidu Translate products |
| Youdao Translate | Requires a Youdao Zhiyun app key and app secret. | Youdao new user guide, App management, Text translation API docs | Youdao text translation pricing |
| Dictionary lookup | No API key is required. It sends one selected English word to the configured dictionary website and uses pronunciation audio URLs from that provider when available. | Youdao Dictionary, Bing Dictionary, Cambridge Dictionary | - |
| Setting | Default | Description |
|---|---|---|
| Dictionary provider | Youdao Dictionary |
Selects which dictionary website handles one-word dictionary lookup. Options: Youdao Dictionary, Bing Dictionary, Cambridge Dictionary. |
| Setting | Default | Description |
|---|---|---|
| Show selected text in popover | enabled | Shows selected text as an editable field before retrying. |
- Select text in Markdown or a selectable PDF text layer.
- Run Translate selection.
- Read the streaming result in the popover.
- Select part of the result if you only need to copy a specific phrase or paragraph.
- Select one English word in Markdown or a selectable PDF text layer.
- Run Translate selection.
- Use the pronunciation buttons in the result header to play UK or US audio.
- Open the plugin settings.
- Change Source language and Target language in the Provider tab.
- Run Translate selection again. Later translations use the saved language values.
Select the ribbon button before selecting text. The popover opens in a waiting state, then translates the next Markdown editor or PDF selection.
PDF support requires a selectable PDF text layer. Scanned pages without OCR text cannot be translated by selection.
This plugin does not collect telemetry and does not scan your vault.
When you translate selected Markdown or PDF text, only the selected text is sent to the translation provider currently selected in plugin settings. When the selection is one English word, that word is sent to the configured dictionary provider instead and pronunciation audio is loaded from that provider when available. Do not translate sensitive content unless you trust that provider.
Provider credentials are stored locally in Obsidian plugin data through saveData(). Secret fields are rendered as password fields in settings, but Obsidian plugin data is local plaintext storage, not encrypted storage. The plugin does not log provider credentials.
This plugin is distributed as a beta plugin through GitHub releases. Install it with the Obsidian BRAT plugin:
- Install and enable BRAT from Obsidian's community plugins.
- Open Settings -> BRAT -> Beta Plugin List.
- Select Add Beta plugin.
- Enter this repository URL:
https://github.com/Zhruoshui/obsidian-selection-translator
- Enable Selection Translator in Settings -> Community plugins.
BRAT installs the release assets from GitHub. Each release must include main.js, manifest.json, and styles.css.
Download main.js, manifest.json, and styles.css from the latest GitHub release, then copy them to:
<Vault>/.obsidian/plugins/selection-translator/
Reload Obsidian and enable the plugin in Settings -> Community plugins.
- Confirm the API base URL is correct and reachable.
- Confirm the credentials are valid for the selected provider.
- For OpenAI-compatible providers, confirm the model name exists on that provider.
- Confirm text is selected in the active Markdown editor or a selectable PDF text layer.
- Try the command palette command Translate selection.
- For PDF files, confirm the PDF has selectable text and is not only a scanned image.
- Use the default prompt or include
{sourceLanguage}in your custom prompt. - The plugin also adds missing language direction context before custom prompts that omit a language placeholder.
During development, symlink the repository into the vault's plugins directory so you can run npm run build and reload Obsidian without copying files manually.
Linux / macOS:
ln -s /path/to/obsidian-selection-translator "<Vault>/.obsidian/plugins/selection-translator"Windows (requires administrator or Developer Mode):
mklink /D "<Vault>\.obsidian\plugins\selection-translator" "C:\path\to\obsidian-selection-translator"You can also create a directory junction on Windows (no admin required):
mklink /J "<Vault>\.obsidian\plugins\selection-translator" "C:\path\to\obsidian-selection-translator"After linking, npm run build compiles main.js into the plugin folder directly. Reload Obsidian or disable and re-enable the plugin to pick up changes.
Install dependencies:
npm installRun a production build:
npm run buildRun lint:
npm run lintThis project is licensed under the MIT License. You are free to use, modify, and distribute it, provided you retain the original copyright notice and license statement.
Thanks to the LinuxDo community (https://linux.do) for their support.