Communitygithub.com

rtl-typography

波斯语(法尔西语)和阿拉伯语网页界面的核心排版规则。在构建或设计包含波斯语/阿拉伯语/法尔西语文本的 UI 时使用,或当用户提到 فارسی、عربی、RTL、نیم‌فاصله、فونت فارسی 时。涵盖字体选择、零宽非连接符(نیم‌فاصله)、波斯数字、标点符号、行高以及禁止模式(如阿拉伯文使用字母间距)。

rtl-typography 是什么?

该技能为右至左(RTL)界面提供了全面的排版指南,专为波斯语和阿拉伯语内容定制,解决了 AI 生成代码中常见的 RTL 排版错误。它涵盖了从文档设置、字体选择到标点符号和数字格式化的所有方面,特别强调了关键细节如零宽非连接符(ZWNJ)的正确使用、避免在阿拉伯文上使用字母间距,以及根据语言使用不同的数字系统。该技能还提供了实用的代码示例、对比表格和预部署检查清单,确保生成的 UI 在视觉上正确且符合本地化标准。它支持多种平台(如 Claude Code、Cursor、Codex),并通过详细的 MD 文件指导开发者避免破坏文本连接或显示乱码等常见陷阱。

兼容平台~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)。缺少 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. 波斯语与阿拉伯语 — 先确定语言

它们是两种不同的语言,具有不同的惯例。在设定样式之前,请先确认使用哪种语言:

  • 数字:fa → ۱۲۳ (U+06F0),ar → ١٢٣ (U+0660)
  • 字母:波斯语 ی/ک 对应阿拉伯语 ي/ك —— 波斯语字体必须包含波斯语字形
  • 标点符号重叠,但语气和习语不同
  • 在阿拉伯语页面上使用仅限波斯语的字体,会显示错误的 ک/ی 字形,反之亦然

机器可读的惯例(数字范围、分隔符、标点符号、词缀列表)位于 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 字重(虚假的粗体会破坏纳斯赫体节奏)—— 加载真实字重。
  • 关于歧义转换的警告:在 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.

相关技能