Communitygithub.com

rtl-bidi

處理波斯語/阿拉伯語與英語混合內容、數字、電話號碼、電子郵件、網址、代碼和貨幣在 RTL 介面中的顯示。當文字同時包含兩種文字、輸出順序錯亂、或在 RTL 頁面上處理輸入、價格、程式碼區塊時使用。涵蓋 Bidi 演算法、bdi 元素、unicode-bidi CSS 和常見的亂碼錯誤。

rtl-bidi 是什麼?

這項技能專門解決在從右到左(RTL)語言(如波斯語和阿拉伯語)的介面中,混合使用拉丁字母文字(如英語)時常見的文字排序錯亂問題。Unicode 雙向演算法(BiDi)會自動重新排列混合方向的文字,但在遇到中立字元(如標點符號、數字旁的 +/- 符號)或特定結構(如電話號碼、電子郵件、網址、產品序號)時,容易產生錯誤的視覺順序。此技能提供了一套完整的干預工具箱,包括使用 `<bdi>` 元素處理未知方向的內嵌文字、使用 `<span dir="ltr">` 強制已知 LTR 片段的內部左對齊、以及使用 `dir="auto"` 和 CSS `unicode-bidi: plaintext` 處理使用者產生的動態內容。它也深入探討了偵錯亂碼的技巧、在無法使用 HTML 結構(如純文字電子郵件)時使用 RLM/LRM 不可見字元,以及處理表單輸入、程式碼區塊、混合清單和資料表的最佳實務。支援的平台包括任何需要處理 RTL 內容的網頁開發環境,特別是針對 Claude Code、Cursor 等 AI 編碼代理工具的使用者。

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

在你喜歡的 AI 中提問

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

說明文件

Bidi:混合波斯語/英語內容

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>

外幣價格

在 RTL 文字中浮動的 $99 會變成 99$:

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

電子郵件、網址、帳號

به <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":電子郵件、電話、使用者名稱、信用卡號、網址、價格(搭配 text-align: end 以便 RTL 使用者的游標從右側開始……但實際上,為了游標位置正常,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. 標題、Meta 與單行上下文

  • 混合語言的 <title>:瀏覽器在分頁標籤中能合理處理雙向性,但應以頁面語言開頭:«raast — مهارت‌های RTL» 相較於 «مهارت‌های RTL — raast»:請將頁面語言的強勢文字放在前面。
  • aria-label 字串遵循相同規則;螢幕閱讀器能處理 Unicode 雙向標記,請保留它們。
  • JSON/API 酬載:務必儲存邏輯順序;切勿為了顯示而預先反轉任何內容。

Individual skills in this repo

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

相關技能