Select any text, anywhere in Windows. Press one key. It's translated in place.
هر متنی را، هر جای ویندوز انتخاب کنید. یک کلید بزنید. همانجا ترجمه میشود.
Persian ⇄ English · System-tray app · Frameless dark UI · Gemini / AvalAI
(or browse all versions on the Releases page · یا همهی نسخهها را در صفحهی Releases ببینید)
ParsiSwap یک ابزار سبک است که در پسزمینهی ویندوز اجرا میشود و در سینی سیستم (System Tray) مینشیند.
در هر برنامهای — Word، مرورگر، Notepad، سرچبار ویندوز، چت، هر جا — کافی است متنی را انتخاب کنید و کلید میانبر را بزنید. متن انتخابشده بلافاصله بین فارسی و انگلیسی ترجمه میشود و دقیقاً در همانجا جایگزین میگردد. کلیپبورد شما هم دستنخورده باقی میماند.
| قابلیت | توضیح |
|---|---|
| 🌐 ترجمهی دوطرفهی هوشمند | متن فارسی ← انگلیسی، متن انگلیسی ← فارسی (تشخیص خودکار زبان) |
| ⌨️ کلید میانبر سراسری | در همهی برنامههای ویندوز کار میکند، قابل تغییر |
| 🎭 انتخاب لحن ترجمه | پیشفرض، دوستانه، محاورهای، حرفهای، رسمی |
| 🔌 چند سرویسدهنده | Gemini (گوگل)، AvalAI (آدرس خودکار)، یا هر واسط سازگار با OpenAI |
| 📋 حفظ کلیپبورد | بعد از ترجمه، محتوای قبلی کلیپبورد بازگردانده میشود |
| ✍️ علائم نگارشی درست | «؟» و «،» فارسی در خروجی فارسی، علائم استاندارد در خروجی انگلیسی |
| 🎨 رابط کاربری مدرن | پنل بدون قاب، گوشههای گرد، سایهی نرم، انیمیشن ورود/خروج، تم تیره |
| 🚀 اجرای خودکار | همراه با ویندوز بالا میآید (قابل خاموش کردن) |
| 🔒 تکنمونهای | هرگز دو نسخه همزمان اجرا نمیشود |
| 📦 نصبکنندهی دوزبانه | ویزارد نصب فارسی (راستچین) و انگلیسی |
روش ۱ — نصبکننده (پیشنهادی)
فایل ParsiSwapSetup-<version>.exe را از بخش Releases دانلود و اجرا کنید. در حین نصب میتوانید زبان، کلید API، سرویسدهنده و کلید میانبر را تنظیم کنید — همه اختیاریاند و بعداً هم از داخل برنامه قابل تغییرند.
روش ۲ — اجرا از سورس
git clone https://github.com/kterfan/ParsiSwap.git
cd ParsiSwap
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
python entry.pyنیازمند ویندوز ۱۰/۱۱ و پایتون ۳.۱۰ به بالا.
یکی از این دو را انتخاب کنید:
- Gemini (گوگل): به Google AI Studio بروید، با اکانت گوگل وارد شوید و روی «Create API key» بزنید. رایگان است اما سهمیهی روزانهی محدودی دارد.
- AvalAI: اگر API گوگل از شبکهی شما در دسترس نیست یا سهمیهی رایگان تمام شده، از AvalAI کلید بگیرید. آدرس سرویس خودکار تنظیم میشود و نیازی به تایپ ندارد.
- روی آیکون برنامه در سینی سیستم کلیک چپ کنید تا پنل تنظیمات باز شود.
- سرویسدهنده را انتخاب و کلید API را وارد کنید.
- دکمهی Refresh را بزنید تا فهرست مدلهای واقعیِ کلید شما بیاید و یکی را انتخاب کنید.
- لحن و کلید میانبر را تنظیم کنید و Save بزنید.
- حالا در هر برنامهای متنی را انتخاب کنید و کلید میانبر را بزنید.
نکتهی مهم: از کلیدهای تنهای F1 تا F12 استفاده نکنید. در بسیاری از لپتاپها این کلیدها بهصورت پیشفرض به کنترل صدا/نور صفحه/رسانه اختصاص دارند و شورتکات هرگز فعال نمیشود. ترکیبهایی مثل
Ctrl+Alt+Tمطمئنترند.
# ساخت فایل exe (تکفایل، بدون پنجرهی کنسول)
.\build.ps1
# ساخت نصبکننده (نیازمند نصب Inno Setup 6)
& "C:\Program Files (x86)\Inno Setup 6\ISCC.exe" installer\setup.issخروجیها در dist\ و dist_installer\ ساخته میشوند.
کلید API شما هرگز داخل مخزن ذخیره نمیشود. تنها جایی که نگهداری میشود این مسیر است:
%APPDATA%\ParsiSwap\config.json
این مسیر خارج از پوشهی پروژه است و در .gitignore هم بهعنوان لایهی محافظ اضافه شده. هیچوقت کلید خود را در جایی عمومی منتشر نکنید.
| مشکل | راهحل |
|---|---|
| شورتکات کار نمیکند | از کلیدهای F استفاده نکنید؛ Ctrl+Alt+T را امتحان کنید |
| «متنی انتخاب نشده» میدهد | مطمئن شوید متن واقعاً انتخاب (هایلایت) شده است |
| «سهمیه پر شده است» | صبر کنید تا سهمیهی روزانه ریست شود، یا به AvalAI سوییچ کنید |
| «مدل در دسترس نیست» | دکمهی Refresh را بزنید و مدل معتبری انتخاب کنید |
| با ویندوز بالا نمیآید | در پنل، تیک «Start automatically with Windows» را بزنید و Save کنید |
ParsiSwap is a lightweight utility that runs in the background and lives in the Windows system tray.
In any application — Word, a browser, Notepad, the Windows search bar, a chat window, anywhere — just select some text and press your shortcut key. The selected text is instantly translated between Persian and English and pasted back in place. Your clipboard is restored afterwards, untouched.
| Feature | Description |
|---|---|
| 🌐 Smart bidirectional translation | Persian → English, English → Persian (automatic language detection) |
| ⌨️ Global hotkey | Works across every Windows app; fully configurable |
| 🎭 Selectable tone | Default, Friendly, Casual, Professional, Formal |
| 🔌 Multiple providers | Gemini (Google), AvalAI (URL auto-filled), or any OpenAI-compatible proxy |
| 📋 Clipboard-safe | Your previous clipboard content is restored after translating |
| ✍️ Correct punctuation | Persian ؟ / ، in Persian output, standard punctuation in English |
| 🎨 Modern UI | Frameless panel, rounded corners, soft drop shadow, slide-up + fade animations, dark theme |
| 🚀 Auto-start | Launches with Windows (can be turned off) |
| 🔒 Single instance | Never runs two copies at once |
| 📦 Bilingual installer | Persian (RTL) and English setup wizard |
Option 1 — Installer (recommended)
Download ParsiSwapSetup-<version>.exe from Releases and run it. During setup you can pick your language, API key, provider and shortcut — all optional and changeable later from inside the app.
Option 2 — Run from source
git clone https://github.com/kterfan/ParsiSwap.git
cd ParsiSwap
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
python entry.pyRequires Windows 10/11 and Python 3.10+.
Pick one:
- Gemini (Google): Go to Google AI Studio, sign in and click "Create API key". Free, but with a limited daily quota.
- AvalAI: If Google's API is unreachable on your network or you've hit the free quota, get a key from AvalAI. Its endpoint URL is filled in automatically — no typing needed.
- Left-click the tray icon to open the settings panel.
- Choose your provider and paste your API key.
- Hit Refresh to fetch the real model list for your key, then pick one.
- Set your tone and shortcut key, then hit Save.
- Now select text in any app and press your shortcut.
Important: Avoid bare F1–F12 keys. Many laptops remap them to volume/brightness/media controls by default, so the low-level hook never sees the real key code. Combinations like
Ctrl+Alt+Tare far more reliable.
# Build the exe (single file, no console window)
.\build.ps1
# Build the installer (requires Inno Setup 6)
& "C:\Program Files (x86)\Inno Setup 6\ISCC.exe" installer\setup.issArtifacts land in dist\ and dist_installer\.
app/
config.py # %APPDATA%\ParsiSwap\config.json load/save
version.py # app name / version / developer
translator.py # Gemini + OpenAI-compatible clients, prompts, model listing
win_hotkey.py # pure ctypes/WinAPI global low-level keyboard hook
win_input.py # pure ctypes/WinAPI SendInput (Ctrl+C / Ctrl+V)
hotkey_listener.py # copy -> translate -> paste pipeline
single_instance.py # named-mutex guard
startup.py # Windows auto-start via HKCU Run key
fonts.py # loads bundled Vazirmatn if present
tray.py # system tray icon + menu
panel_gui.py # frameless animated dark settings panel
main.py # wiring
tools/ # icon + installer artwork generators, hook diagnostics
installer/ # Inno Setup script, Persian translation, wizard images
entry.py # PyInstaller entry point
build.ps1 # build script
On the development machine, pynput's GlobalHotKeys installed its keyboard hook without any error but its callback never actually fired (verified with an independent raw-WinAPI diagnostic). Both the hotkey capture and the key simulation were therefore rewritten with plain ctypes calls to SetWindowsHookExW and SendInput — see win_hotkey.py and win_input.py. This turned out to be far more reliable, and it also removed a dependency.
Your API key is never stored in this repository. It lives only in:
%APPDATA%\ParsiSwap\config.json
That path is outside the project folder, and .gitignore includes a safety net for it anyway. Never publish your API key anywhere public.
| Problem | Fix |
|---|---|
| Shortcut does nothing | Avoid bare F-keys; try Ctrl+Alt+T |
| Says "no text selected" | Make sure the text is actually highlighted |
| "Quota exceeded" | Wait for the daily reset, or switch to AvalAI |
| "Model unavailable" | Hit Refresh and pick a valid model |
| Doesn't start with Windows | Tick "Start automatically with Windows" in the panel and Save |
Developer & Programmer — سازنده و برنامهنویس
Erfan Esmailzadeh