Communitygithub.com

rtl-typography

適用於波斯語(法爾西語)和阿拉伯語網頁介面的核心排版規則。當建構或樣式化包含波斯語、阿拉伯語、RTL、半空格或波斯字型的 UI 時使用。涵蓋字型選擇、ZWNJ(半空格)、波斯數字、標點符號、行高以及阿拉伯文字禁止使用字母間距等規則。

rtl-typography 是什麼?

這個技能提供了一套完整的排版規範,專門用於處理從右至左(RTL)書寫系統的網頁介面,特別是波斯語(法爾西語)和阿拉伯語。它整合了字型選擇策略(例如 Vazirmatn 和 IBM Plex Sans Arabic)、ZWNJ(U+200C)的正確使用、波斯數字與標點符號、適當的行高設定,以及避免常見錯誤(如在阿拉伯文字上使用 letter-spacing)。此技能對開發人員極具價值,因為它能確保由 AI 生成的 UI 文字語言正確,避免在複製貼上、搜尋和渲染方面出現常見缺陷。它適用於任何支援 Markdown 的 AI 代理平台,例如 Claude Code 或 Cursor,並提供從基本文件設定到自動化指令碼的逐步指南,以修正現有文字。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/mhmdsdqi87-cloud/TEKA_raast/tree/HEAD/skills/rtl-typography

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

RTL 排版:波斯語與阿拉伯語的正確做法

此技能編碼了從右至左介面的排版層級。當頁面上的文字是波斯語或阿拉伯語時,請遵循此規範。如需完整頁面建構,請參閱 rtl-landing;如需元件模式,請參閱 rtl-components。

1. 文件設定 — 始終優先

<html lang="fa" dir="rtl">
  • 同時設定 lang 和 dir。波斯語使用 lang="fa",阿拉伯語使用 lang="ar"。
  • 切勿在 LTR 文件上使用 text-align: right 來模擬 RTL。瀏覽器、螢幕閱讀器、表單控制項和捲軸均依賴 dir。
  • 所有對齊必須使用邏輯值:text-align: start,而非 left。

2. 字型

使用專為該語言設計的字型。缺乏波斯語字符的字型會顯示破損的框框或靜默替換。

可靠選擇(詳情及 CDN 片段請參閱 fonts.md):

用途波斯語阿拉伯語
正文/UI(預設)VazirmatnIBM Plex Sans Arabic
顯示/標題Lalezar, EstedadCairo, Changa
編輯/襯線感Markazi Text, ParastooNoto Naskh Arabic
熟悉/系統感Sahel, ShabnamTajawal, Almarai

堆疊模式 — 務必指定一個後備字型,並讓一個字型涵蓋拉丁字母:

font-family: 'Vazirmatn', Tahoma, sans-serif;

僅載入 woff2,使用 font-display: swap,子集化您使用的字重(400、500、700 通常足夠)。

3. 切勿在阿拉伯文字上使用 letter-spacing

這是最常見的 AI 產生的 RTL 錯誤。

阿拉伯字母是連寫且連接到一起的。letter-spacing 會在連接的字形之間插入間距,視覺上會打碎單詞:«مدیریت» 會變成 م د ی ر ی ت。

/* 錯誤 — 破壞連寫 */
.hero-title { letter-spacing: 0.05em; }

/* 正確 — 如果需要更寬的顯示文字,請改用大小/字重 */
.hero-title { font-weight: 800; font-size: 3rem; }

規則:任何阿拉伯文字都應使用 letter-spacing: 0 或取消設定。追蹤技巧(大寫、寬追蹤)也不適用 — 阿拉伯文字沒有大小寫之分。

4. 行高與節奏

阿拉伯文字的行框比拉丁字母更高(上升部/下降部 + 變音符號)。拉丁預設值會顯得擁擠。

  • 波斯正文:line-height: 1.8–2.0(1.9 是安全的預設值)
  • 阿拉伯正文:line-height: 1.6–1.8
  • 標題:1.3–1.4
  • 波斯文字約比相同內容的英文寬 10–15% — 預留更寬的按鈕、更多段落寬度,不要過度截斷。

對齊:建議使用起始對齊(參差不齊)文字。若無 kashida 支援,瀏覽器對齊會在單詞間產生難看的河流。

5. ZWNJ — 半空格(U+200C)

波斯語複合詞和詞綴在部分之間使用零寬度非連接符。缺少 ZWNJ 是生成的波斯語複製內容中最明顯的拼寫缺陷。

正確用法表格

錯誤(空格或連接)正確(使用 U+200C)
می رودمی‌رود
نمی شودنمی‌شود
می خواهممی‌خواهم
خانه هاخانه‌ها
کتاب هایکتاب‌های
بهترین هابهترین‌ها
خوب ترخوب‌تر
برنامه نویسیبرنامه‌نویسی
راه اندازیراه‌اندازی
ورود به سیستم می پردازدورود به سیستم می‌پردازد

經驗法則:

  • 前綴 می、نمی、بی、هم、نا、باز + 動詞/形容詞 → ZWNJ:می‌گوید、نمی‌دانست、بی‌نقص、هم‌گام
  • 後綴 ها、های、تر、ترین 接在詞後 → ZWNJ:پرنده‌ها、کتاب‌های、بزرگ‌تر、بزرگ‌ترین
  • 學院詞表中的複合名詞 → ZWNJ:راه‌اندازی、برنامه‌نویسی、نرم‌افزار、ذخیره‌سازی
  • 所有格後綴 ام/ات/اش 寫為連接形式:کتابم、خانه‌ات — 此處不要插入 ZWNJ。

