persian-writing

ペルシア語の文章とRTL文書

ペルシア語の出力が機械生成のように見える原因は2つあり、それぞれ独立しています。

1. 文章がAIらしく聞こえます。 技術的には正しいものの、堅苦しく、書き言葉に偏り、大げさで、 イラン人ならそのようには書きません。
2. レイアウトが文章の不自然さを際立たせます。 ペルシア語が左揃えで表示される、アラビア語の ي/ك の字形が使われる、 ラテン数字がRTLの流れを妨げる、見出しがページ下部に取り残される、フォントが DejaVuにフォールバックする、といった問題です。

どちらか一方だけを直しても、ネイティブの読者がスクリーンショットを撮って笑うような仕上がりになります。このスキルでは両方に対処します。以下の2つのチェックリストに沿って作業し、何かを生成する前に、出力形式に対応するリファレンスファイルを読んでください。

ステップ0：タスクに応じて参照先を選ぶ

タスク	参照先
ペルシア語の文章全般（必須）	references/writing-style.md
機械的な正確性（必須）	references/orthography.md
学術文書：論文、学位論文、レポート、مقاله/پایان‌نامه	references/academic.md
教育・技術コンテンツ、ドキュメント、製品ページ、ハウツー	references/content-structures.md
Telegram、Instagram、キャプション、カルーセル、リール、ストーリー	references/social-channels.md
SEOコンテンツ、検索向けブログ、ランディングページ／広告文、کپشن فروش	references/seo-copywriting.md
既存テキストの整理・正規化・スペルチェック（ویرایش، پاکسازی）	references/cleanup/paknevis-rules.md + usage-patterns.md
フォントの選択／埋め込み	references/fonts.md
Word/.docx または docx→PDF	references/docx-pdf.md
PowerPoint/.pptx	references/pptx.md
HTML、メールテンプレート、HTML→PDF	references/html-css.md
画像／ポスター（PIL）、新規PDF（reportlab）、Excel	references/format-skills-fa.md

視覚的な中立性 — コード例をコピーする前に読んでください。 このスキルはスタイルを一切指定しません。方向、間隔、字形形成用フォント、テキストを扱いますが、色、アクセントバー、カード背景、固有の見た目は扱いません。コード例にある16進カラーコード、枠線、塗りつぶしはすべて、単なる例として無彩色のグレー／黒で記載されています。これらはプロパティをどこに指定するかを示すものであり、どの値を使うかを示すものではありません。既定の出力は、既定の背景に黒いテキストを置き、アクセントカラーは使いません。色や見た目を取り入れるのは、ユーザーからの明示的な依頼、添付されたブランド／テーマ用スキル、または再現対象の入力テンプレートからの場合に限ります。それらがない場合は配色を独自に作ったり、例ごとに使い回したりしないでください。スタイルを加えないのが正しい既定値であり、予期しない紫色の見出しは不具合です。

このスキルは、一般的なdocx/pptx/pdfスキルと組み合わせて使えます。それらのスキルはファイルの仕組みを扱い、このスキルはペルシア語向けにそのルールを上書き・拡張します。RTLの動作について両者の指示が食い違う場合は、このスキルを優先してください。実際のペルシア語文書のデバッグに基づいたルールだからです。別の有効なスキルやユーザーが特定のフォントや色を指定している場合は、見た目についてはそちらを優先してください。このスキルは引き続きRTLの仕組みと正書法を扱います。このスキル自体はブランドに依存しません。コード例の色はプレースホルダーであり、Vazirmatnは単なる既定のフォントで、必須ではありません。

ライティング：5秒で読める要約

完全なガイドは references/writing-style.md にあります。基本的なポイントは次のとおりです。

