让 AI Agent 说维吾尔语：河蟹 AI v0.4.0 的本土化实践

起因是前几天跟一个维吾尔族朋友聊起来——他说他也想用 AI 助手，但找了一圈，没找到一个能让他自然用维语用起来的本地 Agent 桌面端。

聊完我起了点好奇——本地 AI Agent 桌面端这条赛道，对维语支持到底做到了哪一层？

我自己也顺手试了几款常见的本地 Agent 桌面端，跟朋友说的差不多——要么没维语选项，要么切到一半就回退到中英文，要么界面歪七扭八（emoji 跑行末、版本号倒序、按钮镜像错位这种细节问题）。

放在 2026 年的开源生态里，这件事本来不该是个工程问题。

i18n 早就被研究透了，Vue / React / Next 都有成熟方案；CSS 层面 [dir] 属性用了快二十年；Unicode UAX #9 是长期稳定的双向文本算法规范；logical properties 也已经被主流浏览器广泛支持。技术上没有任何卡脖子的环节。

问题不在技术，而在优先级。海外项目默认英语优先，国产项目默认普通话优先，少数民族语言用户常常排不到产品迭代前列。

"国际化"是把产品翻给海外用户，"本土化"是贴着本土用户的语言、习惯和文化做深。国内 AI Agent 桌面端不缺英文版，缺的是把普通话之外的本土语言当作第一等体验。

河蟹 AI 的 v0.4.0 这个版本，把这件事往前挪了一档。

这篇只讲三件事：UI 上的字、CSS 上的方向、模型最终说出来的话——三层各管一段，缺一不可。

本文核心判断
i18n 不等于支持
本地 AI Agent 桌面端要做到"开箱说维语"，必须做完三层：前端 i18n（字翻齐）+ 前端 RTL CSS（方向对了）+ 后端语言指令（模型用维语回话）。少一层，体验都会断。
v0.4.0 把这三层都做完了。

30 秒版
这版不是只加一个语言下拉，而是把三件事接起来：1400+ 文案键切到维语，RTL 布局不再把混排文本弄乱，后端 system prompt跟随语言偏好让模型尽量用维语回复。

先把维语放到工程视角里

v0.4.0 先做维吾尔语，核心是一个工程取舍：它能一次暴露 RTL 本地化里最容易欠下的工程债。

• 阿拉伯字符体系——和中英文完全不同的字形，需要专门字体支持（系统 fallback 链得调）
• RTL 文字方向——从右往左书写，整个布局要镜像
• bidi 双向算法——维语句子里夹中文、英文、数字、emoji 时，浏览器要按 Unicode UAX #9 重排，控制不好就乱
• 数字与方向不一致——维语里的"2026 年"，数字本身仍是 LTR，要在 RTL 流里强制嵌入
• 标点反向——句号、逗号、引号在维语里位置和形态都和中英文不同

藏文通常按 LTR 排版，传统蒙古文还涉及竖排文字系统；哈萨克语在新疆使用阿拉伯字母时也会遇到 RTL 问题。本文不做语言难度排名，只说一个工程取舍：维语在国内终端用户里覆盖面足够大，也足够暴露 RTL 改造里的核心问题。把维语 RTL 做透，后续阿拉伯语、波斯语、希伯来语、乌尔都语等 RTL 语言可以复用同一套 CSS 底座。

第一层：先把 1400+ 个文案键翻齐

先讲数字。截稿日（2026-05-01）src/i18n/locales/ 下两份文件的实际行数：

两个数字一起看更准——1457 是按对象属性粗略统计的 locale key 数；1568 是 ug-CN.ts 文件总行数（含嵌套结构、注释、空行）。公众号标题里写 1400+ 文案键、1500+ 行 ug-CN locale 文件，工程口径上都站得住。

