---
name: persian-writing
description: Write, edit and proofread standard Persian (Farsi) text following the Academy of Persian Language and Literature (Farhangestan) orthography - correct ZWNJ/half-space (U+200C) placement for می/نمی, ها, تر/ترین and suffixes after silent ه, Persian ی/ک instead of Arabic ي/ك, Persian vs Latin digits, Persian punctuation (، ؛ ؟ « ») and spacing, formal vs colloquial register, and introducing English tech terms. Use whenever you generate or review Persian prose (UI strings, docs, READMEs, blog posts, emails, translations from English) or the user asks to fix نیم‌فاصله, یکدست‌سازی or ویرایش متن فارسی. نگارش و ویرایش فارسی معیار
---

# نگارش فارسی معیار (Standard Persian writing)

Apply these rules to every Persian sentence you write or edit. When editing someone else's text, always fix orthography (characters, ZWNJ, punctuation, digits); change wording or register only when asked or when the text is clearly bureaucratic filler.

## 1. Encoding rules (check first)

| Item | Use | Never use |
|---|---|---|
| Half-space (نیم‌فاصله) | ZWNJ, U+200C | normal space, nothing (glued), ZWJ U+200D, Arabic tatweel ـ |
| Yeh | ی U+06CC | ي U+064A, ى U+0649 |
| Kaf | ک U+06A9 | ك U+0643 |
| Digits in Persian prose | ۰۱۲۳۴۵۶۷۸۹ (U+06F0 to U+06F9) | Arabic-Indic ٠١٢٣٤٥٦٧٨٩ (U+0660 to U+0669); ٤ ٥ ٦ look different from ۴ ۵ ۶ |
| Ezafe after silent ه | ـهٔ = ه + U+0654 (خانهٔ) | خانه ی (with a space) |

- In prose output (Markdown, HTML text, chat answers), insert the real U+200C character.
- In source code string literals, write ZWNJ as an escape so it stays visible in diffs: `\u200c` in JS/TS/JSON/Python/Java/C#/Go, `"\u{200C}"` in PHP double-quoted strings.
- Do not put ZWNJ next to a space, at the start or end of a word, or twice in a row.
- Leave real Arabic text (Quran verses, Arabic quotes) unnormalized; the ی/ک rule applies to Persian only.

Normalizer for Persian input (search fields, imported data):

```js
const normalizeFa = (s) => s
  .replace(/[\u064A\u0649]/g, '\u06CC')  // Arabic yeh, alef maksura -> Persian yeh
  .replace(/\u0643/g, '\u06A9')          // Arabic kaf -> Persian kaf (keheh)
  .replace(/[\u0660-\u0669]/g, (d) => String.fromCharCode(d.charCodeAt(0) + 0x90)); // Arabic-Indic -> Persian digits
```

## 2. ZWNJ (نیم‌فاصله) rules

ZWNJ only matters after a letter that joins to the left. After non-joining letters (ا د ذ ر ز ژ و) the next letter is already separate, so ZWNJ has no visible effect; do not fuss over it there.

| Rule | Before | After |
|---|---|---|
| Verb prefixes می / نمی / همی are always separated by ZWNJ (also in colloquial text) | میشود، می شود، نمی دانم | می‌شود، نمی‌دانم، می‌شه |
| Plural ها / های: Farhangestan accepts joined or separated, but after silent ه it must be separate. Pick separated with ZWNJ as house style | کتابها، خانهها، فایل های | کتاب‌ها، خانه‌ها، فایل‌های |
| تر / ترین are separated by ZWNJ | مهمتر، بزرگترین | مهم‌تر، بزرگ‌ترین |
| Exceptions written joined: بهتر، بیشتر، کمتر، مهتر، کهتر (and their ترین forms) | بیش‌تر، کم‌ترین | بیشتر، کمترین |
| Indefinite ی after silent ه becomes ای with ZWNJ | خانه ای، نامه یی | خانه‌ای، نامه‌ای |
| Ezafe after silent ه: Farhangestan form is ـهٔ | خانه ی من | خانهٔ من |
| Personal endings and possessives after silent ه: ام، ای، ایم، اید، اند، ات، اش | خسته ام، خانه اش | خسته‌ام، خانه‌اش |
| Compound words whose first part ends in a joining letter | نرم افزار، پیش فرض، به روز رسانی | نرم‌افزار، پیش‌فرض، به‌روزرسانی |

Many websites write the ezafe as خانه‌ی (ZWNJ + ی). If a project already uses that form consistently, keep it; never use a plain space.

Do **not** insert ZWNJ into established single words: دانشگاه، دانشمند، کارگاه. Words that are grammatically separate get a real space: را (کتاب را)، the preposition به (به خانه)، که، و.

## 3. Punctuation and spacing