1. 一言も書く前に文体を見極めてください。文体を誤ることは、このスキルが犯しうる最も重大なミスです。 writing-style.md Part 1 の6段階の判定手順に従ってください。基本ルール：ユーザーが入力した口調ではなく、成果物の種類を分類してください（「プロポーザルを書いて」というくだけた依頼でも、正式なプロポーザルが必要な場合があります）。文章が第三者に向けたもので、対立を示す兆候がある場合は、推測せずに短い質問を1つしてください。兆候がまったくない場合は、フォーマルでありながら人間味のある文体にします。
   • プロポーザル、請求書、レポート、公式メール、ウェブサイトの文章 → フォーマルでありながら人間味のある文体：完全な書き言葉を使い、敬語を用い、俗語は一切使いません。ただし、過度に堅苦しい表現は避け、短い文と具体的な主張を使います。人間味があることとくだけていることは別です。提案書や契約書では、語彙もフォーマルに保ちます。親しみやすさは、明快さ、数字、そして締めくくりの温かい一文から生まれます（writing-style.md、「親しみやすさの落とし穴」）。
   • 公式文書 → フォーマルな文体と書簡の慣例（敬称、「謹啓」にあたる挨拶など。writing-style.md を参照）。
   • Instagram／Telegram、チャット、親しみやすいメール → 書き言葉としての口語体：口語的な表現や助詞を使います。
   • ブログ、ニュースレター → 中間的な文体：書き言葉を使い、温かく直接的な語り口にします。
   • 論文、学位論文、大学のレポート → 学術文体：慎重な表現を用い、断定を避け、受動態も使用できます。儀礼的な表現は使いません。references/academic.md を参照してください。
   • SEO／セールスコピー → 上記の成果物に応じた文体を使い、さらに references/seo-copywriting.md を参照してください。
2. 官僚的な表現を避けてください：「〜であることに言及する必要があります」、「〜に向けて」、「特に重要な役割を果たします」、「大きな役割を担います」など。
3. AIらしい表現を避けてください： em ダッシュ（—）、三つ並べる定型句（「速く、簡単で、確実」など）、「〜だけでなく……も」、後付けの「これは〜を示しています」、曖昧な「専門家によると」、ありきたりな「今日の世界では」という書き出し、「最後に、〜と言えるでしょう」という締めくくり。
4. 視点を一貫させてください。 事実は非人称で説明し、読者には直接語りかけます（動詞に呼びかけを含め、「あなた」を繰り返さないでください）。「私たち」は、組織が実際に行ったこと、または責任を負うことにのみ使います。1つの節の中でこの3つの視点を行き来するのは、ペルシャ語のブランドコンテンツで最もよく見られる欠点です。content-structures.md §1 を参照してください。
5. 説明と販売を分けてください。 説明は、何も買わなくても読む価値があるものにしてください。製品より先に問題を説明し、主な答えを隠さず、各機能を検証可能な結果に結びつけ、制限事項や前提条件を削除しないでください。そうした情報があるからこそ、ほかの内容にも信頼性が生まれます。
6. 情報源が裏付けることだけを主張してください。 事実／意見／予測／主張を区別します。節を埋めるために統計、バージョン、価格、引用を作り出してはいけません。矛盾は黙って解消せず、明示してください。推測する代わりに質問を1つしてください（content-structures.md §3）。 論文の言い換え（特に学位論文の章）では、変更するのは語句と構成だけです。推論やつなぎの説明を加えず、限定を表す語句（およそ、主に、可能性がある、まで、少なくとも、有意な）とすべての数字を、情報源のとおり正確に保ちます。研究者自身の推論は本文に織り込まず、「この部分は論文に記載されていません」と明記してください（academic.md §5.5）。
7. ネイティブらしさの確認： イラン人がこれを「AIが書いた文章」としてスクリーンショットに撮るでしょうか。そうであれば、提出前に書き直してください。主な原因は2つです。予測可能性（毎回お決まりのコロケーションを使うこと。例：特に重要な役割、大きな役割）と、均一性（すべての文が15〜20語で、すべての段落が同じ分量であること）です。具体的な内容が本物の変化を生みます。fa_lint.py --check --rhythm は単調なリズムを検出しますが、語彙の癖のほうがはるかに重要です。writing-style.md §3.5 を参照してください。 目指すのは、検出器に合わせて調整した文章ではなく、本当に優れた文章です。AI検出器は信頼性が低く、第二言語で書く人を非常に高い割合で誤検出します。また、このスキルは著者を偽るための支援を一切しません（§3.6）。
8. 数字、句読点、スペースはペルシャ語表記にしてください。次のセクションを参照してください。

