Community라이팅 & 에디팅github.com

persian-writing

Write, translate, edit or review Persian (Farsi) so it reads as fluent, plain Persian written by an Iranian professional, not as English rendered word for word and not as bookish or office-form Persian. Use for every piece of Persian, including blog and news articles, marketing and product pages, titles, excerpts, chart labels, interface labels, messages, errors, help text, assistant replies, letters and SMS. Use it even when the request only says "add the Persian version", "translate this", "make it bilingual", "فارسی‌اش را بنویس", or when Persian strings are a small part of a larger code change. Also use when someone says Persian text sounds translated, stiff, unnatural, robotic or "not proper Persian".

persian-writing란 무엇인가요?

persian-writing is a Claude Code agent skill that write, translate, edit or review Persian (Farsi) so it reads as fluent, plain Persian written by an Iranian professional, not as English rendered word for word and not as bookish or office-form Persian. Use for every piece of Persian, including blog and news articles, marketing and product pages, titles, excerpts, chart labels, interface labels, messages, errors, help text, assistant replies, letters and SMS. Use it even when the request only says "add the Persian version", "translate this", "make it bilingual", "فارسی‌اش را بنویس", or when Persian strings are a small part of a larger code change. Also use when someone says Persian text sounds translated, stiff, unnatural, robotic or "not proper Persian".

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ZharfAI/persian-writing/tree/HEAD/skills/persian-writing

Installed? Explore more 라이팅 & 에디팅 skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

Writing Persian that reads as Persian

Why this exists

Persian written from an English source usually comes out grammatical and wrong at the same time. Each sentence follows the English one: same order, same connectors, same nouns where Persian would use a verb, and the first dictionary word for every term. A native reader hears it at once and calls it what it is, a direct translation.

The skill grew out of one article that called an essay «جستار» and its appendix «پیوست جستار». Neither is a mistranslation. «جستار» is a literary word nobody uses for a blog essay, sitting in sentences built one by one from English. Two terminology reviews had passed that text, because both compared it with the English and checked that the terms were accurate. They were.

So a longer glossary does not fix this, and neither does a list of banned phrases. What fixes it is changing how the Persian gets written and how it gets checked: write from the content, not from the English sentences, and check by reading the Persian alone, as its reader will.

The method

Follow these in order for any text longer than a few strings. The short version for interface strings is at the end of this section.

1. Know the reader and the surface

Decide who reads this and where, because that sets the register. An accountant reading an error message, an engineer reading a blog article and a manager reading a product page are three different jobs. The table under "Register by surface" says what each needs and which reference file to read before writing.

2. Take the content out of the English

Read the source until you understand it. Then write notes, in any language, of what the reader must come away with: each fact, each number with its unit, who said what, how sure they were, and the order of the argument. Notes, not sentences.

If you cannot note a passage plainly, you have not understood it yet, and a translation of it will be fog in two languages.

3. Write the Persian from the notes

Put the English away and write from the notes, as you would explain the matter to an Iranian colleague who has not read the source. You decide where sentences start and end, what gets its own paragraph, and what the headings are. A Persian heading is the heading a Persian editor would put on that section, not the English heading in Persian words.

This is the step that matters. If you find yourself looking at an English sentence to see what comes next, you are translating again; go back to the notes. The same goes for an existing Persian translation: polishing it sentence by sentence keeps its English vocabulary and its English order of ideas. When asked to fix stiff Persian, take notes of what it says and write it again. Editors who work on translated Persian give the same instruction. Ali Khazaeefar, in a talk reported by the editing house ویراستاران, says the writer must be able to write an independent text «صرف‌نظر از اینکه ساختار متن مبدأ چیست». And ویراستاران, in a post titled «فارسی حرف می‌زنیم؛ ولی انگلیسی فکر می‌کنیم!»: «برای فارسی حرف‌زدن هم باید فارسی فکر کنیم».

A worked case:

The company says the new model allows developers to build agents that can work for hours without supervision. However, independent testers found that it still suffers from hallucinations on long tasks, and they caution that the results should be treated as preliminary.

Sentence by sentence, this becomes:

شرکت می‌گوید مدل جدید به توسعه‌دهندگان اجازه می‌دهد عامل‌هایی بسازند که می‌توانند برای ساعت‌ها بدون نظارت کار کنند. با این حال، آزمایش‌کنندگان مستقل دریافتند که این مدل همچنان در وظایف طولانی از توهم رنج می‌برد، و آن‌ها هشدار می‌دهند که نتایج باید به‌عنوان مقدماتی در نظر گرفته شوند.

