ClawdBot国际化：添加新语言支持（如越南语/阿拉伯语）的完整流程

ClawdBot 是一个你可以在自己设备上运行的个人 AI 助手，本应用使用 vLLM 提供后端模型能力。它不是云端黑盒，而是一个真正属于你的本地智能中枢——所有对话、文件处理、工作流编排都在你可控的环境中完成。它的设计哲学很朴素：不依赖网络请求就能响应，不上传隐私就能理解上下文，不装复杂插件就能完成多步任务。

但有一个现实问题始终存在：当你想把 ClawdBot 推广给说越南语的朋友、服务阿拉伯语地区的远程团队，或者让家里的长辈用母语和它交流时，系统默认只支持英文界面和有限的语言交互能力。这不是模型能力的天花板，而是本地化配置的“最后一公里”没走完。

好消息是，ClawdBot 的架构从第一天起就为多语言预留了接口。它不像某些闭源工具那样把语言硬编码进前端或锁死在模型 prompt 里，而是通过清晰分层的国际化机制——UI 翻译资源、指令关键词映射、模型输入/输出语言协商、以及后端服务的语言感知路由——让你能真正“按需添加”，而不是“被迫接受”。

本文不讲理论，不堆概念，只带你从零开始，亲手为 ClawdBot 加入越南语（vi）和阿拉伯语（ar）支持。整个过程不需要改一行核心代码，不重编译镜像，不重启服务，甚至不需要联网下载新模型。你只需要理解三个关键位置、修改四类配置文件、验证五个实际场景——50 分钟内，你的 ClawdBot 就能用越语打招呼、用阿语查天气、用双语切换回答用户问题。

---

1. 理解 ClawdBot 的国际化分层结构

ClawdBot 的语言支持不是“一刀切”的全局开关，而是由四个相互协作又彼此解耦的模块共同构成。只有看清这个结构，你才不会在配置中迷失方向。

1.1 前端 UI 界面语言（用户看到的按钮、菜单、提示）

这是最直观的一层。ClawdBot 前端基于 Gradio 构建，其语言包存放在 /app/i18n/ 目录下，每个语言对应一个 JSON 文件，例如：

• en.json（英语，默认）
• zh.json（中文，已内置）
• ja.json（日语，社区贡献）

这些文件不包含逻辑，只负责把界面上的固定字符串（如 "Settings"、"Model Provider"、"Save Config"）映射为对应语言的翻译。添加新语言，第一步就是在这里放一个 vi.json 和 ar.json。

1.2 指令关键词识别（用户输入的 /help、/settings 怎么被理解）

ClawdBot 的命令系统支持多语言关键词。比如用户输入 /trợ giúp（越语“帮助”）或 /مساعدة（阿语“帮助”），系统需要知道这等价于 /help。这个映射关系定义在 /app/config/commands.json 中，格式如下：

{
  "help": ["help", "trợ giúp", "مساعدة", "hilfe", "aide"]
}

注意：这里不是翻译，而是“同义词列表”。ClawdBot 会把所有列出的字符串统一归一化为内部指令名 help，再执行后续逻辑。

1.3 模型输入/输出语言协商（AI 怎么知道该用什么语言思考和回答）

这是最关键的智能层。ClawdBot 不会强制模型说某种语言，而是通过精心设计的 system prompt + user message 结构，向模型明确传递语言意图。例如，当用户用越南语提问时，ClawdBot 会自动构造类似这样的输入：

<|system|>Bạn là một trợ lý AI hữu ích, luôn trả lời bằng tiếng Việt. Hãy giữ câu trả lời ngắn gọn và chính xác.<|end|>
<|user|>Hôm nay thời tiết thế nào ở Hà Nội?<|end|>

这个行为由 /app/config/language_rules.json 控制，它定义了：

• 哪些语言代码触发哪种 system prompt 模板
• 是否启用自动语言检测（基于用户首条消息）
• 是否允许跨语言混合输入（如中英混输）

1.4 后端服务语言感知（天气、汇率、维基等插件如何返回本地化结果）

ClawdBot 内置的快捷命令（如 /weather、/fx）调用的是本地服务或轻量 API。它们本身不带语言，但 ClawdBot 会在调用前注入 lang=vi 或 lang=ar 参数，并对返回的原始数据做二次本地化处理（比如把 "Sunny" 转成 "Nắng"）。这部分逻辑集中在 /app/services/ 下的各插件模块中，修改点明确且隔离。

---

2. 添加越南语（vi）支持：从零到可用的实操步骤

我们以越南语为例，走一遍完整流程。所有操作均在 ClawdBot 容器内进行，无需宿主机额外环境。

2.1 创建越南语 UI 翻译文件

进入容器并创建语言包：

docker exec -it clawdbot bash
mkdir -p /app/i18n
cd /app/i18n

新建 vi.json，内容如下（仅列出核心字段，完整版见文末附录）：

