阿拉伯语双向排版 SMSMy/dsh-arabic

dsh-arabic

العربية · English

阿拉伯语支持，面向 DeepSeek Harness —— 技术上可靠的 RTL 显示、完整界面本地化包，以及八体界面字体。

DSH 不支持 RTL，也不提供阿拉伯语。界面里阿拉伯文和变量名、路径、代码混在一起，读起来支离破碎，所有菜单都是英文。这个插件解决这两个问题，不用改动应用本身。

它做什么

١) 安全的双向 RTL 显示（任何界面语言下都能用）

方向按每个块的词数占比判定，不看第一个强字符。切分只按空格，所以 @deepseek-ai/dsh 算一个词，不是三个：

| 内容 | 方向 | 原因 |
| كيف حالك Hello | RTL | 阿拉伯语词占多数 |
| Hello كيف حالك | RTL | 仍是阿拉伯语句子 —— 而 dir="auto" 在这里会判错 |
| Error: فشل الاتصال بالخادم | RTL | 句子是阿拉伯语，前缀不是 |
| npm install ثم أعد التشغيل | RTL | 阿拉伯语 ٣ 词对拉丁语 ٢ 词 |
| شغّل npx @deepseek-ai/dsh web | RTL | 技术符号把 npx … web 粘成一个单元：阿拉伯语 ١ 对拉丁语 ١ |
| راجع commit a4c1025b قبل النشر | RTL | 裸哈希不参与投票 |
| نسبة النجاح 15/15 | RTL | 比例是中性的 |
| افتح src/index.ts ثم عدّل الدالة | RTL | 路径不参与投票 |
| "C:\Users\…\الخطوط\thmanyahseriftext" | 不变 | Windows 路径是技术符号，哪怕其中某个文件夹名是阿拉伯语 |
| @deepseek-ai/dsh مهم جدًا | RTL | 单个标识符 = 一个单元 |
| Hello نص | RTL | 平局判给 RTL |
| The build failed while parsing سلام in the file | 不变 | 英文文本里引用一个词，仍是 LTR |
| شغّل "git status" | RTL | 引号是一个单元：只计一次，不计两次 |
| pre、code 和内联代码 | 始终 LTR | 代码不参与判定，也不翻转 |
| 输入框和搜索框 | 跟随你输入的内容 | 阿拉伯语占多数时 RTL，否则用原来的 auto |

表格背后的四条规则：

١. 类代码符号不参与投票 —— 链接、路径（包括 Windows 反斜杠）、@scope/name、哈希、15/15、带点的文件名；一个链接或一个哈希就可能压过整句阿拉伯语，而技术符号会把周围的拉丁词粘成一个技术单元。带阿拉伯语文件夹名的路径仍是路径：把它当阿拉伯语文本计票，正是过去把路径块翻成 RTL 的原因，结果它周围的拉丁片段被重新排序。
٢. 词是单位，不是字母 —— 拉丁术语字母更多、词数更少。平局判给阿拉伯语，不含任何阿拉伯语词的块保持原样。
٣. 流式输出期间锁定（hysteresis） —— 已经变成 RTL 的块会一直保持，直到文本明显变成拉丁语（阿拉伯语词数的两倍），这样逐段生成的回复不会来回抖动。
٤. 把引号内的内容当作一个整体 — "git status" 是引号括起来的文本（命令、标题、句子），只计一次，不计两次；所以 شغّل "git status" 按阿拉伯语句子原样读，而同样两个词不加引号时仍保持 LTR（见下面的边界）。未闭合的引号——回复还在流式输出、引号尚未闭合——会一直延伸到文本末尾，它和闭合引号产生的是同一个整体，所以闭合那一刻不会跳动。

只有文本块才翻转——结构永远不翻转。 flex 或 grid 容器在翻转时会重排子元素，而带按钮的行是工具栏：两者都排除在外，所以发送按钮留在原位，尽管同一行里还有阿拉伯语的权限标签。那一行里的阿拉伯语文本位于自己的文本块中，按常规处理。

有两种形态需要的不只是普通块级判断，每一种都由测试和 data/card-pins.json 固定：

