Inside the engineering
Typing Persian is the easy part.
The hard part is deciding when a word should change, preserving everything around it, and doing it safely across the many editors people use on Windows.
THE PATH OF A WORD
sghlEnglish keystrokes
···Check word and editor
Safe conversionسلام
Keep originalsghl
Counts are from the project engineering notes dated 13 October 2026. They describe documented work, not a promise that every editor behaves identically.
From language ambiguity to Windows behavior
What made the work difficult
These are concrete failure cases from development, and the rules Diyar uses to avoid damaging text when the editor or language is ambiguous.
Language needs evidence
THE PROBLEM
English homographs and unfamiliar words can be hard to distinguish from intended Persian. A false Persian conversion can corrupt ordinary English writing.
HOW DIYAR HANDLES IT
Known English words and technical strings are protected first. Conversion requires positive Persian evidence under one decision policy; users can choose a Persian/English priority or use nearby context for ambiguous words such as “fun” and “leg”.
The keyboard layout changes the letters
THE PROBLEM
On an English layout, punctuation keys such as [ ] ; ' , can represent Persian letters چ، ج، ک، گ، و. A simple letter-for-letter replacement misses layout differences, ZWNJ, and attached suffixes.
HOW DIYAR HANDLES IT
Diyar reads versioned Windows layout data and treats Persian-only punctuation keys as language evidence. Its mapping also accounts for ZWNJ and common suffixes and pronouns.
Mixed text has protected patterns
THE PROBLEM
Emails, URLs, IP addresses, file paths, versions, numbers, and code may appear inside Persian sentences. Changing them is wrong, but treating the whole sentence as English can block later Persian words.
HOW DIYAR HANDLES IT
A technical-pattern detector recognizes these strings before language scoring and leaves them intact. Ordinary English contractions such as “can't” are protected as English, too.
The caret and editor can disagree
THE PROBLEM
Clicks, pastes, arrow keys, or focus changes can make the start of a word uncertain. Chromium editors may expose lagging text, stale text, or visual RTL order rather than stored text order.
HOW DIYAR HANDLES IT
Diyar distinguishes lag from mismatch, tracks when the word start is known, and closes its own leftover selection safely. It only replaces text after confirming the target; otherwise the typed word stays as is.
Some editors need a safe fallback
THE PROBLEM
Windows 11 Notepad can lose Persian characters when a batch of Unicode letters is inserted. Unreadable controls and protected fields also leave Diyar without enough information for a safe replacement.
HOW DIYAR HANDLES IT
Diyar detects the affected Notepad path and skips automatic replacement there. Unknown, protected, or unreadable fields pass through unchanged rather than risking lost or misplaced text.
Recovery and responsiveness are part of correctness
THE PROBLEM
A mistaken conversion must be reversible, while checking an editor must not delay the next key or send it to a different field after focus changes.
HOW DIYAR HANDLES IT
Automatic conversions retain original keystrokes for atomic Backspace recovery. Explicit commands verify the selected text and result; editor inspection runs off the keyboard hook, and Diyar never queues keys while waiting for an editor.
THE ENGINEERING MAP
Ten areas behind the 63 challenges
The 63 documented challenges are grouped into ten areas. Open each one for representative engineering decisions from that part of the work.
Language decisions
Ambiguous words, short words, context, English protection, and Persian vocabulary.
Language decisions
Ambiguous words, short words, context, English protection, and Persian vocabulary.
- A missing English dictionary match is not enough to trigger conversion; known English words and technical patterns are protected first.
- Contextual priority uses the immediately preceding Persian word and frequency clues for homographs such as fun and leg; separate policies govern one- and two-letter words.
Keyboard and characters
Persian key maps, punctuation keys, ZWNJ, suffixes, numbers, and symbols.
Keyboard and characters
Persian key maps, punctuation keys, ZWNJ, suffixes, numbers, and symbols.
- Layout maps are versioned data rather than scattered hard-coded mappings; punctuation keys can be evidence for Persian letters such as و، گ، ک، ج، چ.
- The conversion rules account for ZWNJ, attached suffixes and pronouns, Persian punctuation, money amounts, and optional Persian digits without touching IPs, times, versions, or codes.
Editors and caret
Focus changes, stale text, selection safety, and reliable undo.
Editors and caret
Focus changes, stale text, selection safety, and reliable undo.
- Caret movement from clicks, arrows, paste, or focus change makes the word start unknown until Diyar can establish it again.
- Lagging, mismatched, frozen, and unreadable editor text are treated as separate conditions; Diyar cleans up its own failed selection and only edits a confirmed target.
Different applications
Chromium, Notepad, code editors, rich text, terminals, and app-specific behavior.
Different applications
Chromium, Notepad, code editors, rich text, terminals, and app-specific behavior.
- Windows 11 Notepad has a route where batch Unicode insertion can lose Persian letters; automatic conversion is limited on that route.
- Editor capabilities are remembered. Code editors and terminals can allow direct Persian comments while automatic replacement remains conservative; elevated windows require matching privilege levels.
Sensitive fields
Passwords, addresses, payment forms, and unknown controls pass safely through.
Sensitive fields
Passwords, addresses, payment forms, and unknown controls pass safely through.
- Password, read-only, email, URL, and payment fields are protected. Unknown field state is treated as protected until inspection can confirm it.
- Direct typing also checks field safety; password keystrokes are passed through and must never enter diagnostic logs.
Separate typing modes
Automatic, direct Persian, Caps Lock, Shift, pause, and their distinct rules.
Separate typing modes
Automatic, direct Persian, Caps Lock, Shift, pause, and their distinct rules.
- Only one mode is active at a time. Direct Persian writes mapped characters without prediction or reading editor text; Caps Lock and Shift only have special meaning in their selected modes.
- Pause clears the in-progress word buffer so keys typed before and after a pause cannot be joined into a false word.
Windows and performance
Keyboard hooks, UI Automation, background workers, focus tracking, and TSF.
Windows and performance
Keyboard hooks, UI Automation, background workers, focus tracking, and TSF.
- Slow editor inspection moved off the low-level keyboard hook; an isolated helper process and watchdog keep unavailable UI Automation from freezing the app.
- Focus changes invalidate stale editor facts, modifier state is reconciled with Windows after secure-desktop transitions, and TSF handles explicit selection edits where supported.
Right-to-left text
Paragraph direction, mixed Persian and English, and editors with their own RTL rules.
Right-to-left text
Paragraph direction, mixed Persian and English, and editors with their own RTL rules.
- Paragraph direction is set deliberately when Persian begins a line, so a leading English product name does not pull the whole paragraph left-to-right.
- Word-like editors that manage paragraph direction use a host-specific path; editors that rewrite text around spaces need explicit compatibility limits.
Testing and diagnostics
Unreliable editor simulations, regression tests, diagnostic logs, and CI.
Testing and diagnostics
Unreliable editor simulations, regression tests, diagnostic logs, and CI.
- FakeEditor can be stale, frozen, unreadable, or expose visual RTL order; TypingSession drives the real controller against those states.
- Regression coverage is expected to fail against the old behavior first. Diagnostic logging stays off the keyboard hook, is formatted only when enabled, and temporary logs are cleared when disabled.
Interface and delivery
Bilingual UI, font rendering, installer registration, upgrades, and stored settings.
Interface and delivery
Bilingual UI, font rendering, installer registration, upgrades, and stored settings.
- Typed text catalogs support live Persian/English switching; Persian UI uses Shabnam FD and isolates Latin shortcuts and paths for bidirectional display.
- The bilingual installer registers TSF and handles upgrades. Update checks are delayed and periodic, but never download or install automatically; Azure keys are kept in Windows Credential Manager.
One mode at a time
Four ways to type
Choose the typing behavior that fits the moment.
Automatic
Type with the English layout. Smart mode checks at word boundaries and converts when there is enough evidence for Persian.
Direct Persian
Each key produces its Persian character immediately. There is no word prediction; hold the configured modifier to type English.
Caps Lock switch
Use Caps Lock for the selected layout-switching or direct-typing behavior. Its role depends on the active mode.
Shift switch
Hold Shift to use the alternate Windows layout, then release it to return. This mode switches layout without automatic conversion.
A native Windows text service
Why Diyar uses Windows TSF
Text Services Framework is Windows’ native way for an editor to expose and update text. Diyar uses a dedicated text service for explicit selection commands, so useful editing commands can work without switching the active keyboard layout away from English.
A focused job
The TSF service handles convert-previous-word, convert-selection, and their undo path in editors that support the text service. Ordinary automatic typing remains on its separate path.
One verified edit
The target is selected by the editor, changed in one edit session, and read back afterward. If the text changed between inspection and writing, the operation stops instead of retrying against a new target.
Protected contexts
Password, read-only, and currently composing fields are rejected. The service records operation length and outcome for diagnostics, never the text itself.
Installer registration
The installer registers the service for Windows users. Editors already open during installation need to be reopened once before they load it.
Compatibility with clear boundaries
Support depends on the editor
Diyar adapts to what Windows and each editor can safely confirm. These boundaries are deliberate; “works everywhere” would overstate the current behavior.
Supported text services
Explicit selection-based commands use TSF where the editor exposes a supported text service; the operation verifies what changed.
Chrome, Edge, and Electron
Accessibility text can lag or arrive in a different order. Diyar treats stale, delayed, and mismatched text as different states and avoids blind Backspace replacement.
Windows 11 Notepad
A known Unicode batch-loss route limits automatic replacement. The word is left as typed on that path so inserted Persian characters are not lost.
Elevated or protected fields
Windows blocks input across privilege levels. Password, read-only, payment, and unknown fields are treated conservatively; apps running as administrator require Diyar at the same privilege level.
Keyboard layouts
The current physical-key mapping supports US, US-International, UK, and NZ QWERTY layouts. Dvorak, Colemak, and AZERTY are documented limitations.
Responsive without sacrificing safety
The keyboard hook must never wait
An early implementation queried UI Automation from inside the Windows keyboard hook. One Space key took 505–712 ms, long enough for Windows to remove the slow hook.
505–712 ms
Recorded during the original failure investigation—not a current latency claim. Editor inspection was moved to worker/background paths, each hook callback is timed, and a removed hook can be reinstalled.
Tests designed to catch failure
Make the bad editor reproducible
A green unit-test count alone had missed real failures because the simulated editor always told the truth. The test setup now exercises the actual typing controller against editors that behave badly on purpose.
A deliberately unreliable editor
FakeEditor can return stale text, freeze, expose RTL visual order, or refuse to expose text—conditions seen in real applications.
The real controller in a typing session
TypingSession drives the production controller against those editor behaviors so recovery, focus changes, and selection cleanup are exercised together.
A regression must fail first
For a fix to count as covered, its regression test is checked against the old behavior and must fail before the correction is applied.
Inspect the recorded run
The project notes report more than 3,000 tests in the latest recorded CI run. The exact number should be refreshed from CI before quoting it as a current total.
THE SAFETY PRINCIPLE
Careful by design
When confidence is low, Diyar leaves the text untouched.
- Password and read-only fields pass through unchanged.
- Email, web addresses, file paths, and code are recognized as technical text.
- Short Persian words use nearby context to reduce accidental English-to-Persian changes.
- If text or caret position cannot be confirmed safely, automatic replacement is skipped.
- Typing and Foundry Local translation stay on-device. Only an explicit translation request for selected text, after configuring Azure with your own API key, sends that text directly to Azure and receives its translation.
YOU STAY IN CONTROL
Default quick commands
Quick commands for correction, recovery, and control.
Restore the last automatic conversionBackspace
Convert the word before the cursorCtrl + Alt + Space
Convert selected textCtrl + Alt + Enter
Undo the last explicit conversionCtrl + Alt + U
Add selected text to your dictionaryCtrl + Alt + D
Pause or resume DiyarCtrl + Alt + P
Translate selected textCtrl + Alt + T
Shortcuts can be changed in Diyar settings. App behavior varies by editor and field; a conservative pass-through is intentional when a safe edit cannot be confirmed.