mai-bot/docs/i18n.md

i18n Guide

MaiBot 现在使用 JSON + Crowdin + Babel 的国际化方案，不依赖 gettext 的 .po/.mo 运行时。

目录结构

翻译文件位于 locales/<locale>/*.json，当前默认语言是 zh-CN。

建议按模块拆分文件：

• core.json
• startup.json
• config.json

在代码中使用

统一从 src/common/i18n/init.py 导入：

from src.common.i18n import t, tn

logger.info(t("startup.launching_script", script_file=script_file))
logger.info(tn("core.tasks_cancelled", count))

可用能力：

• t(key, locale=None, **kwargs)：普通翻译
• tn(key, count, locale=None, **kwargs)：plural 翻译
• set_locale(locale) / get_locale()：设置或读取当前默认 locale
• format_datetime_localized(...)
• format_number_localized(...)
• format_decimal_localized(...)

locale 优先级

运行时按以下顺序决定 locale：

1. 显式传入 locale
2. 当前上下文中的 locale 覆盖（如使用 use_locale(...)）
3. 环境变量 MAIBOT_LOCALE
4. 默认值 zh-CN

key 规范

• 使用稳定的点分 key，例如 startup.env_created
• 全部小写
• 不要把中文原文直接当 key

新增翻译的步骤

1. 先在 locales/zh-CN/*.json 添加 source 文案。
2. 在 locales/en-US/*.json 中补上同名 key。
3. 在代码中用 t() 或 tn() 替换硬编码字符串。
4. 运行 python scripts/i18n_validate.py 校验结构。

校验脚本

运行：

python scripts/i18n_validate.py

校验内容包括：

• JSON 语法是否合法
• 是否存在重复 key
• 是否存在空字符串 key
• 各语言 key 集合是否与 zh-CN 对齐
• 占位符集合是否一致
• plural 结构是否一致

候选扫描

如果你想继续做下一批迁移，可以运行：

python scripts/i18n_extract_candidates.py

这个脚本会扫描仓库中的 Python 文件，输出仍然包含中文字符串常量的位置，方便人工挑选下一批适合迁移到 i18n 的文案。

Crowdin

项目根目录的 crowdin.yml 使用 locales/zh-CN/*.json 作为 source。

GitHub Actions 中的 crowdin-sync.yml 会负责和 Crowdin 同步。

当前迁移范围

这一批已经覆盖：

• bot.py 启动、重启、退出与协议确认提示
• src/config 中第一批配置加载、热重载、校验异常提示
• src/main.py 的主要启动链路提示

暂不建议立即迁移：

• 大段 prompt 模板
• 内部协议字段
• debug-only 文案