正書法：必須ルール

すべてのルールは references/orthography.md に記載されています。すべての成果物に適用されます。

1. ZWNJ（نیم‌فاصله、U+200C） — می‌شود と書き、می شود とは書きません。کتاب‌ها と書き、کتاب ها とは書きません。 بزرگ‌تر、خانه‌ام、به‌عنوان。コード内では ‌ または HTML の ‌ を使います。
2. ペルシア文字のみを使用： ي ではなく ی（U+06CC）、ك ではなく ک（U+06A9）を使います。
3. ペルシア語のテキストではペルシア数字 ۰۱۲۳۴۵۶۷۸۹ を使います。URL、メールアドレス、コード、バージョン番号ではラテン数字を使います。アラビア・インド数字の٤٥٦形式は使いません。
4. ペルシア語の句読点： ، ؛ ؟ と、引用符には «ギヨメ» を使います。句読点の前にスペースを入れず、後ろにはスペースを1つ入れます。 4b. هکسره — ezafe の kasre を「ـه」と書いてはいけません。「کتابِ من」と書き、「کتابه من」とは書きません。 「ـه」で終わる形は、口語の「است」（「این کتابه」= این کتاب است）に限ります。 「است」に置き換えて文が成立しない場合は、kasre が必要です。 イランの人々はこの誤りを不注意の表れと見なします。orthography.md §5.1 を参照してください。
5. ペルシア語の文章では em ダッシュと en ダッシュを使いません。「،」を使うか、文の構成を変えてください。
6. ペルシア語の文字間にスペースを入れてはいけません（文字の連結が崩れます）。太字や斜体を偽装してはいけません。
7. ペルシア語の行をラテン文字の単語で始めてはいけません。チャットアプリ、GitHub、Telegram、およびほとんどのエディターでは、段落の最初の文字を基準に各段落の方向が決まるため、「React یک کتابخانه است.」は左から右に表示され、配置が誤りになり、ピリオドが逆側に来て、単語の並びも崩れます。これは文、箇条書き、見出し、表のセル、キャプションすべてに当てはまります。先頭はペルシア語の単語にしてください。 「کتابخانه‌ی React…」、「ابزار Docker…」、「دستور npm install…」のようにします。 行を名前で始める必要があるプレーンテキスト出力では、persian_cleanup.py --bidi が不可視の方向制御マークを追加します。詳しいルールは orthography.md §9 を参照してください。

2つのスクリプトでこれらのルールを機械的に適用できます。ペルシア語のテキストを納品する前に、両方を使ってください。

# 1. FIX: paknevis-style editorial pass (ZWNJ, chars, digits, punctuation, گیومه)
python3 scripts/persian_cleanup.py --edit --in text.md --out text.md
# 2. LINT: report what still needs contextual judgment (dashes, میشود forms,
#    fake tanvin, register issues) — fix these by hand
python3 scripts/fa_lint.py --check text.md

--edit は構造化ファイルでも安全に使えます。処理前にフェンス付きコードブロック、インラインコード、表の行を退避し、バイト単位で変更せずに復元します。また、先頭のインデントがまとめられることもありません。ペルシア語の組版ルールは文章には適切ですが、コードには破壊的な影響を与えるため、これは重要です。これらのルールを適用すると、"text" が «text» に変わり、ASCII 数字がペルシア数字に書き換えられ、表の列に必要な空白が失われます。すべての場所にルールを適用したい場合に限り、protect_code=False（Python API）を指定してください。いずれの場合も、ファイルはバージョン管理に残してください。このツールは慎重ですが、万能ではありません。