{
  "Settings": "Cài đặt",
  "Model Provider": "Nhà cung cấp mô hình",
  "Save Config": "Lưu cấu hình",
  "Language": "Ngôn ngữ",
  "Vietnamese": "Tiếng Việt",
  "Help": "Trợ giúp",
  "About": "Giới thiệu",
  "Dashboard": "Bảng điều khiển",
  "Connected Devices": "Thiết bị đã kết nối",
  "No devices connected yet": "Chưa có thiết bị nào được kết nối"
}

验证方式：重启 Gradio 服务（kill -HUP $(pgrep -f 'gradio')），刷新页面，在设置中选择 “Tiếng Việt”，确认所有按钮文字已变更。

2.2 注册越南语指令关键词

编辑 /app/config/commands.json，找到 help 条目，追加越南语关键词：

{
  "help": ["help", "trợ giúp", "giúp đỡ", "hỗ trợ"],
  "settings": ["settings", "cài đặt", "thiết lập"],
  "weather": ["weather", "thời tiết", "dự báo thời tiết"],
  "fx": ["fx", "tỷ giá", "tỷ giá hối đoái"],
  "wiki": ["wiki", "wikipedia", "bách khoa toàn thư"]
}

验证方式：在聊天框输入 /trợ giúp，应弹出与 /help 完全一致的帮助菜单；输入 /thời tiết Hà Nội，应正确触发天气查询。

2.3 配置越南语模型交互规则

编辑 /app/config/language_rules.json，在 rules 数组中添加：

{
  "code": "vi",
  "name": "Tiếng Việt",
  "detect": true,
  "system_prompt_template": "<|system|>Bạn là một trợ lý AI hữu ích, luôn trả lời bằng tiếng Việt. Hãy giữ câu trả lời ngắn gọn và chính xác.<|end|>",
  "fallback_code": "en"
}

同时确保 auto_detect_enabled 为 true。

验证方式：用越南语发送任意问题（如 “Qwen3 có hỗ trợ tiếng Việt không?”），观察模型回复是否全程使用越南语，且无中英文混杂。

2.4 启用越南语后端服务本地化

ClawdBot 的天气服务默认返回英文城市名和状态。我们需要让它识别 lang=vi 并返回越语结果。

编辑 /app/services/weather.py，找到 get_weather_data() 函数，在请求 URL 后追加 &lang=vi 参数：

# 原始行（可能类似）
url = f"http://api.openweathermap.org/data/2.5/weather?q={city}&appid={API_KEY}"

# 修改为
url = f"http://api.openweathermap.org/data/2.5/weather?q={city}&appid={API_KEY}&lang=vi"

验证方式：执行 /thời tiết Hồ Chí Minh，返回结果中的天气描述（如 "Trời nắng"）、风向（"Gió Đông Nam"）均为越南语。

---

3. 添加阿拉伯语（ar）支持：注意事项与避坑指南

阿拉伯语比越南语更复杂：右向左（RTL）排版、连字渲染、Unicode 变体多。ClawdBot 前端（Gradio）原生支持 RTL，但需额外配置。

3.1 创建阿拉伯语 UI 翻译文件

在 /app/i18n/ar.json 中，必须包含 "direction": "rtl" 字段，否则文本会显示错乱：

{
  "direction": "rtl",
  "Settings": "الإعدادات",
  "Model Provider": "مزود النموذج",
  "Save Config": "حفظ الإعدادات",
  "Language": "اللغة",
  "Arabic": "العربية",
  "Help": "مساعدة",
  "About": "حول",
  "Dashboard": "لوحة التحكم",
  "Connected Devices": "الأجهزة المتصلة",
  "No devices connected yet": "لا توجد أجهزة متصلة بعد"
}

关键避坑：不要用普通文本编辑器直接写阿拉伯字符。务必使用支持 UTF-8 的编辑器（如 VS Code），保存时确认编码为 UTF-8 without BOM。否则 Gradio 会读取失败，界面变空白。

3.2 阿拉伯语指令关键词的特殊处理

阿拉伯语存在多种拼写习惯（如 مساعدة vs مَساعَدَة），ClawdBot 默认只做精确匹配。为提升鲁棒性，建议在 commands.json 中加入常见变体：

"help": ["help", "مساعدة", "مَساعَدَة", "استعن", "أحتاج مساعدة"]

同时，ClawdBot 的命令解析器对 Unicode 空格敏感。确保所有关键词前后没有不可见空格或零宽字符（Zero Width Space）。可用在线工具 https://www.soscisurvey.de/tools/view-chars.php 检查。

3.3 阿拉伯语模型交互的字体与渲染

Qwen3 等主流模型对阿拉伯语支持良好，但 Gradio 界面需加载合适字体才能正确显示连字（如 لَا 应显示为一个连笔字符，而非 ل+ا 分离）。

在 /app/templates/index.html 的 <head> 中追加：

<link href="https://fonts.googleapis.com/css2?family=Tajawal:wght@300;400;500;700&display=swap" rel="stylesheet">
<style>
  .gradio-container[dir="rtl"] { font-family: 'Tajawal', sans-serif; }
