persian-skill

persian: a Claude skill for Persian (Farsi) translation and text mechanics

Makes Claude translate English ↔ Persian the way a good human translator does (idiomatic, register-matched, faithful, and free of the ChatGPT fingerprint), and fixes the small mechanical things that make Persian look right: right-to-left layout, the half-space (ZWNJ / نیم‌فاصله), Persian letters instead of their Arabic look-alikes, Persian digits, and proper punctuation.

It also works without translating. Point it at messy Persian and it cleans it up. Point it at Persian that "sounds like AI" and it rewrites it.

There is a portable version for ChatGPT, Gemini, and any other assistant in portable/.

Where the rules come from

The craft rules are not a list of opinions about good Persian. Each one is the residue of a diff. Model drafts of English literary prose were set against the published Persian translations of the same passages by working translators — امیرمهدی حقیقت، مهدی غبرائی and others — across a corpus assembled for the purpose: Lahiri's Interpreter of Maladies, Hosseini's The Kite Runner, Hemingway's The Old Man and the Sea, Ishiguro, Austen. Every place the model and the translator diverged was examined, and the ones that recurred became numbered rules with the worked example attached.

That is what references/pitfalls.md is: 56 stable rules (P1–P58, two retired), each with the EN source, the calqued version, and the version a professional would write. It is the part of this skill that cannot be regenerated by prompting, because it took the books.

The published translations are a style model, not a content model — Iranian editions sometimes cut alcohol, sex and politics, and this skill explicitly does not (P24).

Does it actually work?

Same model, same prompts, one variable: the skill.

Six discriminating evals × three runs per condition, graded blind by a separate model against assertions written before the benchmark existed. Full method, the honest caveats, and every raw output: evals/BENCHMARK.md.

The interesting part is where the 16 points live. Not in typography — on the pure-mechanics evals both conditions produced byte-identical Persian, because Claude already handles ZWNJ and ی/ک well. The gap is entirely in craft:

1 · Persian answers a negative question with «چرا», not «بله»

EN — "Isn't that the day the war started?" "Yes."

✗ «مگر همان روزی نبود که جنگ شروع شد؟» … «بله.» ✓ «مگر همان روز، روزِ شروعِ جنگ نیست؟» … «چرا، هست.»

2 · English agentless passive becomes Persian impersonal active (P32)

EN — The teachers were dragged out of the school and shot.

✗ معلم‌ها بیرون کشیده شدند و تیرباران شدند. ✓ معلم‌ها را از مدرسه بیرون کشیدند و تیرباران کردند.

3 · Reach for the idiom, not the paraphrase

EN — I left India in 1964 with a certificate in commerce and the equivalent, in those days, of ten dollars to my name.

✗ … تنها دارایی‌ام مدرکی در بازرگانی بود و آنچه در آن روزگار معادل ده دلار به‌شمار می‌آمد. ✓ سال ۱۹۶۴ با مدرکی در بازرگانی از هند رفتم و همهٔ دار و ندارم، به پول آن روزها، معادل ده دلار بود.

4 · A wrong idiom is worse than no idiom. Asked for the Persian for "cost an arm and a leg", the unaided model recommended «به قیمت خون پدرم تمام شد» and called it common usage. It isn't. With the skill: «کمرم را شکست»، «سرسام‌آور بود»، «به قیمت گزاف تمام شد» — and the note that no fixed calque exists.

Install

Pick one. Most people want the first.

1. Claude app or claude.ai (upload a zip)

1. Download persian.zip from the Releases page, or take it from whoever sent you here. The zip must contain a folder named persian with SKILL.md inside it. (GitHub's green "Code → Download ZIP" button gives you a folder named persian-skill-main, which Claude rejects because the folder name must match the skill name. Rename that folder to persian and re-zip it if that's what you have.)
2. In Claude, go to Settings → Capabilities and make sure Code execution and file creation is on. Skills need it.
3. Go to Customize → Skills, click +, then Create skill → Upload a skill, and pick the zip.
4. Toggle the skill on. Then ask normally: "translate this to Persian", "fix the نیم‌فاصله in this text", "make this Persian sound less like ChatGPT".

The same upload works for Cowork and the desktop app, since they read the skills on your claude.ai account.

2. Claude Code (copy the folder)

Put the skill folder at ~/.claude/skills/persian/ (on Windows: %USERPROFILE%\.claude\skills\persian\).

git clone https://github.com/Mojtaba-Alehosseini/persian-skill ~/.claude/skills/persian

Claude Code picks it up on the next session. Note that Cowork and cloud sessions don't read this folder; for those, use option 1.

3. ChatGPT, Gemini, or any other assistant (paste a prompt)