这里要先讲清楚：v0.4.0 的维语翻译是 auto-translated 基础可用版，不是母语者全量校审过的最终版。ug-CN.ts 文件头也写得明白：等社区维语母语者通过 issue / PR 持续校审。这件事不能含糊——把"工程支持完成"夸大成"翻译质量完成"，是发版稿最常见的失信。

为什么强求 1:1 对齐

这件事值得花一段单写。

i18n 工程里最常见的偷懒做法是：缺 key 时静默 fallback 到默认语言。Vue I18n、i18next 都是这个默认行为，看起来很合理。

但放进一个 RTL 界面里，这个 fallback 会立刻变成用户体感最强的 bug——维语界面里突然冒出一句中文，文字方向从 RTL 切回 LTR，整行布局抖一下，按钮跟着错位。

维语母语用户报回来的高频反馈，不是"翻译不准"，是"看着乱"。

所以 v0.4.0 的硬规则是：CI 跑 i18n 完整性测试，缺一个 key 整个 build 失败。这条规则贯穿整个开发周期，强制每个新 PR 同步两份 locale。

翻译流水线（auto-translated 起步）

1400+ 个文案键，一个人对着字典抠不现实。v0.4.0 的做法分几步：

1. 多模型交叉翻译——zh-CN.ts 切片，让 Claude / DeepSeek / Qwen 各翻一份维语，三份输出交叉对比，分歧位置打标记。这一步生成的就是"auto-translated 基础版"。
2. CI 完整性校验——对齐 zh-CN 缺 key 失败；阿拉伯字符比例校验防止漏翻成中文 fallback。
3. 桌面端实测——主路径页面手动切到维语过一遍，截图存档。

母语者校审是开放给社区的——v0.4.0 没卡在"等全量校审完才发版"，而是先把 auto-translated 版本上线让用户能用，然后通过 GitHub issue / PR 让维语母语者持续打磨。一个人维护 6 个仓库，等不到完美翻译；先让维语用户能用，再让翻译质量随反馈往上走，比压在抽屉里更对。

术语表的取舍

不是所有词都该翻。技术词译过去会丢失语义、丢失搜索性，反而是减分项。v0.4.0 的处理：

原则一句话：让母语用户能用，让技术词保持搜索性。

第二层：光翻完字还远远不够，bidi 才是真正的硬骨头

如果你以前没做过 RTL 改造，这一节会改变你对"加个 dir=rtl"的理解。

先纠正一个常见误解："做 RTL 不就是给 HTML 加个 dir=rtl 吗？"

不是。dir="rtl" 只解决文字基本方向。

当一段文本里同时存在维文（强 RTL）+ 中文（强 LTR）+ 数字（弱 LTR）+ emoji（中性）时，浏览器会用 Unicode Bidi Algorithm（UAX #9）动态决定每个字符段的视觉方向。

这个算法的默认行为，在很多场景下会把语义重排到错乱的位置。

最经典的反例

河蟹 AI 启动横幅原文：

扔进维语容器里，浏览器把 🦀 和版本号判定为弱方向、整段重排，渲染出来大概是这样：

emoji 跑到了行末，版本号也跟着跑了。

CSS 给的解法是 unicode-bidi 属性，最关键的值是 plaintext：让浏览器按内容首字符自动判断方向，而不是强制反转。等价于 HTML 的 dir="auto"，但粒度可以放在 CSS 选择器层。

从逐 class 修补到全局兜底——CSS 改造的演化

这一段是这次改造里最值得分享的工程经验。

阶段一（错误路径）：逐 class 修补。每个组件一发现 bidi 问题就单独写一条 CSS：

这条路走到一半就走不下去了。

问题是：每发现一个新页面、一个新组件，就得加一条规则。日志页有日志页的 class、设置页有设置页的 class、IM 通道有 IM 通道的 class——一旦漏覆盖，就有一处错乱，得等用户报上来才发现。

阶段二（正确路径）：全局兜底。一条规则覆盖所有内容容器：

从 50+ 条单独 CSS 规则，缩到 1 条全局兜底 + 5-6 条特殊场景覆盖。新页面、新组件不用再单独适配 RTL，CSS 框架级解决。

