## 📋 Table of Contents

• 📋 Overview
• ✨ Features
• 🎬 Demo
• 🚀 Installation
• 🔧 Usage
• ⚙️ Configuration
• 📁 Data Storage
• 🛠️ Building from Source
• 📊 Project Structure
• 🤝 Contributing
• ❓ FAQ
• 🧑‍💻 Tech Stack
• 🌐 Localization
• 📸 Screenshots
• 📄 License
• 🙏 Acknowledgements
• ☕ Support
• 🆕 What's New (v1.4.0)
• 🆕 What's New (v1.3.3)
• 🆕 What's New (v1.3.2)
• 🆕 What's New (v1.3.1)

🆕 What's New (v1.4.0)

• 🇫🇷 French Dictionary Support — Added French support via Collins French-English dictionary with Wiktionnaire fallback
• 🤖 Automatic Language Detection — Use natural queries like def world, def Enchanté, def слово
• 🌐 Multi-Language Latin Lookups — Configure LatinLanguages setting (e.g., "en,fr") to query multiple Latin-script dictionaries simultaneously
• ⚙️ Enhanced Configuration — Added LatinLanguages setting for flexible language selection
• 🔄 Improved Provider Routing — Better automatic matching for multilingual input

🆕 What's New (v1.3.3)

• 🇺🇦 Ukrainian Dictionary — Switched to Wiktionary https://uk.wiktionary.org as the primary source

📋 Overview

Definition is a plugin for Microsoft PowerToys Run that allows you to quickly lookup word definitions, phonetics, and synonyms without leaving your keyboard. Simply type def <word> to fetch definitions. The plugin supports English, French (Français), Ukrainian (Українська), and Chinese (中文) with automatic script detection — just type a word in any supported language and the plugin will prioritize results accordingly.

✨ Features

• 🔍 Instant Definitions: Get definitions in real-time via dictionaryapi.dev.
• ��� French Dictionary (Français): Lookup French words via Collins with Wiktionnaire fallback.
• ��� Ukrainian Dictionary (Українська): Lookup Ukrainian words using Wiktionary https://uk.wiktionary.org as the primary source.
• 🇨🇳 Chinese Dictionary (中文): Offline Chinese-English lookups powered by the embedded CC-CEDICT database (~124,000 entries) — no network needed.
• 🔄 Multi-Language Parallel Lookup: All configured providers are queried simultaneously; results are prioritized based on your query script (Latin, Cyrillic, or Chinese characters).
• 🤖 Automatic Language Detection: Use natural input like def world, def Enchanté, or def слово.
• 🔊 Pronunciation Audio: Play phonetic audio directly from your results.
• 📚 Phonetics & Synonyms: View phonetic spelling, synonyms, and antonyms.
• 📝 Usage Examples: See real-world examples of how words are used.
• ⚙️ Fully Configurable: JSON-based configuration with 15+ customizable settings.
• ⏱️ Delayed Execution: Shows loading indicator before fetching results.
• 💾 Smart Caching: In-memory cache for repeat lookups with configurable size and expiration.
• 🔄 Robust Network Handling: Exponential backoff retry logic for reliable API calls.
• 🌓 Theme Awareness: Automatically switches icons for light/dark mode.
• 📋 Rich Context Menu: Copy definitions, play pronunciation, open source URL, or search for related words.
• 🔄 Cancellable Requests: Automatically cancels previous requests when typing new queries.
• 🌐 Wiktionary Integration: Open any word in Wiktionary for additional information and translations.

🎬 Demo

🚀 Installation

Prerequisites

• PowerToys Run installed (v0.70.0 or later)
• Windows 10 (build 22621) or later
• .NET 9.0 Runtime (included with Windows 11 22H2 or later)
• Internet connection (for API access)

Quick Install (Manual)

1. Download the appropriate ZIP for your system architecture:

   • x64 version
   • ARM64 version

2. Extract the ZIP to:

   %LOCALAPPDATA%\Microsoft\PowerToys\PowerToys Run\Plugins\
   

   Typical path: C:\Users\YourUsername\AppData\Local\Microsoft\PowerToys\PowerToys Run\Plugins\

3. Restart PowerToys (right-click the PowerToys icon in the system tray and select "Restart").

4. Open PowerToys Run (Alt + Space) and type def <word>.

Manual Verification

To verify the plugin is correctly installed:

1. Open PowerToys Settings
2. Navigate to PowerToys Run > Plugins
3. Look for "Definition" in the list of plugins
4. Ensure it's enabled (toggle should be ON)

🔧 Usage

1. Activate PowerToys Run (Alt + Space).
2. Type:
   • def to see instructions.
   • def <word> to lookup definitions automatically based on language/script.
3. Press Enter to fetch results.
4. Use Ctrl + C to copy a definition.
5. Right-click a result to:
   • Copy definition with Ctrl + C
   • Play pronunciation audio
   • Open the word in Wiktionary
   • Search for related words

⚙️ Configuration

The plugin supports extensive customization through a config.json file that's automatically created in the plugin directory. Changes take effect immediately without requiring a restart.

Available Settings