Open portable/PERSIAN-PROMPT.md and paste it into the instructions of a Custom GPT, a ChatGPT Project, a Gemini Gem, or a Claude Project. It is under 8,000 characters, which is the Custom GPT limit. For the small "custom instructions" box (1,500 characters on free ChatGPT), use portable/PERSIAN-PROMPT-short.txt. The portable version has no scripts, so the model applies the mechanics rules itself; it is a little less strict than the linter but covers the same ground.

نصب (به فارسی)

این مهارت (skill) به کلود یاد می‌دهد فارسی را مثل یک مترجم حرفه‌ای بنویسد، نه مثل ماشین: نیم‌فاصله‌ها درست باشد، «ی» و «ک» فارسی باشد نه عربی، اعداد فارسی باشد، و متن بوی ترجمهٔ ماشینی یا «چت‌جی‌پی‌تی» ندهد.

نصب در کلود:

۱. فایل persian.zip را بگیرید (از صفحهٔ Releases یا از کسی که این لینک را برایتان فرستاده). ۲. در کلود به Settings → Capabilities بروید و Code execution and file creation را روشن کنید. ۳. به Customize → Skills بروید، روی + و بعد Create skill → Upload a skill بزنید و فایل zip را انتخاب کنید. ۴. مهارت را روشن کنید. حالا فقط بنویسید: «این را به فارسی ترجمه کن» یا «نیم‌فاصله‌های این متن را درست کن».

برای چت‌جی‌پی‌تی یا جمینای، متن فایل portable/PERSIAN-PROMPT.md را در بخش Instructions بچسبانید.

What it does differently

Most "Persian mode" output reads like machine Persian: word-for-word calques, passive «شد» where Persian uses an active verb, Arabic ي and ك, missing half-spaces, Latin digits, and the officialese that models learned from government websites («می‌باشد», «مورد استفاده قرار می‌گیرد»). This skill works on both halves:

• Craft: the 56 rules described above, a catalog of AI-Persian tells, register guidance, and a review pass with back-translation for fidelity.
• Mechanics: a deterministic linter (persian_lint.py) that normalizes letters, ZWNJ, digits, punctuation, and spacing. It is idempotent, protects code and URLs, leaves English inside a Persian document alone, and flags ambiguous cases instead of guessing.

What the linter does, in one line:

in:  او مي رود و كتاب ها روي ميز است ، و بزرگ ترين آرزو همين بود 1964 .
out: او می‌رود و کتاب‌ها روی میز است، و بزرگ‌ترین آرزو همین بود ۱۹۶۴.

And the officialese it strips when writing Persian:

✗    این کتاب دارای سه فصل می‌باشد و توسط او نوشته شده است.   (officialese, AI tell)
✓    این کتاب سه فصل دارد و نوشتهٔ اوست.

When it writes a Word, PDF, or HTML file it sets RTL direction, start (visually right) alignment, and a Persian-capable font, so the page looks native rather than "Persian text on a left-aligned page".

What's inside

persian/
├── SKILL.md                     workflow, routing (translate / clean / write / look up), checklists
├── references/
│   ├── pitfalls.md              56 machine-Persian rules + worked EN↔FA exemplars
│   ├── ai-tells.md              signs of AI-written Persian and how to remove them
│   ├── typography-and-rtl.md    RTL, ZWNJ, digits, punctuation, file rendering
│   ├── register-guide.md        choosing and holding register; spoken vs written dialogue
│   ├── review-lenses.md         review lenses, priority order, verification checklist
│   └── lexicon.md               idioms, collocations, never-soften list, opt-in coinages
├── scripts/
│   ├── persian_lint.py          the mechanics linter (Python standard library only)
│   ├── lookup.py                builds a terminology brief from the banks
│   ├── test_scripts.py          regression tests
│   └── data/{idioms,glossary}.tsv
├── evals/
│   ├── evals.json               test prompts with checkable assertions
│   ├── BENCHMARK.md             with-skill vs without-skill: method, results, caveats
│   └── benchmark/               raw prompts, outputs and grader verdicts
└── portable/                    prompt versions for ChatGPT / Gemini / Claude Projects

The scripts need Python 3.7 or newer and nothing else.

python scripts/persian_lint.py --fix messy.txt            # cleaned text to stdout
python scripts/persian_lint.py --check --style draft.txt  # report, including officialese flags
python scripts/test_scripts.py                            # run the tests

Extending the term banks

scripts/data/idioms.tsv and glossary.tsv are small hand-curated seeds (format: EN <TAB> FA <TAB> note). Add rows to grow coverage; lookup.py surfaces only the entries that appear in a given source text, so the banks can scale without bloating context. NOTICE lists open-source banks you can ingest and their licenses.

Contributing

Issues and pull requests are welcome, especially new pitfalls with a real source, gold exemplars, term and idiom rows, and Persian AI tells you keep seeing. Run python scripts/test_scripts.py before submitting.

License

MIT. See LICENSE.