- 被 CSS 变成块的文本单元格。 助手提问的问题卡片用 flex 绘制每个选项 button，标签和描述是其中的 span。内联 span 本来就是周围流的一部分，而 flex 元素是独立的文本块：每个单元格都取 RTL，所以 ادفع fix/rust-flake كما هو 按原顺序读，不会倒过来，选项编号也留在原位；
- 内容卡片的 /。 DSH 把问题文本放进 （header 和 footer 是结构标记，保持 LTR）。卡片外框带 data-question-key——这是本插件从应用读取的唯一标识符——所以卡片内的标记属于卡片，其中的问题就是内容，和任何段落一样。
scripts/check-card-pins.mjs <app.asar> 会指出差异并失败，如果这个标识符变了，或者选项行不再是 flex 行；
- 不动的部分： 选项编号和控件本身。带按钮的行不翻转，控件不单独赋予方向——flex 按钮会反转图标和标签的顺序，居中的标签在超出对齐时会跳到边缘。所以编号留在设计放的位置，卡片按钮保持原布局，阿拉伯语文本从旁边开始——卡片不翻转，翻转的是它的文本。

前后对比：带图层和不带图层的问题卡片

用 Chromium 和真实 bidi 引擎渲染：两块面板中的标记和文本相同，右面板带有插件写入的 dir 属性。选项编号在两种情况下都留在左侧。源码：docs/question-card.html。

如果某个块的方向由应用或你设定（标记中的 dir="ltr"），我们绝不改动——这是估计器判断出错的任何块的兜底出口。

已知边界（固定在测试中，不隐藏）

- 孤立的拉丁词会投票。 شغّل git status 保持 LTR：两个普通拉丁词压过一个阿拉伯词，没有技术分隔符把它们粘在一起。曾尝试把每个拉丁序列当作一个整体，但被否决——因为它会翻转引用阿拉伯词的英语段落。引号是读者手中的解法：شغّل "git status" 会翻转。
- 阿拉伯语句子中的混合路径遵循 bidi 算法。 块是阿拉伯语，保持 RTL，所以路径的拉丁片段围绕其阿拉伯片段排列。把路径写在反引号内是可靠写法：样式表把 code 从左侧隔离
- 在右侧，路径按顺序读取（已在 Chromium 中验证）。
- 侧边栏终端无法连接字母。 DSH 终端基于 xterm.js，无法连接阿拉伯字母（ا ل ع ر ب ي ة）。这是源码中的限制，我们如实记录，不假装修复。
- 复数形式。 DSH 字典是扁平字符串，因此阿拉伯语句子计数时无法为 1、2、3–10 和 11+ 选择正确形式；在重要之处，我们措辞句子使其不受数量影响。
- 结构保持 LTR。 列表和侧边栏遵循结构方向而非所选语言；通过注入翻转它们会破坏用物理 CSS 属性编写的布局。出于同样原因，flex/grid 容器和拥有按钮的行被排除在方向决策之外——因此编辑器栏中的阿拉伯有效性标签从右向左读取，而发送按钮不会移动。已批准的计划优先考虑源码——见 docs/roadmap.md。

词主导方法、「单一标识符即单一词」规则，以及计数前删除类代码符号的想法——都遵循社区共识，由 haythamat/dsh-client-ui-rtl 和 kfirsch/dsh-hebrew-rtl 发起（两者均为 MIT 许可证）；此实现独立，并添加了输入框、按键和流式传输期间固定层，且有其测试覆盖。

之前和之后：强首字符规则对比词主导

由 Chromium 浏览器以真实 bidi 引擎渲染：两列包含相同的五行，每行以拉丁标识符开头。来源：docs/direction.html。

不会将整个界面翻转为 RTL。 开发者界面本质上是双语的，逐块方向才是保持两种语言可读的关键。

2) 界面本地化包

通过官方翻译服务注册（ctx.locale.addLanguage + ctx.locale.register）——即应用本身使用的同一机制，不替换 DOM 中的文本，不修改现有函数：

- 60 个域 · 3,307 条文本，取自 DSH 官方源码
- 任何未翻译的键自动回退到英语（fallback: 'en'）
- 从 设置 ← 通用 ← Language 选择 العربية

覆盖范围和每个非显而易见的翻译决策均可在 data/en-catalog.json（官方英语键集）、 locales/ar.json（阿拉伯语包）和 data/overrides.json（批次间形式统一）中审查。

3) 选择权在你，不在我们

阿拉伯语作为选项添加，绝不强制：

- 设置 ← 通用 ← Language 在内置语言旁列出 العربية，应用通过官方语言服务保存你的选择——偏好英语界面的人可以保留它。
- 设置 ← 通用 ← 从右到左文本方向 开启方向层并立即停止它，并记住你的选择（localStorage）。关闭时，不标记任何块，不设置任何输入框方向——界面表现完全如同插件不存在。

