# English ↔ Hebrew Keyboard Layout Mapping

This document shows how characters map between English and Hebrew keyboard layouts.

## The Mapping

When you type on a **Hebrew keyboard**, the physical keys produce different characters than when you type on an **English keyboard**. LangOver converts between these layouts by mapping the characters.

### Visual Guide

```
English Keyboard (QWERTY):
┌─────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┐
│  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  │  ,  │  .  │  /  │
└─────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┘

Hebrew Keyboard (same physical keys):
┌─────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┐
│  /  │  '  │  ק  │  ר  │  א  │  ט  │  ו  │  ן  │  ם  │  פ  │
├─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┤
│  ש  │  ד  │  ג  │  כ  │  ע  │  י  │  ח  │  ל  │  ך  │  ף  │
├─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┤
│  ז  │  ס  │  ב  │  ה  │  נ  │  מ  │  צ  │  ת  │  ץ  │  .  │
└─────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┘
```

## Character-by-Character Mapping

### Top Row (QWERTYUIOP)
| English | Hebrew | Hebrew Letter Name |
|---------|--------|-------------------|
| q       | /      | (slash)           |
| w       | '      | (apostrophe)      |
| e       | ק      | Qof               |
| r       | ר      | Resh              |
| t       | א      | Alef              |
| y       | ט      | Tet               |
| u       | ו      | Vav               |
| i       | ן      | Final Nun         |
| o       | ם      | Final Mem         |
| p       | פ      | Peh               |

### Middle Row (ASDFGHJKL;')
| English | Hebrew | Hebrew Letter Name |
|---------|--------|-------------------|
| a       | ש      | Shin              |
| s       | ד      | Dalet             |
| d       | ג      | Gimel             |
| f       | כ      | Kaf               |
| g       | ע      | Ayin              |
| h       | י      | Yod               |
| j       | ח      | Het               |
| k       | ל      | Lamed             |
| l       | ך      | Final Kaf         |
| ;       | ף      | Final Peh         |
| '       | ,      | (comma)           |

### Bottom Row (ZXCVBNM,./)
| English | Hebrew | Hebrew Letter Name |
|---------|--------|-------------------|
| z       | ז      | Zayin             |
| x       | ס      | Samekh            |
| c       | ב      | Bet               |
| v       | ה      | Heh               |
| b       | נ      | Nun               |
| n       | מ      | Mem               |
| m       | צ      | Tsadi             |
| ,       | ת      | Tav               |
| .       | ץ      | Final Tsadi       |
| /       | .      | (period)          |

## Real-World Examples

### Example 1: "Hello" in Hebrew (Shalom)
If you want to type "שלום" (shalom) but accidentally have English keyboard active:

```
What you typed:    a k u o
(English keyboard)

What you meant:    ש ל ו ם
(Hebrew letters)

English meaning:   "shalom" (hello/peace)
```

**LangOver converts:** `akuo` → `שלום`

### Example 2: "Thanks" in Hebrew (Toda)
If you want to type "תודה" (toda):

```
What you typed:    , u s v
(English keyboard)

What you meant:    ת ו ד ה
(Hebrew letters)

English meaning:   "toda" (thanks)
```

**LangOver converts:** `,usv` → `תודה`

### Example 3: Typed Hebrew but meant English
If you typed on Hebrew keyboard but meant to type in English:

```
What you typed:    אגדא
(Hebrew keyboard)

What you meant:    test
(English letters)
```

**LangOver converts:** `אגדא` → `test`

## How to Read the Code

In `LayoutConverter.swift`, you'll see the mapping as Swift dictionaries:

```swift
// English → Hebrew
let mapping: [Character: Character] = [
    "a": "ש",  // Physical key "a" → Hebrew Shin
    "s": "ד",  // Physical key "s" → Hebrew Dalet
    // etc...
]
```

This means: when you press the physical "a" key on your keyboard while in English mode, but you wanted Hebrew, it converts "a" to "ש".

## Notes on Hebrew Typography

### Final Letters (Sofit)
Hebrew has 5 letters with special "final" forms used only at the end of words:
- כ → ך (Kaf → Final Kaf)
- מ → ם (Mem → Final Mem)
- נ → ן (Nun → Final Nun)
- פ → ף (Peh → Final Peh)
- צ → ץ (Tsadi → Final Tsadi)

**LangOver handles these automatically** based on the keyboard layout mapping.

### Right-to-Left (RTL) Direction
Hebrew is written from right to left. macOS handles this automatically in text fields, so LangOver doesn't need to reverse the text - it just converts the characters.

## Adding Support for Other Languages

To add Russian, Arabic, or other layouts:

1. Find the keyboard layout mapping (Wikipedia has great tables)
2. Add a new function in `LayoutConverter.swift`
3. Create a similar mapping dictionary

Example for Russian (Cyrillic):
```swift
// English → Russian
let mapping: [Character: Character] = [
    "q": "й", "w": "ц", "e": "у", "r": "к",
    "a": "ф", "s": "ы", "d": "в", "f": "а",
    // etc...
]
```

---

**Reference:** Standard Hebrew keyboard layout follows the SI 1452 Israeli standard.