Every word is defensible and the whole is English. From notes (company's claim: developers can build agents that run for hours unsupervised; independent tests: still invents answers on long tasks; the testers' own caution: treat the results as preliminary), a Persian writer says:

به گفتهٔ شرکت، توسعه‌دهندگان با مدل جدید می‌توانند عامل‌هایی بسازند که ساعت‌ها بدون نظارت کار کنند. ولی آزمایش‌های مستقل نشان می‌دهد مدل در کارهای طولانی هنوز دچار توهم می‌شود، و خود آزمایش‌کنندگان هشدار می‌دهند که این نتایج را باید مقدماتی دانست.

Every fact and every hedge is still there. "Allows developers to" became «توسعه‌دهندگان با مدل جدید می‌توانند», "However," became «ولی», "suffers from" became «دچار … می‌شود», and "should be treated as preliminary" became «را باید مقدماتی دانست».

4. Name things the way Iranians in that field name them

For each term, ask what an Iranian engineer, accountant or journalist calls it, not what the dictionary gives. "Choosing a word" below has the order of preference. Read references/word-choice.md before writing about AI, software or accounting.

5. Check the facts against the source

Now open the English again, for one purpose: every number, unit, name, date, negation, comparison ("more than", "up to", "at most") and hedge ("about", "may", "the authors estimate") must be in the Persian and say the same thing. Writing freely makes it easy to drop a qualifier, and a literal translation once turned "up to 10,000 times less" into "at most one ten-thousandth" in the same article. Nothing may be added either.

Quotations are the exception to free writing: a quoted sentence keeps its meaning exactly, in natural Persian, inside «».

6. Read it cold, with three tests

Read only the Persian, from the top, as the reader.

  • Would I say this to a colleague? Not slang; the sentence you would actually speak in a meeting. «این ابزار به شما اجازه می‌دهد» fails. So does «جستار». Abolhassan Najafi's rule, as ویراستاران quote it from «غلط ننویسیم»: a form that exists only on paper and never entered speech goes against the nature of Persian.
  • Can I rebuild the English from it? If a phrase maps back word for word onto an English phrase, and a Persian speaker would have put it differently, rewrite it.
  • Did I read anything twice? A sentence the reader has to reread is too long, has its verb too far away, has a chain of linked nouns, or contains a word that can be read as a different word. Split it or reorder it.

Then check the names. List the dozen things the text talks about most, and search the text for each. Every one should have a single Persian name from start to finish, and that name should be what the thing is called, not the English noun in Persian letters. This is where a text written from an English source gives itself away even when its sentences are fine: "compute" turns up as «محاسبه» in one place and «توان پردازشی» in another, a company's published "measurements" become «اندازه‌گیری‌ها» instead of «آمار», "evidence" becomes «شاهد», "the median researcher" becomes «پژوهشگر میانه».

references/translationese.md names the common shapes of the fault, with repairs. Use it to diagnose a sentence that fails, not as a checklist to pass.

7. Give it to a fresh reader

You cannot see your own calques: you know the source too well. Hand the Persian, and only the Persian, to a reader who has not seen the English or this conversation. With subagents available, start one with this brief and nothing else:

You are an Iranian reader. Below is a Persian text written for [who] to appear on [where]. You have not seen any source. Read it once, at normal speed, and report: (1) every phrase that sounds translated from English, with the English phrase you think is behind it; (2) every word or phrase nobody would say aloud in this setting, or that reads bookish, official or invented; (3) every sentence you had to read twice. For each, quote it and give the wording you would have used. Then say in one line whether you would take this for a text written in Persian or for a translation. Do not rewrite the whole text and do not praise it.

Expect the first reader to find a lot. On the article this skill was built around, a careful rewrite by the method above still came back with fifty items and the verdict "a translation, or more exactly an Iranian's careful retelling written with the English open beside them". The reader caught a sentence that could be read with the wrong verb, a label whose Persian sense was the opposite of the English one, a count announced as three above a table of five rows, and one concept under three names. None of that is visible to the writer.

Readers also contradict each other: one finds «پرشمارتر» invented, the next proposes it; one calls «هفته منتهی به» accounting language, the next asks for it. Take what two readers agree on, and where they split, choose the plainer form and list it among your judgment calls.

