Communitygithub.com

rtl-bidi

处理波斯语/阿拉伯语与英语文本、数字、电话号码、电子邮件、URL、代码和货币在RTL界面中的混合显示。当文本同时包含两种脚本、输出顺序错乱或数字位置错误时,或用于RTL页面上的输入框、价格和代码块时使用。涵盖双向算法、bdi元素、unicode-bidi CSS以及常见的乱序错误。

rtl-bidi 是什么?

该技能旨在解决在从右到左(RTL)界面中混合波斯语/阿拉伯语和英语文本时常见的双向文本(BiDi)问题。它为开发者提供了一套清晰、系统的方法,用于诊断和修复由于Unicode双向算法自动重排导致的文本混乱、数字顺序错误、符号错位等现象。技能详细介绍了关键的HTML/CSS工具,如`<bdi>`元素、`dir`属性和`unicode-bidi` CSS属性,并针对电话号码、URL、电子邮件、产品序列号、价格、代码段以及用户生成内容等典型场景给出了具体的代码示例和最佳实践。同时,概念被呈现为易于遵循的决策规则和调试清单,帮助开发者在不改变底层数据逻辑的前提下,仅通过前端标记和样式来确保跨脚本文本在任何浏览器或平台上都能正确、一致地显示。

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

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

双向文本:混合波斯语/英语内容

Unicode 双向算法会自动重新排序混合方向的文本——有时是错误的。本技能教你何时干预以及如何精确操作。

1. 思维模型

  • 基础方向来自最近祖先元素上的 dir 属性(页面:RTL)。
  • 强 LTR 内容(拉丁字母)的片段嵌入并内部按 LTR 流动。
  • 中性字符(标点符号、与数字相邻的符号如 + - / $ %)会根据其周围环境获得方向——这是混乱发生的地方。

2. 干预工具箱

工具适用场景示例
<bdi> 元素波斯语文本中的内联外语原子,方向未知«فایل report_final.pdf را ببینید»
<span dir="ltr">已知为 LTR 的原子,同时希望其内部左对齐<span dir="ltr">+98 912 345 6789</span>
dir="auto"用户生成或不可预测的内容聊天气泡、评论、文件名
CSS unicode-bidi: plaintext与 dir="auto" 相同,但用于带样式的 span.user-content { unicode-bidi: plaintext; }
isolate(bdi 的默认值)防止该原子重新排列其邻居<bdi> 的默认行为

3. 典型场景

电话号码

+98 912 在波斯语文本中通常会将 + 渲染在错误的一侧。

تلفن پشتیبانی: <span dir="ltr">+98 21 9100 2000</span>

外币价格

$99 浮动在 RTL 文本中会变成 99$:

اشتراک جهانی: <span dir="ltr">$99/mo</span> — اشتراک داخلی: ۹۹٬۰۰۰ تومان

电子邮件、URL、用户名

به <bdi>[email protected]</bdi> ایمیل بزنید.
مستندات: <bdi>https://docs.example.co/fa</bdi>

句子中间的拉丁品牌名称

通常作为纯文本是安全的,但后面跟波斯语后缀时会出问题: «نسخه‌ی جدید Node.js» — «Node.js» 是安全的;但如果后缀附加,«های Node.js» 需要用 <bdi> 包裹拉丁语段:<bdi>Node.js</bdi>های 是错误的——应改写为 «افزونه‌های Node.js»。

代码和命令——始终为 LTR 块

<pre dir="ltr" style="text-align: left;">npm install raast</pre>

波斯语散文中的内联命令:<code dir="ltr">npx create-next-app</code>。

混合项目列表

项目标记(۱ ۲ ۳)位于 RTL 流中;长 LTR 项目内部保持各自隔离——对任何以拉丁字母/数字开头的项目使用 <bdi>。

产品标识符、序列号和技术 ID

最高混乱类别——混合字母、数字和破折号:

شماره سریال: <bdi dir="ltr">SN-9F42-KM18</bdi>
کد پیگیری: <bdi dir="ltr">TRK-IR-14050823-0042</bdi>
شناسه محصول: <bdi dir="ltr">SKU 88451-B</bdi>

规则:

  • 标识符在复制时必须保持字节精确——隔离只改变渲染,从不改变字符串。
  • RTL 句子末尾的尾随破折号/数字段如果不加 <bdi> 会重新排序(例如 88451-B → B-88451)。
  • 在 JS 中进行数据库查询:保留逻辑字符串;不要为了显示“预翻转”。
  • 表格中的 ID 列:使用等宽字体 + dir="ltr" + text-align: start。

用户生成的内容(聊天、评论、文件名)

  • 容器:dir="auto" + CSS unicode-bidi: plaintext——每条消息根据其第一个强字符确定方向。
  • 一个粘贴英文文本的波斯语用户(或反之),必须无需手动切换 dir 就能正确阅读。
  • 切勿仅通过 dir="rtl" + text-align: start 将页面方向强加到用户生成内容上;第一个强字符规则是 plaintext 的要点。
  • 文件名/下载:在 <bdi> 中渲染,这样扩展名(.pdf、.zip)不会分离。

4. 表单输入

  • dir="auto":输入框采用第一个强字符的方向——适用于姓名/消息字段。
  • 显式 dir="ltr":电子邮件、电话、用户名、卡号、URL、价格(对于 RTL 用户,配合 text-align: end 使光标从右侧开始……实际上,对 LTR 输入框保持 text-align: start 以保持光标正常;请测试)。

5. 调试混乱输出——检查清单

  1. 原子是否被包裹/隔离?(bdi / span dir=ltr)
  2. 中性字符(+ - / . , ( ))是否位于方向边界附近?添加隔离或 RLM(\u200F)/LRM(\u200E)标记。
  3. LTR 原子的尾部标点符号跳转到错误的一端?将尾随空格也包含在隔离内。
  4. 字符串是在 JS 中构建的吗?双向文本是渲染问题——不要在代码中重新排序,修复 DOM/CSS。
  5. 不可见字符转储:将文本粘贴到双向检查器或使用 JSON.stringify() 查看 U+200E/F 的位置。

6. RLM/LRM——手术刀

&rlm;(U+200F)/ &lrm;(U+200E)在无法隔离时(例如纯文本电子邮件、CSV 单元格)强制中性字符位于一侧:

متن فارسی‎ +98‎  -> 将 + 附加到数字

谨慎使用——在某些字体中会出现可见的乱码;在网页上优先使用结构隔离。

7. 标题、元描述和单行上下文

  • 包含混合脚本的 <title>:浏览器在标签页中能较好地处理双向文本,但应以页面语言开头:«raast — مهارت‌های RTL» vs «مهارت‌های RTL — raast»:将页面语言的强脚本放在首位。
  • aria-label 字符串遵循相同规则;屏幕阅读器处理 Unicode 双向标记,因此保留它们。
  • JSON/API 负载:始终存储逻辑顺序;永远不要为显示预反转任何内容。

Individual skills in this repo

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

相关技能