# Localize Fa

> Use when translating or localizing UI strings, marketing copy, documentation, or any source text into Persian/Farsi (فارسی) for Iran (fa-IR) or Dari (fa-AF). Persian is NOT Arabic — SOV, NO gender, NO dual, ICU one/other plurals, and the defining ezafe construction (-e linker). Enforces the 4 extra letters پ چ ژ گ, Persian ی/ک (not Arabic), ZWNJ half-space in compounds, Persian numerals ۰۱۲۳, Sol…

- **Type:** Skill
- **Install:** `agentstack add skill-i18n-agent-i18nstack-localize-fa`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [i18n-agent](https://agentstack.voostack.com/s/i18n-agent)
- **Installs:** 0
- **Category:** [Productivity](https://agentstack.voostack.com/c/productivity)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [i18n-agent](https://github.com/i18n-agent)
- **Source:** https://github.com/i18n-agent/i18nstack/tree/main/localize-fa
- **Website:** https://i18nagent.ai

## Install

```sh
agentstack add skill-i18n-agent-i18nstack-localize-fa
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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](https://github.com/i18n-agent)
- **Source:** [i18n-agent/i18nstack](https://github.com/i18n-agent/i18nstack)
- **License:** MIT
- **Homepage:** https://i18nagent.ai

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-i18n-agent-i18nstack-localize-fa
- Seller: https://agentstack.voostack.com/s/i18n-agent
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.