Localize Fa

Localize: Persian / Farsi (fa → فارسی)

Scope & Variants

Persian is the heritage language of a continuous civilization stretching from western China to the Caucasus. It is one of the world's oldest continuously-attested literary languages (Old Persian → Middle Persian / Pahlavi → New Persian since the 9th century CE). Today it is spoken by ~110 million people across Iran, Afghanistan, and Tajikistan, with significant diaspora in the Gulf, Europe, and North America.

This skill covers the Perso-Arabic-script written language. Tajik (which writes Persian in modified Cyrillic) is out of scope.

| Locale | Name | Native name | Where | Default register | |--------|------|-------------|-------|------------------| | fa / fa-IR | Iranian Persian (standard) | فارسی / فارسی ایران | Iran (~85M speakers) | Formal شما | | fa-AF | Dari | دری / فارسی دری | Afghanistan (~15M speakers) | Formal شما (slightly more conservative) | | fa-TJ | Tajik | тоҷикӣ / تاجیکی | Tajikistan (Cyrillic script) | Out of scope |

Default for general UI / international audiences: fa-IR (Iranian Persian standard, Tehran-based modern register). It is mutually intelligible with Dari in written form; most differences are in pronunciation and a few lexical items.

fa-IR vs fa-AF (Dari) — what actually differs in writing

The two are the same written language for ~95% of UI copy. Differences appear mainly in:

| Concept | fa-IR (Iran) | fa-AF (Dari, Afghanistan) | |---------|--------------|--------------------------| | Currency | تومان / ریال | افغانی (afghani) | | University | دانشگاه | پوهنتون | | Faculty/college | دانشکده | پوهنځی | | Hospital | بیمارستان | شفاخانه | | Bicycle | دوچرخه | بایسکل | | Airport | فرودگاه | میدان هوایی | | Office | دفتر / اداره | دفتر / دفترکار | | Calendar | Solar Hijri (Jalali) — Persian-named months فروردین… | Solar Hijri — but month names use Arabic-origin zodiac names (حمل، ثور، جوزا، سرطان، اسد، سنبله، میزان، عقرب، قوس، جدی، دلو، حوت) | | Weekend | جمعه (Friday only) — شنبه is workday | پنج‌شنبه + جمعه | | Lexical loanwords | More French/English loans (سیمان، آپارتمان، تاکسی) | More Pashto/Arabic loans alongside Persian | | Verb endings (spoken) | -ad (می‌رود = miravad in Iran often miravad → "mire" colloquially) | More conservative, closer to written form |

Default to fa-IR. If the user requests fa-AF/Dari, switch the lexical items above and use Dari month names.

When the target locale is unspecified

If the user requests "Persian" or "Farsi" without specifying region, ask once:

> Which Persian variant should I target? > > - fa-IR Iranian Persian — Recommended. Default for international/general use. Months: فروردین، اردیبهشت… Currency: تومان/ریال. > - fa-AF Dari (Afghanistan) — Pohantoon/shafakhana vocabulary, Arabic-zodiac month names (حمل، ثور…), afghani currency.

Default to fa-IR if no answer.

---

Identity Guardrail — Persian is NOT Arabic

This is the single most important section of this skill. Persian is an Iranian Indo-European language. Arabic is an Afro-Asiatic Semitic language. They are as related as English and Hindi — distant cousins in the global Indo-European family vs an entirely different family.

The two languages share script and vocabulary (Persian adopted the Perso-Arabic script in the 9th century and absorbed ~30-40% Arabic loanwords for religion, law, and high culture), but their grammars are completely different:

