How to Fix Persian Keyboard Typing Mistakes on Windows, macOS, and Linux

Have you ever started typing in English while your keyboard was supposed to be in Persian? For example, you type sghl instead of سلام and realize that you’ve written an entire sentence in the wrong keyboard layout!

Switching keyboard layouts and typing everything again can be frustrating.

In this tutorial, I’ll show you how to build a simple Persian Keyboard Layout Fixer that converts incorrectly typed English characters into their corresponding Persian characters using a keyboard shortcut.

We’ll cover Windows, macOS, and Linux using open-source tools.

---

What Is a Persian Keyboard Layout Fixer?

A Persian keyboard layout fixer converts characters typed using the English keyboard layout into their equivalent Persian characters.

For example:

Incorrect Text	Correct Persian
sghl	سلام
thvsd	فارسی
lkh	ماه

The idea is simple: instead of changing your keyboard language and typing everything again, select the incorrect text and press a shortcut to convert it instantly.

---

Step 1: Windows Setup (AutoHotkey)

On Windows, we’ll use AutoHotkey to create a global keyboard shortcut.

1. Install AutoHotkey

Download and install AutoHotkey v2:

https://www.autohotkey.com/

2. Create the Script

Create a file named PersianFix.ahk:

#Requires AutoHotkey v2.0
#SingleInstance Force

^!f::
{
    savedClipboard := ClipboardAll()
    A_Clipboard := ""

    Send "^c"

    if !ClipWait(1) {
        A_Clipboard := savedClipboard
        return
    }

    inputText := A_Clipboard

    layout := Map(
        "q", "ض", "w", "ص", "e", "ث", "r", "ق",
        "t", "ف", "y", "غ", "u", "ع", "i", "ه",
        "o", "خ", "p", "ح", "[", "ج", "]", "چ",
        "a", "ش", "s", "س", "d", "ی", "f", "ب",
        "g", "ل", "h", "ا", "j", "ت", "k", "ن",
        "l", "م", ";", "ک", "'", "گ",
        "z", "ظ", "x", "ط", "c", "ز", "v", "ر",
        "b", "ذ", "n", "د", "m", "پ", ",", "و"
    )

    outputText := ""

    Loop Parse inputText {
        char := A_LoopField
        key := StrLower(char)

        if layout.Has(key)
            outputText .= layout[key]
        else
            outputText .= char
    }

    A_Clipboard := outputText
    Send "^v"

    Sleep 300
    A_Clipboard := savedClipboard
}

3. Create a BAT Launcher

Create Start.bat in the same directory:

@echo off
start "" "%~dp0PersianFix.ahk"

Double-click Start.bat to start the script.

4. Use the Shortcut

1. Select the incorrectly typed text.
2. Press Ctrl + Alt + F.
3. Your selected text will be converted into Persian.

---

Step 2: macOS Setup (Hammerspoon)

On macOS, we’ll use Hammerspoon, an open-source automation tool that supports global keyboard shortcuts.

1. Install Hammerspoon

Download it from:

https://www.hammerspoon.org/

2. Create the Configuration

Open Terminal and run:

mkdir -p ~/.hammerspoon
nano ~/.hammerspoon/init.lua

Add the following code:

local map = {
    q="ض", w="ص", e="ث", r="ق", t="ف",
    y="غ", u="ع", i="ه", o="خ", p="ح",
    ["["]="ج", ["]"]="چ",

    a="ش", s="س", d="ی", f="ب", g="ل",
    h="ا", j="ت", k="ن", l="م",
    [";"]="ک", ["'"]="گ",

    z="ظ", x="ط", c="ز", v="ر",
    b="ذ", n="د", m="پ", [","]="و"
}

local function convert(text)
    return (text:gsub(".", function(c)
        return map[c:lower()] or c
    end))
end

hs.hotkey.bind({"cmd", "alt"}, "F", function()
    local old = hs.pasteboard.getContents()
    hs.pasteboard.setContents("")

    hs.eventtap.keyStroke({"cmd"}, "c")

    hs.timer.doAfter(0.3, function()
        local selected = hs.pasteboard.getContents()

        if selected and selected ~= "" then
            hs.pasteboard.setContents(convert(selected))
            hs.eventtap.keyStroke({"cmd"}, "v")

            hs.timer.doAfter(0.5, function()
                hs.pasteboard.setContents(old or "")
            end)
        else
            hs.pasteboard.setContents(old or "")
        end
    end)
end)