4) 界面排版

八个中的三个部分，每个都在其绘制的角色中：

| 角色 | 部分 | 出现位置 |
| 界面 | 八度无衬线 | 默认：标签、按钮、结构和短文本 |
| 阅读 | ثمانية سيريف تيكست | Markdown 段落、列表项和引用块 |
| 标题 | ثمانية سيريف ديسپلاي | h1–h6 |

一行承载界面角色 —— 插件重定义 --dsw-font-family，应用主题里所有排版符号都经由这个变量传递 —— 另有两条元素规则承载另外两个角色。应用字体包仍留在定义中每个字族之后，代码字体不动，任何角色在缺少文件时都保持沉默。

从 DSH 0.2.1 起，这个变量在应用内部变成了中间层：它在 body 上取 --dsh-font-family-text 的值 —— 你在 设置 ← 通用 里选的字体 —— 优先于其内置字体包。于是插件把自己的字体片段称作该变量的兜底，而非它的值：你在应用字段里选的字体，会优先于我们的片段，作用于界面、段落和标题；字段留空 —— 此时应用不写入任何内容 —— 则让ثمانية留在原位。变量只被读取，从不被定义，这正是保住该顺序的原因。

字重在 fonts/ —— 子目录，不是仓库根目录 —— 连同两份许可证文本（以阿拉伯语为准），插件从应用自身的服务器经 /dsh-arabic/fonts/ 提供它们：桌面版从 http://127.0.0.1:<port> 加载页面，所以同一链接在两端都可用，页面携带九条简短的 @font-face 规则，而不是约一兆字节的 base64。把 DSH_ARABIC_FONTS 指向结构相同的目录，即可供给另一份副本；或指向空目录，以保留应用原字体 —— 该层保持沉默，不会失效。

在你选择之前，界面不会有任何变化。

安装

从 npm
dsh plugin --profile desktop add dsh-arabic

或从本地副本（用于开发）
dsh plugin --profile desktop add link:/完整/路径/dsh-arabic

或在应用内：设置 ← Plugins ← Plugin Manager。

安装后重启 DSH。 插件本身的加载在宿主启动时决定（对等网关）；注入表则在每次页面渲染时收集，所以刷新页面会在启动后重新收集它。

兼容性：没有上限。 插件在 0.2.0 或更新的任何 DSH 版本上都被接受；更新的版本不会阻止它运行，因为其中大多数不触及这些集成点。只有早于 0.2.0 的版本会被拒绝。若版本比最后测试过的版本更新（data/tested-runtimes.json），检查网关会提示 —— 但不阻止。

然后启用阿拉伯语界面：设置 ← 通用 ← Language ← العربية。
RTL 层在插件加载后即可配合任何语言工作。

工作原理

index.js 宿主侧 └── webserver/index-inject 行
├── { kind: 'style', text: <方向 CSS> }
└── { kind: 'script', placement: 'body', text: <标记脚本> }

lib/client.js 浏览器中的程序侧（生成） └── window.__ModuleLoader__.load({ id, factory }) ├── ctx.locale.addLanguage({ id: 'ar', label: 'العربية', fallback: 'en' }) │ ctx.locale.register(namespace, 'ar', dictionary) × 59 └── ctx.slots.inject('settings.general.item', …)
└── 单个 Switch 行 → window.__dshArabic.setEnabled()

加载层面没有外部依赖：react 和官方组件只在设置席位存在时才请求，且该注册受到保护，未来对站点的改动不会连带丢掉语言包。

仓库结构