Setting	Default	Description
Language	"en"	Default language ("en", "fr", "uk", or "zh")
ApiEndpoint	https://api.dictionaryapi.dev/api/v2/entries/en/	English dictionary API endpoint
LatinLanguages	"en,fr"	Comma-separated Latin-script languages to query (e.g. "en,fr" for both)
UkrainianApiEndpoint	https://sum.in.ua/s/	Ukrainian dictionary fallback endpoint (sum.in.ua)
ChineseApiEndpoint	https://www.mdbg.net/chinese/dictionary?...	Chinese dictionary reference URL
CacheMaxSize	100	Maximum number of cached word lookups
HttpTimeoutSeconds	10	Timeout for API requests in seconds
CacheExpirationMinutes	30	How long to keep cache entries
EnableAudioPlayback	true	Enable/disable pronunciation audio
EnableClipboardOperations	true	Enable/disable copy to clipboard
TextTruncateLength	30	Maximum text length in context menu
EnableVerboseLogging	false	Enable detailed debug logging
MaxResultsPerMeaning	3	Maximum definitions per word meaning
ShowExamplesInResults	true	Show usage examples
ShowSynonymsInResults	true	Show synonyms
ShowAntonymsInResults	true	Show antonyms

Example Configuration

{
  "Language": "en",
  "CacheMaxSize": 200,
  "HttpTimeoutSeconds": 15,
  "EnableAudioPlayback": true,
  "ShowSynonymsInResults": false,
  "ShowAntonymsInResults": false,
  "ShowExamplesInResults": true,
  "MaxResultsPerMeaning": 2,
  "EnableVerboseLogging": true
}

Note: You don't need to change Language to use Ukrainian or Chinese. The plugin automatically detects the script of your query. Cyrillic input (e.g. def слово) will prioritize Ukrainian results, Chinese characters will prioritize Chinese results, and Latin input will query the languages listed in LatinLanguages.

Multi-language Latin lookups: Set "LatinLanguages": "en,fr" to query both English and French dictionaries simultaneously for Latin-script words.

📁 Data Storage

All settings are stored in the standard PowerToys settings file (no additional data files created).

🛠️ Building from Source

git clone https://github.com/ruslanlap/PowerToysRun-Definition.git
cd PowerToysRun-Definition/Definition
dotnet build
# To package:
dotnet publish -c Release -r win-x64 --output ./publish
zip -r Definition-v1.4.0-x64.zip ./publish

📊 Project Structure

PowerToysRun-Definition/
├── data/                            # Plugin assets (icons, demos)
│   ├── definition.dark.png
│   ├── definition.logo.png
│   ├── demo-definition.gif
│   └── demo-definition-2.gif
├── Definition/                      # Plugin source
│   ├── Community.PowerToys.Run.Plugin.Definition/
│   │   ├── Images/
│   │   │   ├── definition.dark.png
│   │   │   └── definition.light.png
│   │   ├── Main.cs
│   │   └── plugin.json
│   └── Community.PowerToys.Run.Plugin.Definition.csproj
└── README.md

🤝 Contributing

Contributions are welcome! Here's how you can help:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m 'Add amazing feature'
4. Push to the branch: git push origin feature/amazing-feature
5. Open a Pull Request

Please make sure to update tests as appropriate.

Contributors

• ruslanlap - Project creator and maintainer

❓ FAQ

Does the plugin require internet access?

English, French, and Ukrainian lookups require internet access (dictionaryapi.dev, collinsdictionary.com/wiktionary, and goroh.pp.ua respectively). Chinese lookups use an embedded offline dictionary and work without internet. All results are cached in memory for subsequent lookups.

How do I change the plugin's theme?

The plugin automatically adapts to your PowerToys theme (light/dark). Icons are dynamically loaded based on your current system theme.

Are definitions cached?

Yes, definitions are cached in memory during the current session (up to 100 entries) to improve performance and reduce API calls.

Can I customize the dictionary source?

Yes. You can change ApiEndpoint (English) and UkrainianApiEndpoint (Ukrainian) in config.json. Chinese lookups use the embedded CC-CEDICT database.

How do I look up Ukrainian words?

Just type def слово (any Ukrainian word in Cyrillic). The plugin automatically detects Cyrillic script and prioritizes Ukrainian results. The primary source is goroh.pp.ua (Горох — українські словники, 500,000+ words) with sum.in.ua as fallback. No special API key is needed.

Which languages are supported?

Four languages are supported out of the box:

• English — via dictionaryapi.dev (free REST API)
• French (Français) — via Collins French-English Dictionary (primary) + Wiktionnaire (fallback)
• Ukrainian (Українська) — via Wiktionary (primary) + goroh.pp.ua (fallback)
• Chinese (中文) — via embedded CC-CEDICT database (~124,000 entries, fully offline)

Why does the plugin show "Looking up..." before showing results?

The plugin implements IDelayedExecutionPlugin which shows a loading indicator while fetching results from the API. This provides immediate feedback while the request is processing.

How do I play the pronunciation audio?

Right-click on any definition result and select "Play Pronunciation" from the context menu (only available if the API provides audio for that word).