Fix what it finds, and judge its suggestions yourself: a reader's replacement can be worse than the original, can go colloquial, or can change a fact, so check any reworded claim against the source again. Then give the fixed text to a new reader, because one who has seen the earlier draft is no longer fresh. Stop when a reader takes the text for Persian writing and what remains is taste. Plan on two or three rounds for an article, and do not expect the last one to come back empty: on the test article the third reader still listed 36 items. Say in your report how many ran and what the last verdict was. Without subagents, leave the text, do something else, and reread it from the top before delivering.

A reader who is shown the English checks accuracy and misses fluency. That is how «جستار» passed twice.

8. Run the spelling check

python3 scripts/fa_check.py path/to/file.mdx path/to/Component.tsx

The script is in this skill's scripts/ folder; give its full path when you run it from somewhere else. Fix everything under "Spelling", unless the text is quoting a fault on purpose (an article about half-spaces will show «می رود»). Version numbers, codes and identifiers in Latin digits are right and are not reported. The "Phrases" section lists wording that often marks translated, office or bookish Persian; read each hit in its sentence and change it only if a plainer sentence says the same thing. A clean run means these mechanical checks passed. It does not prove the spelling, which references/spelling.md covers more fully, and it says nothing about the prose.

Short strings

For a button, a label or a one-line message there is no source to step away from, but the same idea holds: do not translate the English string in your head. Picture the person at their desk and write what you would tell them. Then run test one from step 6 and the spelling check. Read references/interface-text.md first; it has the forms Iranian products use for each kind of string.

Three ways it goes wrong

Check for all three. Fixing one often pushes a text into another.

English underneath. Persian words on an English frame. The common signs: a doer hidden behind «توسط»; a noun where Persian wants a verb («انجام بررسی»، «عدم وجود»); «مورد … قرار گرفتن»; pronouns the verb already carries («شما می‌توانید»); «یک» for "a"; «به‌طور …ی» for every adverb; «اجازه می‌دهد» for "allows"; a connector at the head of each sentence; English images carried over («بار استدلال را بر دوش دارد»); headings translated instead of written.

It also hides in the vocabulary of the argument, where each word is the dictionary's answer for an English word: «انتظار دارد» for "expects" (a Persian writer says «پیش‌بینی می‌کند» or «فکر می‌کند»), «استدلال می‌کند» for "argues" («می‌گوید»), «شاهد» for "evidence" («مدرک»، «نمونه»، «دلیل»), «شتاب» for "speed-up" (to an engineer that is acceleration; say «افزایش سرعت»), the author's name in every sentence because English repeats it. One of these is nothing. A page of them reads as English.

Bookish and invented words. Reaching past the everyday word for a literary one, or building a new compound because English has a single word. «جستار» for an article, «سنجه» for a metric, «واکاوی» for a review, «درنوردید» for "swept through", «پرشمار» for "many", and coinages like «وارسی‌پذیر»، «راستی‌آزمایی‌پذیر»، «نمره‌پذیر». Avoiding English loanwords at any cost produces this. Persian editors treat it as a fault of the same weight as translationese. Persian Wikipedia's style manual says «رسمی‌نوشتن لزوماً به معنی متکلف نوشتن یا به کارگیری کلمه‌های ثقیل نیست», and its page on purism gives the test: «وضوح برای اکثریت».

Office register and word soup. «می‌باشد»، «گردید»، «نمایید»، «جهتِ»، «در خصوصِ»، «لازم به ذکر است» make a text sound like a circular. It is native Persian, so "avoid calques" does not catch it. The other form is the opposite: leaving English words in Latin script mid-sentence («updateهای outlier را بدون ایجاد side channel مانیتور نمایید») where a Persian or Persian-script word exists.

The target between them is نثر معیار: the standard written Persian of a good Iranian newspaper or a well-edited product. Not colloquial either: «می‌تونی» and «الزامیه» belong to consumer brands that chose that voice on purpose.

Choosing a word

In this order:

  1. The word an educated Iranian in that field says aloud, whatever its origin: «مقاله»، «کامپیوتر»، «ایمیل»، «فاکتور»، «مدل». Settled Arabic and European loanwords are Persian words.
  2. A Persian coinage only if it has already won in everyday use: «نرم‌افزار»، «پیامک»، «هوش مصنوعی»، «یادگیری ماشین». Not one that lives in Academy lists («رایانامه» for email).
  3. A technical loanword in Persian script, as practitioners write it: «بنچمارک»، «توکن»، «پرامپت». Product names, acronyms and code stay in Latin script; section 6 of references/word-choice.md says which company and personal names are written in Persian script.
  4. A term with no settled Persian form: explain it in a short plain phrase and give the English once in parentheses at first use. After that, use the Persian phrase.
  5. Never coin a compound and never pick a literary synonym to avoid a common word.