| Mark | Character |
|---|---|
| Comma | ، (U+060C) |
| Semicolon | ؛ (U+061B) |
| Question mark | ؟ (U+061F) |
| Quotes | « » |
| Period, colon, exclamation | . : ! (same as Latin) |

- No space before a punctuation mark, one space after it: «سلام، خوبی؟» not «سلام ، خوبی ؟».
- Quotes and brackets hug their content: «متن» and (متن), not « متن ».
- One space between words; remove double spaces.
- Do not use Latin `,` `;` `?` or `"..."` inside Persian sentences. Inside code, commands and English phrases, keep Latin punctuation.

## 4. Digits

- Persian prose uses Persian digits: «سال ۱۴۰۵»، «۱۲ فایل».
- Keep Latin digits in anything a machine or a user will copy into a system: code, inline code, CLI commands, URLs, emails, file paths, IPs, version strings inside code spans, API parameters, tracking codes.
- Never mix digit systems inside one number.
- Separators: thousands ٬ (U+066C), decimal ٫ (U+066B), percent ٪ (U+066A). This is exactly what `(1234567.5).toLocaleString('fa-IR')` returns: `۱٬۲۳۴٬۵۶۷٫۵`, and `(0.5).toLocaleString('fa-IR', {style: 'percent'})` returns `۵۰٪`.

## 5. Register

- Default to formal-neutral written Persian (فارسی نوشتاری معیار) for docs, UI and emails. Use colloquial (محاوره) only when the user asks or the brand voice is clearly casual.
- Never mix registers in one text: می‌خواهیم (formal) and می‌خوایم (colloquial) must not appear together.
- UI microcopy: short and polite, address the user consistently with شما, verbs at the end. Buttons: a bare verb or noun («ذخیره»، «ارسال»); instructions: polite imperative («فایل را انتخاب کنید»).
- Gently replace stiff administrative phrasing when it adds nothing:

| Stiff | Simpler |
|---|---|
| می‌باشد | است |
| جهت (meaning "for") | برای |
| در خصوص / در رابطه با | دربارهٔ |
| نمودن | کردن |
| اقدام به نصب نمایید | نصب کنید |

- Prefer a Persian plural when it reads naturally (سندها over اسناد, نظرها over نظرات), but do not purge established loanwords (اطلاعات، امکانات stay). Do not invent purist neologisms the reader will not recognize.

## 6. Technical terms

- First mention: Persian term, then the English term in parentheses. Afterwards use only the Persian term: «یادگیری ماشین (Machine Learning)».
- Use the term your audience actually uses. Farhangestan has approved equivalents (رایانه for computer, رایانامه for email); use them when widely understood, otherwise use the common word (ایمیل).
- Keep product, library and company names in Latin script: React، Docker، GitHub.
- Never translate code identifiers, commands, file names or config keys; put them in backticks.
- A Latin word inside a Persian sentence is fine. In HTML, wrap unpredictable-direction fragments in `<bdi>` (see the rtl-ui skill) so punctuation does not jump sides.

## 7. Before / after examples

| Before | After |
|---|---|
| ما میخواهیم این فایل ها را به روز رسانی کنیم ، لطفا صبر کنید . | ما می‌خواهیم این فایل‌ها را به‌روزرسانی کنیم، لطفاً صبر کنید. |
| اين يك نمونه كد است (Arabic ي and ك) | این یک نمونه کد است |
| خانه ی بزرگتر | خانهٔ بزرگ‌تر |
| تعداد کاربران : 1,250 نفر | تعداد کاربران: ۱٬۲۵۰ نفر |
| در خصوص نصب پکیج جهت اجرای پروژه اقدام نمایید. | برای اجرای پروژه، بسته (package) را نصب کنید. |
| برای نصب دستور npm install را اجرا کنید | برای نصب، دستور `npm install` را اجرا کنید. |
| آیا مطمئن هستید ? | آیا مطمئن هستید؟ |
| "تنظیمات" را باز کنید | «تنظیمات» را باز کنید. |

## 8. Editing workflow

1. Normalize characters: ی/ک, digits.
2. Apply ZWNJ rules (section 2).
3. Fix punctuation and spacing (section 3).
4. Apply digit rules, leaving code, URLs and identifiers untouched (section 4).
5. Only if asked, or if the text is bureaucratic filler: a light register and wording pass (section 5).
6. Re-read once for meaning; never change facts, names or numbers.

Quick self-check before returning text:
- No `ي`, `ك` or `ى` remain in Persian words.
- No space directly after می or نمی when they are verb prefixes. Watch for false positives: می can also be a standalone noun.
- No space before ، ؛ ؟ . !
- Persian digits in prose, Latin digits in code.

Reference: Farhangestan, *دستور خط فارسی* (current edition linked from https://apll.ir/; older 1394 edition PDF: https://apll.ir/wp-content/uploads/2018/10/D-1394.pdf).