How can I see more information about a word?

Right-click on any result and select "Open Source URL in Browser" to view the word in Wiktionary, which provides additional information, translations, and etymology.

What's the difference between WinGet and manual installation?

WinGet installation: Run one command (winget install ruslanlap.DefinitionForCommandPalette) and WinGet handles everything - downloads, verifies, installs, and registers the extension automatically. You also get automatic update notifications when new versions are released.

Manual installation: Download ZIP file, extract to specific folder, restart PowerToys. You need to check for updates manually on GitHub.

WinGet is recommended for most users as it's more convenient and ensures you always have the latest version.

🔆 Feature Spotlight

This section highlights some of the most powerful features of the Definition plugin:

🧑‍💻 Tech Stack

Technology	Description
C# / .NET 9.0	Primary language and runtime
PowerToys Run API	IPlugin, IDelayedExecutionPlugin, IContextMenu interfaces
HttpClient	API requests with timeout handling
System.Text.Json	JSON parsing
WPF MediaPlayer	Audio playback
System.Threading	Asynchronous operations
GitHub Actions	CI/CD with multi-architecture builds

🌐 Supported Languages

The plugin supports four dictionary sources with automatic script detection:

Language	Source	Method	Internet Required
English	dictionaryapi.dev	REST API (JSON)	Yes
Français	Collins (primary) + Wiktionnaire (fallback)	HTML parsing + MediaWiki API	Yes
Українська	Wiktionary (primary) + goroh.pp.ua (fallback)	API + HTML scraping	Yes
中文	CC-CEDICT (embedded, ~124,000 entries)	Offline database	No

How it works: When you type def <word>, the plugin detects the script of your input and queries the appropriate providers:

• Cyrillic input (def слово) → Ukrainian results prioritized
• Chinese characters (def 你好) → Chinese results prioritized
• Latin input (def hello / def enchanté) → Queries languages from LatinLanguages config (default: English + French)

Note on Ukrainian: There is no public REST API for Ukrainian dictionaries. The plugin uses goroh.pp.ua (Горох — українські словники) as the primary source — a comprehensive Ukrainian dictionary with 500,000+ words, definitions, examples, synonyms, and more. Cyrillic words are used directly in the URL (e.g. def слово → https://goroh.pp.ua/Тлумачення/слово). If goroh.pp.ua is unavailable, sum.in.ua is used as fallback.

📸 Screenshots

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgements

• Microsoft PowerToys team for the amazing launcher
• dictionaryapi.dev for providing the free English dictionary API
• Collins Dictionary for French-English dictionary content
• Wiktionnaire for French fallback definitions
• goroh.pp.ua for Горох — українські словники (primary Ukrainian dictionary source) NEED API write to developers of goroh.pp.ua to add API to the plugin.
• sum.in.ua for the Словник української мови (Ukrainian dictionary fallback) NOT WORKING.
• MDBG.net for providing access to CC-CEDICT Chinese-English dictionary
• Wiktionary for comprehensive word information and translations
• All contributors who have helped improve this plugin

☕ Support

If you find this plugin useful and would like to support its development, you can buy me a coffee:

🆕 What's New (v1.2.2)

• 🇺🇦 Ukrainian Dictionary Support — Integrated with sum.in.ua explanatory dictionary. NOT WORKING.
• 🇨🇳 Chinese Dictionary Support — Integrated with MDBG.net (CC-CEDICT data) for Chinese-English lookups.
• 🔄 Parallel Lookup — Simultaneously fetch results from English, Ukrainian, and Chinese sources.
• 🎯 Smart Prioritization — Results are automatically prioritized based on the query script (Cyrillic, Chinese, or Latin).
• 🏗️ Improved Architecture — Refactored to a provider-based system for better extensibility.
• 🩹 Better Reliability — Enhanced error handling ensures one failed provider doesn't break the entire search.
• 📦 Dependencies — Added HtmlAgilityPack for robust HTML parsing of Ukrainian and Chinese results.

🆕 What's New (v1.2.1)

• ⚙️ Fully Configurable Settings — JSON-based configuration system with runtime updates:
  • config.json with 11 customizable settings
  • Toggle synonyms, antonyms, examples display
  • Configure cache size, timeouts, and result limits
  • Enable/disable audio playback and clipboard operations
  • Settings reload automatically without restart
• 🔄 Robust Network Retry Logic — Enhanced reliability for API calls:
  • Exponential backoff with smart retry conditions
  • Handles transient network errors gracefully
  • Configurable retry attempts and delays
• 🛠️ Improved Clipboard Operations — Better threading and reliability:
  • Custom STA task scheduler for thread safety
  • Enhanced error handling and timeout protection
  • Configurable clipboard operations enable/disable
• 🔧 Configuration Bug Fix — Settings now actually work:
  • Fixed issue where config.json changes were ignored
  • All configuration options now properly respected
  • Dynamic reloading ensures immediate effect
• 📊 Enhanced Debugging — Better troubleshooting capabilities:
  • Verbose logging option for detailed diagnostics
  • Improved error reporting throughout the plugin
  • Better network error categorization

---