i18n: crowdin integration

docs/i18n.md

@@ -0,0 +1,102 @@
+# 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](/Users/sayaka/workspace/MaiBot/src/common/i18n/__init__.py) 导入：
+
+```python
+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` 校验结构。
+
+## 校验脚本
+
+运行：
+
+```bash
+python scripts/i18n_validate.py
+```
+
+校验内容包括：
+
+- JSON 语法是否合法
+- 是否存在重复 key
+- 是否存在空字符串 key
+- 各语言 key 集合是否与 `zh-CN` 对齐
+- 占位符集合是否一致
+- plural 结构是否一致
+
+## 候选扫描
+
+如果你想继续做下一批迁移，可以运行：
+
+```bash
+python scripts/i18n_extract_candidates.py
+```
+
+这个脚本会扫描仓库中的 Python 文件，输出仍然包含中文字符串常量的位置，方便人工挑选下一批适合迁移到 i18n 的文案。
+
+## Crowdin
+
+项目根目录的 [crowdin.yml](/Users/sayaka/workspace/MaiBot/crowdin.yml) 使用 `locales/zh-CN/*.json` 作为 source。
+
+GitHub Actions 中的 [crowdin-sync.yml](/Users/sayaka/workspace/MaiBot/.github/workflows/crowdin-sync.yml) 会负责和 Crowdin 同步。
+
+## 当前迁移范围
+
+这一批已经覆盖：
+
+- `bot.py` 启动、重启、退出与协议确认提示
+- `src/config` 中第一批配置加载、热重载、校验异常提示
+- `src/main.py` 的主要启动链路提示
+
+暂不建议立即迁移：
+
+- 大段 prompt 模板
+- 内部协议字段
+- debug-only 文案