成熟产品和站点的 RTL 体验，背后也离不开这套思路。
成熟标准和浏览器实现的价值，就在于把这种"少写 CSS 多覆盖"的工程原则沉淀下来。

logical properties——CSS 的现代写法

第二个改造是用 logical properties 替代物理属性。

核心原则很简单：不要再写 padding-left / margin-right / border-left，统一换成 inline-start / inline-end。

浏览器会按当前文字方向自动决定 start/end 是左还是右，避免给 RTL 单独再写一份 CSS。

不该镜像的元素——这件事曾被维语用户反弹过

RTL 改造里有一类常见误判：认为所有视觉元素都要跟着语言方向镜像。这是错的。

• 布局间距、边框、阅读进度：跟随语言方向镜像。
• 语义图标、代码块、URL、版本号、时间戳：保持原方向或强制 LTR。
• 回退 / 前进这类导航箭头看场景，不能机械镜像。

早期我把语义图标也加了 transform: scaleX(-1)，被维语用户反弹后全部回滚——他们告诉我这些图标在 RTL 文化里本来就保持原向，反过来反而陌生。

这是单纯靠工程师视角判断不出来的细节。必须有母语用户的反馈环。

"不该镜像"那一档，CSS 上怎么落实？以代码块 / 命令行 / URL 这一档为例，强制保持 LTR：

否则维语界面里读到一段代码——变量名和注释都被 bidi 算法重排，看到的不是本地化，是灾难。

第三层：UI 翻完了，模型还在说中文

这一节是这次改造里最容易被忽略，但工程含金量最高的一块。

前端把 UI 翻译完、RTL 改造做完，只解决了一半问题。

底层 LLM 不会因为你 UI 是维语就用维语回复你。Qwen / DeepSeek / GLM 这些模型默认按训练分布的概率最大语言回复——通常是中文或英文。

用户切到维语 UI、用维语问"今天天气怎么样"，模型回中文——这种体验断裂比 UI 翻译漏一半还糟。

解法：在 system prompt 末尾追加语言指令

河蟹 AI 的解法很直接：前端读取 localStorage 里的 hc-locale（用户当前语言偏好），写到 chat metadata 的 user_locale 字段发给后端：

后端服务层构造 system prompt 时，在末尾追加一段语言指令。实现位置：hexclaw/engine/react.go，函数 localeOutputDirective(locale string) string。核心代码（删除注释）：

细节一：维语指令为什么是双语

注意维语 case 的写法——维吾尔文 + 中文双份，不是单纯的维文。

这是有原因的：不同模型对维语的理解和指令跟随能力参差不齐。有的模型能读懂维文指令，有的模型更依赖中文提示兜底。

如果 system prompt 里只放纯维语指令，模型可能根本读不懂你在让它做什么。

双语写法是个工程兜底：维吾尔文部分给维语能力较好的模型一个母语指令；中文部分作为 fallback——即使模型完全无视维文，也能从中文部分理解任务。

几轮本地测试里，这个策略比只放纯维文指令更稳：用户用维语提问时更容易回维语；在维语 UI 下偶尔切中文/英文提问，也更容易跟随当前提问语言，而不是僵化锁死。

细节二：🔒 prompt injection 防御

这一段是本节的工程含金量所在。

注意上面那段代码的 default 分支——未知 locale 直接返回空串，不拼接进 system prompt。为什么？

因为 metadata.user_locale 的源头是前端 localStorage 里的 hc-locale——这是不可信输入。任何用户都可以打开浏览器 DevTools，把 hc-locale 改成任意字符串。

攻击者可以这么干：

如果后端把这个字符串直接 sprintf 进 system prompt，用户控制的 locale 就变成了 prompt injection 入口。

v0.4.0 的防御方案：switch case 显式枚举所有合法 locale，未知值直接返回空串。新增语言必须显式加 case，不是开放变量注入。