3. Enable Permissions

Allow Hammerspoon to control your computer:

1. Open System Settings.
2. Navigate to Privacy & Security.
3. Open Accessibility.
4. Enable Hammerspoon.

4. Reload Configuration

Open Hammerspoon and reload its configuration.

Select text and press:

Cmd + Option + F

---

Step 3: Linux Setup (Bash + Python)

On Linux, we’ll use Bash, Python, and clipboard utilities.

1. Install Dependencies

For Ubuntu or Debian:

sudo apt update
sudo apt install python3 xclip

2. Create the Script

Create a file named persian-fix.sh:

#!/usr/bin/env bash

python3 -c '
import sys

mapping = dict(zip(
    "qwertyuiop[]asdfghjkl;'\''zxcvbnm,",
    "ضصثقفغعهخحجچشسیبلاتنمکگظطزرذدو"
))

text = sys.stdin.read()

print(
    "".join(mapping.get(c.lower(), c) for c in text),
    end=""
)
'

3. Make It Executable

chmod +x persian-fix.sh

4. Convert Selected Text

Copy your selected text and run:

xclip -selection clipboard -o \
  | ./persian-fix.sh \
  | xclip -selection clipboard

Now paste the converted text.

5. Add a Global Shortcut

Open your desktop environment’s keyboard shortcut settings and create a custom shortcut.

For example:

• Shortcut: Ctrl + Alt + F
• Command: Your clipboard conversion command.

For Wayland, you can use wl-clipboard (wl-copy and wl-paste) instead of xclip.

---

Step 4: How Does the Conversion Work?

The main idea behind this project is character mapping.

Each English keyboard key corresponds to a Persian character in the standard Persian keyboard layout.

For example:

English keyboard: s  g  h  l
Persian keyboard: س  ل  ا  م

The script reads every character, finds its equivalent in the mapping dictionary, and replaces it.

Characters without a mapping, such as spaces, numbers, and most punctuation, remain unchanged.

---

Step 5: Keyboard Shortcuts

Here is a quick overview:

Operating System	Shortcut	Tool
Windows	Ctrl + Alt + F	AutoHotkey
macOS	Cmd + Option + F	Hammerspoon
Linux	Ctrl + Alt + F	Bash + Python

These shortcuts work with most applications that support normal text selection and clipboard operations.

---

Why Use Open-Source Tools?

One of the main goals of this project is to avoid relying on closed-source applications for simple everyday tasks.

Instead of installing proprietary keyboard utilities or third-party apps that you cannot inspect, we use open-source tools:

• AutoHotkey: Automate keyboard shortcuts on Windows.
• Hammerspoon: Customize macOS using Lua.
• Bash: Automate tasks on Linux and Unix-like systems.
• Python: Handle character mapping and text conversion.

Using open-source tools gives you more control over your system, lets you inspect and modify the code, and avoids unnecessary dependencies on proprietary software.

You don’t need an expensive or closed-source application just to fix a keyboard layout mistake. A few lines of code can do the job!

---

Important Notes

• Always select the text before using the shortcut.
• These scripts use clipboard operations to read and replace selected text.
• Some applications may block clipboard access or simulated keyboard input.
• The examples use a basic character mapping and can be extended for uppercase letters, additional punctuation, and other keyboard layouts.
• Clipboard restoration and timing should be improved and tested before using these scripts as production-ready utilities.
• Linux shortcut integration depends on your desktop environment and whether you’re using X11 or Wayland.

---

Final Thoughts

Typing in the wrong keyboard layout happens to everyone, especially when switching between Persian and English frequently.

With a small script and a global keyboard shortcut, you can fix these mistakes without retyping everything.

Whether you’re using Windows, macOS, or Linux, you can customize this project to fit your workflow.

And most importantly, you can do it without depending on closed-source keyboard utilities.

Happy coding! 🚀