ZCBOT

主题

多语言（界面语言） ​

ZCBOT 支持切换面向用户的提示文案语言。目前覆盖启动 / 停止等生命周期日志， 切换后无需改代码、重启即生效。

支持的语言 ​

代码名称基调启动文案示例
zh简体中文（默认）正式、简洁ZCBOT 框架 启动中...
ciallo中文活泼版俏皮、带颜文字Ciallo～(∠・ω< )⌒☆ ZCBOT 框架启动中咯～ 稍等一小下，马上就好喵～
enEnglish正式、简洁ZCBOT framework starting...

关于 Ciallo～ 「Ciallo～(∠・ω< )⌒☆」是柚子社 galgame《魔女的夜宴》女主角因幡巡的标志性问候语， 由意大利语「Ciao」与英语「Hello」合成，配上配套的卖萌颜文字，是中文 ACG 社群里 辨识度极高的活泼打招呼用语。这里只把它作为「活泼版」的语气基调——只改语气，不改事实。

三种设置方式（优先级从高到低） ​

1. 启动参数（优先级最高） ​

bash
python main.py --language ciallo
python main.py -l en              # 简写
python main.py --language=ciallo  # 等号写法

2. 环境变量 ​

bash
ZCBOT_LANG=ciallo python main.py

适合容器 / systemd 等不方便改参数文件的场景。

3. config.yaml（持久生效） ​

yaml
language: ciallo    # zh（默认）/ ciallo / en

首次启动自动生成的 config.yaml 里已包含该项（默认 zh），改完重启即可。

优先级：启动参数 → 环境变量 ZCBOT_LANG → config.yaml 的 language → 默认 zh。 三种方式可以混用，临时调试用参数、长期用配置文件。

实际效果 ​

# --language ciallo
INFO ==================================================
INFO Ciallo～(∠・ω< )⌒☆ ZCBOT 框架启动中咯～ 稍等一小下，马上就好喵～
INFO ==================================================
INFO Ciallo～(∠・ω< )⌒☆ 启动完成啦～ 正竖起耳朵等你的消息哦～（总共花了 3.31s）

# --language en
INFO ZCBOT framework starting...
INFO Framework started, waiting for messages... (took 3.90s)

# --language zh（默认）
INFO ZCBOT 框架 启动中...
INFO 框架启动完成，等待消息...（总耗时 3.20s）

覆盖范围 ​

当前已本地化 12 条，覆盖整条启动链路：

词条 key时机
framework.initializing框架核心引擎开始初始化
framework.init_done框架核心引擎初始化完成
framework.starting框架启动开始
framework.started框架启动完成（含耗时占位符 {elapsed}）
framework.stopping框架停止开始
framework.stopped框架已停止
app.ctrl_c收到 Ctrl+C 退出
plugin.loaded插件加载成功（含 {name} {version}）
plugin.disabled官方插件被禁用（含 {name} {enabled}）
webui.startedWeb 管理后台启动（含 {url}）
console.ready调试控制台就绪（含 {addr} {bits}）
terminal.skipped非交互终端，跳过终端交互

已用 ciallo 实测：一次启动共输出 47 处 Ciallo 文案。

框架其余日志（数据库连接、安全策略、迁移、蜜罐等）仍为中文 —— 它们是运维诊断信息， 不是面向终端用户的提示，刻意保持单一语言以避免跨语言排查困难。

CLI 配置控制台 ​

不用手改 YAML，直接在命令行查看 / 修改配置（写回 config.yaml）:

bash
python main.py config                      # 显示配置摘要（含当前语言、可用语言）
python main.py config get language         # 查看某一项
python main.py config set language ciallo  # 修改某一项（重启后生效）

输出示例：

配置文件: C:\path\to\config.yaml
ZCBOT 配置摘要
----------------------------------------------
  language               ciallo
  database.type          sqlite
  onebot.listen_port     6830
  web.port               8080
----------------------------------------------
可用语言: zh, ciallo, en
示例: python main.py config set language ciallo（重启后生效）

细节：

  • 支持 --config <path> / --config=<path> 指定配置文件。
  • set 采用按行原地替换而非 yaml.dump，所以 config.yaml 里的中文注释完整保留。
  • 设置 language 时会做合法性归一化提示（如 zh_CN → 提示按 zh 生效）。

给插件开发者 ​

插件可以直接复用同一套 i18n 能力给用户返回本地化文案：

python
from framework import i18n

i18n.set_language('ciallo')                      # 通常不需要：跟随框架全局设置
i18n.t('framework.starting')                    # → Ciallo～(∠・ω< )⌒☆ ...
i18n.t('framework.started', elapsed='1.23')     # 支持 {} 占位符

新增词条：在 framework/lang/ 下对应的 zh.yaml / ciallo.yaml / en.yaml 里各加一条即可（zh 同时是回退源，建议先补 zh）。目前有 zh / ciallo / en 三个文件；新增语言只需在 framework/lang/ 下加一个 <code>.yaml，无需改代码。

API ​

函数说明
i18n.t(key, **kwargs)取本地化文案，支持 {} 占位符
i18n.set_language(lang)设置语言，返回实际生效代码（无法识别时回退 zh）
i18n.get_language()当前生效的语言代码
i18n.available_languages()所有支持的语言代码
i18n.normalize(lang)归一化写法（zh_CN / en_US / CIALLO → 标准代码）

设计约定与坑 ​

  1. 协议标识符不翻译。 例如调试控制台的 'ZCBOT console' banner 是进程探测用的 协议字段，翻译会破坏「已有控制台在跑」的探测逻辑与相关测试断言。只翻译给人看的文案。
  2. 缺失必回退，绝不抛异常。 取词顺序是「当前语言 → zh → key 本身」； 占位符填充失败时原样返回模板 —— 启动日志不能因为文案问题把框架带崩。
  3. 不引入 gettext / .po / .mo。 词条外置于 framework/lang/ 下的 YAML 数据文件（嵌套结构，加载时自动展平为点号 key），由 PyYAML 解析，框架运行环境已具备；改完文案即生效，适合「文案随版本走、不随系统 locale 走」的场景。
  4. 启动参数会被提前摘出。 --language / -l 在进入子命令解析前就被摘掉并同步回 sys.argv，否则会被下游当成配置文件路径（同类历史坑：python main.py argparse 曾生成一个叫 argparse 的默认配置）。

基于 MIT + Apache 2.0 双协议发布

Copyright © 2026 ZCBOT