原则：不要把前端传来的字符串直接拼进 system prompt；只用白名单枚举。

测试覆盖

engine/locale_directive_test.go（88 行），覆盖：

• 基础 case——zh-CN / en / ug-CN 各自返回正确指令
• 别名归一——ug 视为 ug-CN
• 注入字符串防御——任何 default 分支输入都返回空指令
• 注入位置——验证指令拼到 prompt 末尾、原 prompt 不被破坏

更上层 ChatPromptInjection 测试套件还有 11 个用例覆盖整个对话链路上的注入面，locale 只是其中一个攻击向量。

意外的副作用：连中文音译都能触发维语回复

这一段是测试时才撞上的彩蛋。

原本想做的事很直接：用户切到维语 UI + 用维文输入 → 模型用维语回。但 v0.4.0 发版前实测时撞上一件意料之外的事——用户输入中文音译，模型也会用维语回。

比如在维语 UI 下打"阿达西，一西米然"（维语口语里"朋友，你好"的中文音译写法）——模型直接用维语回，没切回中文。

再试"河蟹AI非常亚克西"（亚克西 = 维语"好"的音译），模型一样用维语回，还带了 emoji 和列表。

这是三层叠加出来的副作用：

1. system prompt 里已经写了"用户当前语言设置为维吾尔语"
2. 模型更容易把这些常见维语词汇和维语交流场景关联起来（亚克西、阿达西、撒拉姆这些词在中文互联网也常见）
3. 两个信号同时点亮，模型直接进入维语回复模式

实际意义挺有意思——用户哪怕不会切维文输入法，只要会几个维语词的汉字音译，也能跟 AI 用维语聊一段。对一个想试试维语 AI 但没装维文键盘的人来说，这是个意外友好。

能触发这种副作用，恰好说明后端 locale 指令那一层在工作——如果只做 UI 翻译、不做后端语言指令，输入中文音译时模型大概率会回中文。三层架构是不是接对了，这种 edge case 反而是很好的检验。

三层接起来，一次完整的维语对话长这样

把上面三层串起来，一次完整的维语对话流程：

1. 用户在 UI 切换语言为维吾尔语——前端 i18n 切到 ug-CN locale，1457 个 locale key 切换为维语；<html dir="rtl"> 属性切换
2. CSS 全量改造生效——[dir='rtl'] 选择器命中，所有 logical properties 自动镜像，unicode-bidi: plaintext 全局兜底，混排文本按内容首字符自动分段
3. 用户发送维语消息——前端把 user_locale: "ug-CN" 写入 chat metadata 发给后端
4. 后端构造 LLM 请求——localeOutputDirective("ug-CN") 返回双语指令拼到 system prompt 末尾（白名单校验通过的合法 locale 才拼，未知 locale 直接 ignore）
5. LLM 用维语回复——回复内容流式回到前端，渲染时再走一次 RTL 改造的 CSS

前端 i18n + 前端 CSS RTL + 后端 prompt 指令——三层缺一不可。
任何一层没做，体验都会断在那一层。i18n 听起来简单，但做完第一层之后还要补第二、第三层，才算把"维语支持"这件事真正做到位。

诚实写一下：这个版本还有什么没做对

写工程笔记不能只写顺利部分。

这一节把 v0.4.0 维语支持的实际测试覆盖和已知缺陷都摆出来。

已 PASS 的部分

• i18n + RTL 契约测试——验证切到 ug-CN 后根节点 lang="ug" + dir="rtl"，常用维语 key 解析正常
• RTL bidi 全局兜底回归——确保 [dir='rtl'] :is(...) 全局规则存在，日志页等未具名 class 不再漏覆盖
• locale 指令安全测试——覆盖 zh-CN / en / ug-CN + 恶意 locale 不进 system prompt
• Prompt injection 防御——ChatPromptInjection 11 个用例覆盖对话链路注入面
• 整包兜底——桌面端单测、后端 race + 全包测试通过