persian_cleanup.py は、paknevis と davat を統合した包括的なツールキットです。NLP 向けの強力なクリーニング（--preset persian）、単独の関数（--fn convert_digits）、同梱の453K語の頻度辞書を使ったスペルチェック（--edit --spellcheck）、カスタムパイプラインに対応しています。ペルシア語で「ویرایش」を依頼された場合は --edit（保守的で、内容を保持）を使います。「پاکسازی/نرمالایز」を依頼された場合は --preset persian（リンク、メンション、絵文字を削除）を使います。詳細は references/cleanup/ を参照してください。注：--edit は خانهٔ の ezafe 表記を適用します。خانه‌ی を維持するには、--steps から fix_ezafe を削除してください。

フォント

assets/fonts/ に同梱されています（SIL OFL、商用利用も無料）：

• Vazirmatn — 本文、UI、ドキュメントなど、すべての用途における既定のフォントです。9種類のウェイトがあります。
• Lalezar — 見出し、表紙、ポスター向けのディスプレイフォントです。1種類のウェイトのみで、本文には使いません。

その他のファミリー（Shabnam、Sahel、Samim、Parastoo、Tanha、Gandom）と組み合わせ方のアドバイスは references/fonts.md を参照してください。オフラインのサンドボックスでは同梱フォントのみ使用できます。scripts/download_fonts.py が動作するのは、GitHub に接続できる環境に限られます。

docx→PDF または pptx→PDF に変換する前に、必ずフォントをインストールしてください：

bash scripts/install_fonts.sh   # copies assets/fonts → ~/.fonts, runs fc-cache
fc-list | grep -i vazir         # verify — else LibreOffice silently falls back

これを省略すると、ペルシア語のPDFが崩れる原因の第1位になります。変換は「成功」しても、すべての字形が DejaVu の豆腐文字になったり、文字の連結が切れたりします。

ドキュメント：常に適用されるルール

形式ごとの手順はリファレンスファイルに記載されています。以下はすべてに共通するルールです。

1. RTL は右ではなく、先頭を意味します。 OOXML で bidirectional: true の場合、 AlignmentType.RIGHT は視覚的には左に表示されます。常に START に揃えてください。
2. ペルシア語の各ランには、rightToLeft: true と hint: "cs"（複合スクリプト）を指定したフォントを設定します。
3. 各セクションには bidi: true を設定します。右から左に流す必要がある表には、 visuallyRightToLeft: true を設定します。
4. 番号付きコンテンツではペルシア数字を使います — ラテン文字の「1.」は段落を LTR に反転させます。 したがって、docx では組み込みの List Number／List Bullet スタイルを使ってはいけません。 これらのマーカーは numbering.xml にあり、bidi がないため、ラテン文字の「1.」が誤った側に表示され、 さらにフォント埋め込みを妨げる OpenSymbol の箇条書きが使われます。 マーカーは通常のランとして記述します（«۱. »、«• »）— docx-pdf.md §6.1。
5. コンテンツを追加する前に、ドキュメントの既定値を修正します。 python-docx はラテン文字用テンプレートから開始します。styles.xml にペルシア語フォントがなく、Word の見出しスタイルには指定していない青色が設定されています。Document() の直後に docx-pdf.md §6.1 の persianize_styles(doc) を実行してください。ヘッダーとフッターは別の XML パーツなので、RTL の処理をそれぞれに直接適用する必要があります。
6. ページ分割： 見出しには keepNext + keepLines を設定します（見出しだけがページ末尾に残るのを防止）。カードやボックスは cantSplit: true を設定した単一セルの表に入れます（ページをまたいで分割されないようにします）。リストの最後の項目の後に区切り線を置きません。セクション区切りの前に余分な PageBreak を置きません（空白ページの原因になります）。
7. 記号： ペルシア語フォントには多くのグリフがありません。バンドルされている Vazirmatn／Lalezar で確認済みなのは • と · のみです。▪ ■ ✓ ✕ ● ◆ ⊙ は DejaVu にフォールバックします。その他の記号やフォントを使う場合は、まず cmap を確認してください（方法は fonts.md を参照）。