生成波斯語複製內容時,請原生使用 ZWNJ(而非空格)。若要清理現有文字,請使用配套指令碼:

python3 scripts/fix-zwnj.py draft.md            # 乾運行差異
python3 draft-output.md > fixed.md --apply ...  # 請參閱 --help

該指令碼會合併常見的錯誤模式(می رود、خانه ها、خوب تر),將阿拉伯語 ي ك 轉換為波斯語 ی ک,且絕不觸及程式碼區塊或 URL。

6. 數字

語言數字Unicode 範圍
波斯語۰۱۲۳۴۵۶۷۸۹U+06F0–U+06F9
阿拉伯語٠١٢٣٤٥٦٧٨٩U+0660–U+0669
拉丁(內嵌上下文)0123456789U+0030–U+0039
  • 波斯語書寫的複製內容使用波斯數字:«۵ دلیل»、«۲۴ ساعت»。
  • 價格:۱۲۵٬۰۰۰ تومان — 千位分隔符為 U+066C(٬),小數點為 U+066B(٫)。
  • 百分比放在數字後,無空格:۱۲٪(阿拉伯百分號 U+066A)。
  • 切勿手動格式化這些內容:請使用 JS 區域設定 API。
(125000).toLocaleString('fa-IR')   // "۱۲۵٬۰۰۰"
(12.5).toLocaleString('fa-IR')     // "۱۲٫۵"
new Intl.NumberFormat('fa-IR', { style: 'percent' }).format(0.12)  // "۱۲٪"

僅在固有 LTR 原子(電話號碼、URL、程式碼、外幣價格)中保留西方數字。

7. 標點符號 — 波斯語文字中的波斯語標點

用途波斯語/阿拉伯語請勿使用
逗號،(U+060C),
問號؟(U+061F)?
分號؛(U+061B);
引號«متن»"متن"
小數點/千位分隔符٫ ٬. ,
百分號٪(U+066A)%

省略號為 …,非三個點。在 , ؟ ؛ 前無空格;其後有一個空格。

8. 波斯語 vs 阿拉伯語 — 先決定

它們是不同的語言,具有不同的慣例。在設定樣式前請確認使用哪一種:

  • 數字:fa → ۱۲۳(U+06F0),ar → ١٢٣(U+0660)
  • 字母:波斯語 ی/ک vs 阿拉伯語 ي/ك — 波斯字型必須包含波斯語字形
  • 標點符號有重疊,但語調/慣用語不同
  • 在阿拉伯語頁面上使用僅限波斯語的字型會顯示錯誤的 ک/ی 字形,反之亦然

機器可讀的慣例(數字範圍、分隔符、標點符號、詞綴列表)儲存在 raast/profiles/fa.json 和 raast/profiles/ar.json 中 — 這些是 raast CLI 使用的相同檔案,因此文字規則和自動檢查永遠不會分離。

9. 複製、貼上、選取與渲染

阿拉伯文字在複製/貼上和選取時比拉丁文字更常出現問題。規則:

  • 選取渲染:為 ::selection 設定足夠的對比度(阿拉伯文字字形簇延伸到線條下方;細的選取反白帶會視覺上切割它們)。對 ::selection 使用內邊距有幫助。
  • 複製/貼上完整性:切勿程式化地將 ZWNJ 插入使用者可能貼上到純文字欄位的區域;在貼上到頁面時,保持貼上的文字字節精確(不要自動「清理」U+200C、U+200E/F、U+061C 阿拉伯文字標記)。靜默移除不可見字符會破壞波斯語搜尋和拼寫。
  • 引文/引用使用 user-select: all 以保持引號相連。
  • 複製到剪貼簿元件(價格、追蹤號碼)必須複製邏輯字串,而非視覺重新排序的字串 — 使用 RTL 頁面 + LTR 剪貼簿檢視器進行測試。
  • 字型渲染標誌:建議使用 text-rendering: optimizeLegibility;請勿在阿拉伯顯示字型上使用 font-synthesis 字重(偽粗體會破壞 naskh 節奏)— 載入真實字重。
  • 關於不明確轉換的警告:將阿拉伯印度數字(٠١٢)正規化為波斯數字(۰۱۲)在 fa 內容中是安全的,但在 ar 內容中具有破壞性。任何自動轉換都必須以語言為門檻 — 請參閱 references/normalization.md 中的決策表。

10. 混合文字基礎(詳情請參閱 rtl-bidi 技能)

  • 波斯文內部的電話/電子郵件/URL/程式碼:包裹在 <bdi> 或 dir="ltr" 的 span 中。
  • 程式碼區塊:始終使用 dir="ltr" + text-align: left,即使在 RTL 頁面上也如此。
  • 使用者生成的輸入:使用 dir="auto",以便每個輸入根據其自身內容進行調整。

11. 發佈前檢查清單

  • 已設定 <html lang="fa|ar" dir="rtl">
  • 字型涵蓋該語言;已指定後備字型
  • 阿拉伯文字上未使用 letter-spacing
  • 正文行高 ≥ 1.8(波斯語)
  • 所有詞綴使用真實的 U+200C,而非空格
  • 複製內容中使用波斯數字 + ٬ ٫ ٪ ٬;拉丁數字僅用於 LTR 原子
  • 複製內容中使用波斯標點符號 ، ؟ ؛ «»
  • 對齊使用 start/end,絕不使用 left/right

Individual skills in this repo

This repo contains 3 individual skills — each has its own dedicated page.

相關技能