已知遗留

遗留：维语字体在某些 macOS 字体设置下有粘连。

少数 Mac 用户反馈维语字符之间出现轻微粘连——定位下来是 macOS 字体 fallback 链选到了不擅长阿拉伯字符渲染的字体。系统级问题，应用层无法根治。已在 docs 里给出 workaround：用户安装 Tahoma / Noto Naskh Arabic / 微软雅黑等字体后渲染恢复正常。

读者看到产品宣传"全面支持维语"，但切进去发现某些机器上字体粘连，仍然会觉得被骗。把字体 fallback 这类遗留问题提前写清楚，反而是诚信。

v0.4.0 不止做了维语

维语本地化只是这版的一件事。v0.4.0 不是一次常规小修，而是把桌面端体验和 Agent 底层能力一起往前推了一步：

• 🌍 支持维吾尔语——1457 个 i18n key、RTL bidi 全局兜底、后端 locale 指令三层打通，让维语用户打开就能从母语体验开始
• 🧠 Skill 闭环自学习——Skill 执行后沉淀轨迹，表现不佳时生成改进草稿，稳定组合可沉淀 meta-Skill，为"越用越聪明"打底
• 🤖 子 Agent 委托——7 种 Agent 策略模式覆盖规划、自查、多思路、记忆增强、辩论等任务场景，底层仍复用 ReActEngine，保留现有工具链和流式体验
• 💬 统一文本对话框——文本、图片、视频统一从一个输入框进入，按模型能力自动分流，用户不用在不同输入器之间切换
• 🧩 结构化交互组件——buttons / select / approval / card / block 五类交互接入，让 Agent 不只会回一段文字，也能给出可点击、可确认的操作
• ⚙️ 运行时治理——feature flag、events、model gateway、skill pipeline、tool lifecycle 纳入同一套开关体系，方便灰度启用和快速回退

本文只展开维语本地化这一件事，其它几条先作为 v0.4.0 的版本亮点交代到这里。

为什么花这么大篇幅写维语——不是因为它"最大"，而是因为它在本地 AI Agent 桌面端品类里长期被忽略。一个值得做的工程动作，越是没人做，越值得详细写下做法和踩过的坑——让下一个想做的人少走弯路。

本地 AI Agent 桌面端这个品类已经存在好几年了，
也该有一个版本，让维语用户打开就能用母语用得顺。

延伸阅读——河蟹系列前作：

1. 河蟹 AI vs OpenClaw / Hermes — 2026 本地 AI Agent 的三条路径
2. Claude Code SOP — 设计驱动 × 测试闭环 × 多 Agent 协作
3. 架构详解 — 一个人 × Claude Code × 5 个月 × 6 仓
4. 从养龙虾到养河蟹 — 产品发布 / OpenClaw 开题呼应
5. 思考过程 — 打通 Qwen / Gemma / DeepSeek-R1 的最后一公里
6. 完全指南 — 5 分钟从零到一个能干活的本地 AI Agent
7. 前 leader Skill — 把 leader 蒸馏成 AI Skill

参考资料

• HexClaw 河蟹 AI 生态仓库：github.com/hexagon-codes
• Unicode Bidirectional Algorithm：unicode.org/reports/tr9
• MDN · unicode-bidi：developer.mozilla.org/en-US/docs/Web/CSS/unicode-bidi
• MDN · CSS logical properties and values：developer.mozilla.org/en-US/docs/Web/CSS/CSS_logical_properties_and_values
• OWASP LLM01 · Prompt Injection：genai.owasp.org/llmrisk/llm01-prompt-injection

文中技术资料核验时间：2026-05-01，以官方文档和上游仓库为准。

HexClaw 河蟹 AI
本地云端均可部署 · 数据自主掌控 · 软件开源免费
官网 hexclaw.net  |  GitHub hexagon-codes
微博 @HexClaw  |  X @hexclawapp
邮箱：[email protected]