提出前の検証

確認事項は 2 つあります。変換前に .docx を確認し（コードレビューでは見つけられない問題を検出します）、その後 PDF を確認します。

# 1. DOCX: package integrity FIRST (a file Word won't open can't be RTL-checked),
#    then section bidi, jc=right traps, cs fonts, list numbering, heading colors.
#    --fix repairs missing <w:bidi/>; --sanitize strips the Word-for-Mac template
#    artifacts python-docx inherits (the classic "file is corrupt" fingerprint).
python3 scripts/verify_docx.py output.docx --expect-font Vazirmatn --fix --sanitize

# 2. PDF: fallback fonts, blank pages, template leaks, Arabic chars
python3 scripts/verify_pdf.py output.pdf --expect-font Vazirmatn

verify_docx.py が存在するのは、RTL フラグを設定することと、そのフラグが XML に反映されることは別だからです。ライブラリがセクションプロパティから bidi を削除することがあり、OOXML では <w:bidi/> が <w:sectPr> の最初の子要素である必要があります。別の位置に追加しても、レンダラーは無視します。ソースコードではなく、生成物を検証してください。

このツールはパッケージ自体もチェックします。[Content_Types].xml が ZIP の最初のエントリであること、すべてのリレーションシップの Target が解決できること、すべての XML パーツが整形式で制御文字を含まないことを確認します。修復は一時ファイルに書き込み、何かを置き換える前に検証されるため、修復に失敗してもドキュメントが破損することはありません。詳細と、すでに破損しているファイルの手順については、docx-pdf.md §4.5 を参照してください。

チェック項目は、ほぼ空白のページ、「undefined」やテンプレートの残存、フォントが埋め込まれていないことやフォールバックしていること、抽出されたテキストに含まれるアラビア文字の ي／ك、ページ数です。すべての警告を修正し、再生成して再検証してください。文章については、最終テキストをネイティブ話者のテストと照らし合わせて読み直してください。persian_cleanup.py --edit + fa_lint.py --check を 1 回実行し、さらに声に出して正直に読み上げれば、ほとんどの大きな問題を発見できます。

ファイル

persian-writing/
├── SKILL.md                    ← you are here
├── references/
│   ├── writing-style.md        ← registers, Persian AI tells, colloquial patterns
│   ├── academic.md             ← نگارش علمی: papers, theses, citations, formulas
│   ├── orthography.md          ← ZWNJ, characters, digits, punctuation, ezafe
│   ├── cleanup/                ← paknevis rules, davat API, usage patterns
│   ├── fonts.md                ← catalog, personalities, pairings, embedding
│   ├── content-structures.md   ← POV, education vs promotion, body patterns
│   ├── social-channels.md      ← Telegram/Instagram craft, repurposing
│   ├── seo-copywriting.md      ← Persian SEO writing + کپی‌رایتینگ
│   ├── docx-pdf.md             ← RTL docx recipes, pagination, PDF post-processing
│   ├── pptx.md                 ← RTL PowerPoint via python-pptx / html2pptx
│   ├── html-css.md             ← RTL web, mixed-direction text, print CSS
│   └── format-skills-fa.md     ← PIL posters, reportlab PDFs, Excel RTL
├── scripts/
│   ├── persian_cleanup.py      ← FIX: edit/clean/normalize/spell-check (paknevis+davat)
│   ├── fa_lint.py              ← LINT: report issues needing contextual judgment
│   ├── verify_docx.py          ← DOCX RTL checks (+ --fix for section bidi)
│   ├── verify_pdf.py           ← post-generation PDF checks
│   ├── check_version.py        ← verify the version matches in all four places
│   ├── install_fonts.sh        ← bundled fonts → ~/.fonts (run before PDF export)
│   └── download_fonts.py       ← fetch extra families (needs GitHub access)
└── assets/
    ├── fonts/                  ← Vazirmatn + Lalezar TTFs
    └── persian_words.txt       ← 453K-word frequency dictionary (spell-check)