| 路径 | 用途 |
| index.js | 宿主侧：方向注入行 |
| lib/client.js | 生成的代码侧：阿拉伯语语言包 |
| locales/ar.json | 翻译词典 |
| data/en-catalog.json | 从 DSH 源码提取的官方英文键集合 |
| data/en-catalog.meta.json | 集合所依据的 upstream 基准/指纹 |
| data/glossary.yml | 自动术语表（术语、阿拉伯语、应避免的译法、不翻译的内容） |
| data/overrides.json | 并行批次出现分歧时统一写法 |
| data/term-map.json | 对流水线中每个值应用的术语规范化 |
| data/bidi-decisions.json | 状态行家族中的每一处隔离——以及每个混合值——及其原因 |
| data/shimmer-pins.json | 闪光镜像所依据的类名与拆分后的 keyframes |
| scripts/extract-catalog.mjs | 从官方源码重新生成 data/en-catalog.json（npm run extract） |
| scripts/status.mjs | 相对已记录的 upstream 基准的覆盖率（npm run status） |
| scripts/build-client.mjs | 校验语言包并重新生成 lib/client.js（CI 用 --check） |
| scripts/assemble-translations.mjs | 把翻译批次合并进 locales/ar.json |
| scripts/lint-consistency.mjs | 检出同一段英文被译成两种写法 |
| scripts/check-bidi-family.mjs | 状态行家族中出现未记录的隔离时失败——并标出键名 |
| scripts/check-shimmer-pins.mjs | 对照已安装的 app.asar 复核闪光镜像的类名（发布步骤） |
| tests/golden-direction.mjs | 45 条黄金文本，各带应有方向 |
| fonts/ | 三套八件字体（无衬线 · 文本衬线 · 展示衬线），字重 400/500/700 + 两份许可证文本（阿拉伯语为准），该目录是仓库子目录而非根目录 |
| docs/roadmap.md | 三个层次、源码请求，以及我们不打算做的事 |
| AUDIT.md | 项目如何建成：每一步、每条命令、每道门禁的结果 |
| CONTRIBUTING.md | 如何新增或修正翻译，以及 CI 跑哪些检查 |
| tests/verify-rtl.mjs | 67 项行为测试，在 DOM 模拟器上验证方向层 |
| tests/verify-locales.mjs | 目录完整性、文件契约与语言注册 |
| data/card-pins.json | 问题卡片的结构（标识符、标记、flex 行），从已安装的 app.asar 复核（发布步骤） |

开发

npm test # الاتجاه (67) + الترجمة (32) + المصفوفة الذهبية (45) + الخطوط (28)
npm run check # الاكتمال + تدقيق الاتساق + المصفوفة الذهبية
npm run build # إعادة توليد lib/client.js
npm run status # التغطية مقابل مرجع upstream المسجَّل

跟进官方更新

每周工作流（.github/workflows/upstream-sync.yml）会重新提取官方键集合，并只带新键开 PR，让偏差以可评审的 diff 形式出现，而不是突然冒出来：

GITHUB_TOKEN=$(gh auth token) npm run extract # تحديث data/en-catalog.json
node scripts/build-client.mjs --check # سرد كل مفتاح غير مترجم
npm run status # التغطية + مرجع upstream
运行时缺失的键回退为英文——所以部分更新永远不会弄坏界面。
参见 CONTRIBUTING.md 和路线图。

兼容性

已在 DSH 0.2.0-rc.2（桌面应用）和 0.2.1-alpha.2（由 dsh web 提供的 Web 版）上测试。两端使用同样两个有文档的内部接入点——事件 webserver/index-inject 和客户端的 locale 服务——任一端变化时插件会安全降级：方向层做了包装，永远不会弄坏索引渲染；语言包则只是停止注册。桌面版里注入表在宿主启动时只收集一次，所以需要重启，而不是刷新页面。

从 0.2.1 起，应用有了用户自选的字体角色（界面文本、代码、侧边栏终端）：应用把你选的字体写进 body 上的 --dsh-font-family-text，我们的字体切片就作为回退挂在这个变量后面——你选的字体优先，我们的切片只画它画不出的部分（通常是阿拉伯文），字段留空则八个字体留在最前面。这个变量只读不定义，这个顺序固定在 tests/verify-fonts.mjs 里。

与其他阿拉伯语/RTL 插件的交互。 我们的插件和 dsh-client-ui-rtl 或 dsh-rtl-fix 都会在内容块上设置 dir；两个一起装意味着它们轮流生效，最后写入的赢。「通用」里的设置开关会停掉我们的层，这是两者共存最干净的路子。同样，用 ar 这个标识注册两种语言（@mimateinn/dsh-i18n 就这么做，覆盖范围不同）会争抢同一个标识——选一个。

术语。「بلاقن」是有意的选择：阿拉伯开发者口语里就用这个说法，而 plugin 留在技术语境里（包名、路径、终端输出）。如果你更喜欢界面上用拉丁词，改一处词典就行——参见 CONTRIBUTING.md。

致谢与文档

- 界面文本和键名来自 deepseek-ai/deepseek-harness（MIT 许可证）。
- 词主导方案和「一个标识一个词」规则遵循 haythamat/dsh-client-ui-rtl（MIT 许可证）发起的社区共识，本实现是独立的。
- 本仓库的阿拉伯语翻译是原创作品，以 MIT 许可证发布。

许可证

MIT——参见 LICENSE。