</style>

验证方式：输入 /مساعدة，菜单正常显示；发送阿拉伯语问题（如 “ما هو طقس الرياض اليوم؟”），模型回复阿拉伯语，且所有字符连贯无断裂。

---

4. 全局验证与效果对比：确保每处都生效

添加完两种语言后，不能只测单点。要模拟真实用户路径，覆盖全部交互环节。

4.1 四维度交叉验证表

验证维度	越南语测试用例	阿拉伯语测试用例	期望结果
UI 界面	设置页选择 “Tiếng Việt”	设置页选择 “العربية”	所有按钮、标签、提示文字均为目标语言
指令识别	输入 /cài đặt	输入 /الإعدادات	正确打开设置面板，无报错
模型对话	发送 “Dịch đoạn này sang tiếng Anh”	发送 “ترجم هذه الجملة إلى الإنجليزية”	模型用目标语言解释任务，并用英文翻译
插件服务	/tỷ giá USD	/سعر صرف الدولار	返回结果含越南语/阿拉伯语单位与说明

4.2 一键验证脚本（推荐保存为 verify_i18n.sh）

#!/bin/bash
echo "=== Testing Vietnamese UI ==="
curl -s http://localhost:7860/ | grep -q "Tiếng Việt" && echo " VI UI loaded" || echo "❌ VI UI failed"

echo "=== Testing Arabic Command ==="
echo "/المساعدة" | docker exec -i clawdbot clawdbot chat --stdin | grep -q "مرحبا" && echo " AR command parsed" || echo "❌ AR command failed"

echo "=== Testing Weather Localization ==="
docker exec clawdbot python -c "
import json
from app.services.weather import get_weather_data
res = get_weather_data('Hanoi', lang='vi')
print(' VI weather has Vietnamese text' if 'Nắng' in res.get('description', '') else '❌ VI weather not localized')
"

运行后，四行输出应全为 。

---

5. 进阶技巧：让多语言支持更智能、更省心

完成基础添加只是起点。以下技巧能显著提升体验，且改动极小。

5.1 自动语言检测 + 用户偏好记忆

ClawdBot 默认每次对话都重新检测语言，但用户通常有稳定偏好。可在 /app/config/user_prefs.json 中添加：

{
  "default_language": "vi",
  "auto_detect_fallback": "en",
  "per_user_lang": {
    "123456789": "ar",  // Telegram 用户 ID → 语言
    "987654321": "vi"
  }
}

然后在消息处理器中优先读取此配置，再 fallback 到自动检测。

5.2 混合语言输入支持（中越混输、阿英混输）

很多用户习惯夹杂母语和术语（如 “Xem lại log của service ‘clawdbot’”）。ClawdBot 支持在 system prompt 中启用 mixed_language_mode：

{
  "code": "vi",
  "mixed_language_mode": true,
  "system_prompt_template": "<|system|>Bạn là trợ lý AI song ngữ (Việt-Anh). Giữ phần giải thích bằng tiếng Việt, nhưng giữ thuật ngữ kỹ thuật như 'log', 'service', 'container' nguyên bản.<|end|>"
}

5.3 一键生成语言包的 Python 工具

手动翻译费时易错。用 Google Translate API（或离线模型）批量生成初稿：

# gen_vi_translations.py
import json
from googletrans import Translator

translator = Translator()
en_keys = ["Settings", "Model Provider", "Save Config", ...]

vi_dict = {"direction": "ltr"}
for key in en_keys:
    vi_dict[key] = translator.translate(key, src='en', dest='vi').text

with open("vi.json", "w", encoding="utf-8") as f:
    json.dump(vi_dict, f, ensure_ascii=False, indent=2)

提示：生成后务必人工校对！机器翻译常错在敬语、技术术语和文化适配（如 “Dashboard” 译为 “Bảng điều khiển” 比直译 “Bảng điều hướng” 更准确）。

---

6. 总结：你已掌握 ClawdBot 国际化的完整方法论

回顾整个流程，你其实只做了三件事：
第一，把语言字符串放进 /i18n/ 目录——解决用户“看得到”的问题；
第二，把关键词塞进 /config/commands.json——解决用户“说得通”的问题；
第三，把语言规则写进 /config/language_rules.json——解决 AI“听得懂、答得准”的问题。

这三层结构清晰、职责分明、修改安全。它不依赖任何外部服务，不改变模型权重，不增加部署负担。你添加的每一个新语言，都是对 ClawdBot “个人助手”定位的再次确认：它服务于你，也服务于你关心的每一个人。

下一步，你可以：

• 把 vi.json 和 ar.json 提交到 ClawdBot 官方仓库，成为社区标准语言包；
• 为更多小众语言（如泰语、希伯来语）复用本文流程；
• 结合 MoltBot 的多模态能力，让图片 OCR 结果也自动翻译为你的首选语言。

真正的国际化，从来不是堆砌功能，而是让每一种语言的使用者，都感觉这个工具是为他而生的。

---

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。