When you are not sure which form people use, do not decide from memory. Search Persian sources for the candidates in quotes (a general search, or restricted to outlets such as zoomit.ir, digiato.com, peivast.com) and take the form working writers use. If usage is split, take the plainer one and keep it throughout.

Weigh who is using it. A form that appears only in Persian news items translated from English may itself be a word-for-word rendering. A pattern Persian already uses for the same idea outranks it: for "research taste", two tech outlets write «سلیقه پژوهشی», but Persian says «شمّ اقتصادی»، «شمّ سیاسی» for exactly this kind of instinct, and readers hear «سلیقه» as personal preference. When the corpus and a native reader disagree, say so in your report and let the person you are writing for choose.

One name per thing in one text. Persian tolerates repeating a noun far better than English does; do not rotate synonyms for variety.

Register by surface

SurfaceReaderWhat it should sound likeRead before writing
Blog and news articlesengineers, managers, curious general readersa well-edited Iranian tech publication: plain standard prose, real verbs, the argument in the writer's own orderreferences/articles.md, references/word-choice.md
Marketing and product pagesa business decision-makerdirect and concrete; what it does and for whom, in the words they would use; no hypereferences/articles.md section 8
Titles, excerpts, chart titles and labelsscannersshort noun phrases or a plain question; nothing that needs the English to be understoodreferences/articles.md
Interface labels, messages, errors, helpsomeone in the middle of their workshort, exact, polite; says what happened and what to doreferences/interface-text.md
Replies of a built-in assistantthe same persona capable colleague reporting what they found, figure firstreferences/interface-text.md section 5
Letters, SMS, printed formsoutside recipientsthe genre's own conventions, plain bodyreferences/interface-text.md section 6

What outranks this skill

  • Words the project has fixed. Product names, brand spellings, status labels and other terms recorded in the project's instructions. Use them as given.
  • The product's existing vocabulary. Before naming something in an interface, search the product for how it already names it, and use that. If a fresh reader cannot tell what an existing word does, keep it for consistency and raise the rename with the person you are writing for instead of deciding alone.
  • Existing text you were not asked to change. This governs new Persian and Persian you were asked to improve. Do not restyle a file in passing.
  • Official wording: laws, tax and bank forms, and the conventional frame of an official letter.
  • The project's publishing checks. If the project has length, heading, link or source-parity rules for articles, a freer Persian article still has to pass them.

Do not overcorrect

A list of faults in a reviewer's hands makes new faults. Section 8 of references/translationese.md has the cases. The short form: «توسط» is fine when a passive is really needed; «چالش»، «قابل قبول»، «یکی از مهم‌ترین» are ordinary Persian; loanwords people use need no replacement; a repair that draws more attention than the fault is not a repair; and one stiff phrase in a page harms nothing. Aim at how the whole reads.

When you hand it over

Say, in a few lines:

  • the three to six word choices that were judgment calls (the English term and the Persian you chose), so the person you are writing for can overrule them in one reply;
  • anything in the source you could not carry over exactly, and what you did instead;
  • that the fresh-reader check and the spelling check ran, and what they found.

A native reader is the final judge. If the person you are writing for reads Persian, their ear outranks every reviewer agent, and a reviewer agent passing the text is not evidence that it is good.

Reference files

  • references/translationese.md — the shapes of translated-sounding Persian with repairs, and what not to "fix". Read when a sentence fails the reading tests.
  • references/word-choice.md — everyday words against bookish ones, and the AI, software and business vocabulary Iranian writers actually use. Read before writing about technology.
  • references/articles.md — how Iranian tech writing phrases attribution, numbers, hedges, dates and headings, and how to write chart labels and marketing pages.
  • references/interface-text.md — labels, messages, errors, help, assistant replies, accounting words, and what to do with a product's own rules.
  • references/spelling.md — half-space, letters, digits, numbers, dates, punctuation, Latin words in Persian text.
  • references/sources.md — where the guidance comes from, and what is still unconfirmed.
  • scripts/fa_check.py — the spelling and phrase check.
  • scripts/build_phrases.py — the source of scripts/phrases.tsv. To flag a new phrase, add a row to ROWS in that file and run it; it rewrites phrases.tsv next to itself.

관련 스킬