| Feature | Persian (Indo-European, Iranian) | Arabic (Afro-Asiatic, Semitic) | |---------|----------------------------------|--------------------------------| | Word order | SOV (Subject-Object-Verb) — verb at end | VSO (Verb-Subject-Object) preferred | | Grammatical gender | NONE — no masculine/feminine on nouns or verbs | Masculine + feminine on every noun, adjective, verb, pronoun | | Number system | Singular + plural | Singular + dual + plural (3 numbers) | | CLDR plural categories | 2 — one/other (and one and other often look identical) | 6 — zero/one/two/few/many/other | | Noun-after-number | Stays singular (پنج فایل = "five file") | Changes by count band (3-10 plural genitive, 11-99 sg. accusative tanween, 100+ sg. genitive) | | Defining grammar feature | EZAFE (-e linker connecting noun + modifier) | IDAFA (construct state, opposite direction: possessor follows possessed) | | Verb morphology | Conjugates for person + number (NOT gender). Compound verbs (noun + کردن) extremely common | Conjugates for person + number + gender + case (nom/acc/gen). Root-and-pattern morphology | | Definite article | NONE (definiteness shown by context, را marker, or demonstratives) | ال prefix | | Letters specific to language | پ چ ژ گ (4 letters NOT in Arabic) | ث ح خ ذ ض ظ ع (kept in Persian for Arabic loanwords but pronounced differently) | | Letter ی | U+06CC (no dots beneath in any form) | ي U+064A (dots beneath in initial/medial/isolated) | | Letter ک | U+06A9 (no hamza-like tail) | ك U+0643 (with tail in isolated form) | | Numerals | ۰۱۲۳۴۵۶۷۸۹ (Persian) preferred | ٠١٢٣٤٥٦٧٨٩ (Arabic-Indic) traditional, or Western 0-9 | | Religious framing | Shia-majority Iran (~90%) + Sunni Afghanistan; significant Zoroastrian heritage and minority Christians/Jews/Baha'is | Sunni-majority overall; some Shia regions (Iraq, Lebanon, Bahrain) |

Concrete contrast — "The new files were saved":

| Language | Sentence | Word-by-word | |----------|----------|--------------| | English | The new files were saved. | The new files were saved. | | Persian | فایل‌های جدید ذخیره شدند. | files-the new saved became (SOV, no gender, ezafe ‍-e‍ connects فایل‌ها + جدید). | | Arabic | حُفِظت الملفات الجديدة. | was-saved-fem.sg the-files the-new-fem.sg (VSO, non-human plural takes fem. sg. agreement). |

Mistakes that auto-fail:

• Writing Arabic ي where Persian ی belongs (ميكنيد instead of می‌کنید)
• Writing Arabic ك where Persian ک belongs (كتاب instead of کتاب)
• Forgetting ZWNJ in compound forms (میکنید or می کنید instead of می‌کنید)
• Putting adjective before noun, Arabic-IDAFA-style or English-style (جدید فایل instead of فایل جدید)
• Adding Arabic-style gender agreement (فایل جدیده instead of فایل جدید — Persian has no feminine adjective form)
• Using Arabic-style dual (دو فایلان — Persian has no dual; just دو فایل)
• Importing Arabic ICU six-category plurals into Persian (Persian needs only one + other)
• Calling Persian "a dialect of Arabic" (it is not — it predates Arabic literature by centuries and belongs to a different language family)

When in doubt: Persian is Iranian; Arabic is Semitic. They share a script, not a grammar.

---

Register — شما (formal) vs تو (informal)

Persian distinguishes two registers via second-person pronoun + verb ending. Software UI default is formal شما throughout.

| Register | Pronoun | "You save" | "Your file" | "Please click" | Use case | |----------|---------|-----------|-------------|----------------|----------| | شما (formal/plural — DEFAULT) | شما | ذخیره می‌کنید | فایل شما / فایلتان | لطفاً کلیک کنید | UI, business, news, formal address, any unknown audience | | تو (informal singular) | تو | ذخیره می‌کنی | فایلت | کلیک کن | Close friends, family, children, casual chat apps, intimate marketing |

Hard rules:

1. Software UI uses شما — always. This is non-negotiable for product copy aimed at general users.
2. Never mix شما and تو in the same file. All verb endings, pronouns, and possessive suffixes must agree.
3. شما is also the polite plural (used to address multiple people). It is the only safe default for unknown audience.
4. تو is intimate — use only when the source text is explicitly casual (informal tone of voice, "Hey!", chat-app messaging, children's product, dating app personal voice).

Verb ending table (present tense, "do/does")

| Person | شما-form (formal) | تو-form (informal) | |--------|-------------------|---------------------| | I do | می‌کنم (mikonam) | می‌کنم (same) | | You do | می‌کنید (mikonid) | می‌کنی (mikoni) | | He/she/it does | می‌کند (mikonad) | می‌کند (same) | | We do | می‌کنیم (mikonim) | می‌کنیم (same) | | You (pl.) do | می‌کنید (mikonid) | می‌کنید (same — also formal sg.) | | They do | می‌کنند (mikonand) | می‌کنند (same) |

Possessive suffix table

| English | شما-form (UI default) | تو-form (informal) | |---------|-----------------------|---------------------| | my file | فایل من / فایلم | فایل من / فایلم | | your file | فایل شما / فایلتان | فایلت | | his/her file | فایل او / فایلش | فایل او / فایلش | | our file | فایل ما / فایلمان | فایل ما / فایلمان | | your (pl.) file | فایل شما / فایلتان | فایل شما / فایلتان | | their file | فایل آن‌ها / فایلشان | فایل آن‌ها / فایلشان |

Register auto-detection from source

| Source signal | Target register | |---------------|-----------------| | Neutral product/UI prose (Click to save, Your file was uploaded) — DEFAULT | شما formal — لطفاً کلیک کنید, فایل شما بارگذاری شد | | Contractions, exclamations, casual lexicon (Hey!, Let's…, emoji-heavy) | شما formal still recommended, but soften — drop لطفاً in buttons, allow short status forms | | Legal/financial/very-formal (terms of service, banking, government) | شما formal + elevated vocabulary (یُرجی, خواهشمندیم, با احترام, جناب/خانم titles) | | Children's product, chat-app personal voice, intimate marketing | تو informal — but be absolutely sure this is the brand voice |

Hard rule: when in doubt, use شما. Defaulting to formal is always safe; defaulting to informal can offend.

---

Critical Hard Rules

1. EZAFE construction — the defining Persian grammatical feature (severity 2.5)

Ezafe (اضافه, literally "addition") is a short unstressed vowel -e (or -ye after a vowel) that links a noun to its modifier, possessor, or descriptor. It is the single most distinctive feature of Persian grammar.

Form:

• After a consonant: pronounced -e, often unwritten (sometimes shown with کسره ◌ِ for clarity).
• After a vowel (especially ـه silent or ـا or ـو): pronounced -ye, written explicitly as ـۀ or ـه‌ی or ی depending on convention.

Word order: head noun FIRST, then modifier — opposite of English.

| Pattern | Example | Pronunciation | Meaning | |---------|---------|---------------|---------| | noun + adjective | فایل جدید | fâyl-e jadid | (file-of new =) new file | | noun + possessor noun | تنظیمات کاربر | tanzimât-e kâr-bar | (settings-of user =) user settings | | noun + possessor pronoun | کتاب من | ketâb-e man | (book-of me =) my book | | noun ending in vowel + modifier | خانهٔ بزرگ / خانه‌ی بزرگ | khâne-ye bozorg | (house-of big =) big house | | chain | اسم کاربر جدید | esm-e kâr-bar-e jadid | (name-of user-of new =) new user's name |

Critical contrasts:

| ✗ Wrong (English/Arabic order) | ✓ Correct (Persian ezafe order) | Why | |--------------------------------|---------------------------------|-----| | جدید فایل | فایل جدید | Noun must come FIRST | | کاربر تنظیمات | تنظیمات کاربر | Possessed (settings) FIRST, possessor (user) SECOND | | من کتاب | کتاب من | Possessed FIRST | | نو خانه | خانهٔ نو | Vowel-ending noun → write ـۀ or ـه‌ی, not just space |

ezafe vs Arabic idafa — opposite direction:

In Arabic idafa, كتاب الرجل = "book the-man" = "the man's book" — possessed first, possessor second WITHOUT a linker, and the first noun drops ال.

In Persian ezafe, کتابِ مرد = "book-e-man" = "the man's book" — possessed first, possessor second WITH the linker -e.

The order is the same, but Persian REQUIRES the linker (audibly), and Persian does NOT drop the article (Persian has no article).

When the ezafe is sometimes written:

• For clarity in formal/educational text: explicit kasra ◌ِ on the head noun (کتابِ من).
• After ـه silent: ـۀ (one character, with hamza-like mark) or ـه‌ی (two-character with ZWNJ + ی). Both are accepted; ـۀ is more traditional, ـه‌ی is more modern/common in software.
• After ـی or vowels: just ی appended (دانشجویی بزرگ → ezafe is implicit in pronunciation).

For UI translation: write the words in correct head-first order. Do NOT add diacritics (kasra) to UI strings unless the source explicitly uses them. Modern Persian software omits the kasra and lets the reader infer ezafe from context.

2. ZWNJ (Zero-Width Non-Joiner, U+200C) — the half-space (severity 2.5)

Persian uses a special invisible character — the half-space or نیم‌فاصله (nim-fâsele) — between certain morphemes to:

• Prevent letter ligature (so two adjacent letters don't visually connect).
• Mark a compound boundary inside what is conceptually one word.
• Distinguish prefixed verbs from separate words.

ZWNJ is REQUIRED in these contexts (auto-fail if missing or replaced by full space):

| Context | ✗ Wrong (no space) | ✗ Wrong (full space) | ✓ Correct (ZWNJ) | |---------|--------------------|-----------------------|------------------| | می- present-tense prefix | میرود | می رود | می‌رود (is going) | | می- with negation | نمیخواهم | نمی خواهم | نمی‌خواهم (I don't want) | | ها plural suffix | فایلها | فایل ها | فایل‌ها (files) | | ها on consonant-ending nouns | کتابها | کتاب ها | کتاب‌ها (books) | | تر comparative | بزرگتر | بزرگ تر | بزرگ‌تر (bigger) | | ترین superlative | بزرگترین | بزرگ ترین | بزرگ‌ترین (biggest) | | ای indefinite suffix | فایلای | فایل ای | فایل‌ای (a file) — rare, usually فایلی | | Compound words | خوشحال | (varies) | خوش‌حال or خوشحال (both accepted) | | Numbered compound | پنجشنبه | پنج شنبه | پنج‌شنبه (Thursday) |

Why this matters technically:

• Without ZWNJ, می + رود written as میرود looks visually different — the م + ی would attempt to ligate with the next ر, producing an awkward shape.
• With a full space, می رود would treat می and رود as separate words, which is grammatically wrong (می- is a verbal prefix, not an independent word).
• The ZWNJ produces the correct visual rendering AND the correct semantic word boundary.

Producing ZWNJ in software:

• Unicode U+200C
• HTML entity: ‌
• Persian keyboards: Shift+Space (Iranian standard layout) or Ctrl+Shift+2 (some layouts)
• Often invisible in source code — use a Persian-aware editor (VSCode renders it as a narrow dotted box).

Common QA bug: translation tools that "normalize whitespace" can strip ZWNJ, breaking every present-tense verb in the file. Always check that your translation pipeline preserves U+200C.

3. Direct Object Marker را (severity 2.0)

When a direct object is definite (specific, known), Persian marks it with the postposition را placed AFTER the noun phrase.

Rule: definite direct object → add را; indefinite direct object → no را.

| English | Persian | را used? | Why | |---------|---------|----------|-----| | Save the file. | فایل را ذخیره کنید. | ✓ | Specific file | | Save a file. | فایلی ذخیره کنید. | ✗ | Indefinite (suffix ـی marks indefinite) | | Delete this account. | این حساب را حذف کنید. | ✓ | Demonstrative → definite | | Delete an account. | حسابی حذف کنید. | ✗ | Indefinite | | Click the button. | روی دکمه کلیک کنید. | ✗ (with روی) | Indirect object via preposition روی | | Click the button (transitive). | دکمه را فشار دهید. | ✓ | Direct object |

Critical context — را goes AFTER the entire noun phrase, including ezafe modifiers:

| ✗ Wrong placement | ✓ Correct placement | |--------------------|---------------------| | فایل را جدید ذخیره کنید | فایل جدید را ذخیره کنید | | تنظیمات را کاربر تغییر دهید | تنظیمات کاربر را تغییر دهید | | نام را کاربر جدید وارد کنید | نام کاربر جدید را وارد کنید |

Common error: omitting را with definite objects. Translators with English

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: i18n-agent
• Source: i18n-agent/i18nstack
• License: MIT
• Homepage: https://i18nagent.ai

Install and usage instructions live in the source repository linked above.