docs(worker): align guides with runtime behavior

Synchronize both language guides, API references and examples with
the implemented authorization, storage and delivery behavior.
Document migration requirements and accepted operational limits.
This commit is contained in:
翅膀 committed 2026-10-23 23:24:05 +08:00
1 parent a62044f359
commit 5fcb129170
47 files changed
+938 -660

No files matched your search

+7 -5
View File
@@ -8,17 +8,19 @@
## 自定义覆盖
翻译覆盖从 KV 键 `i18n:<lang>` 读取,值为扁平的「键 → 文本」JSON 对象。内置字典(en/zh)中的任意键都可覆盖;未提供的键回退为英文。
额外的消息语言从 KV 键 `i18n:<lang>` 读取:一个与内置字典(`server/lib/lib/locales/en.ts`)嵌套结构相同的 JSON 对象,未提供的键都会回退为英文。内置的 `en` 与 `zh` 不会从 KV 读取,因此不能这样覆盖;请使用其他语言代码(如 `zh-custom`),并把它设为分组的 `lang`。
```jsonc
// KV 键:i18n:zh
// KV 键:i18n:zh-custom
{
"events.push.title": "{repo}: 推送了 {count} 个提交到 {ref}",
"events": {
"push": { "title": "{repo}: 推送了 {count} 个提交到 {ref}" },
},
}
```
覆盖对分组消息(以及适用的控制台界面)生效。要新增一种语言,可在 `i18n:<lang>` 存放完整字典——未提供的键都会回退为英文。
已加载的字典会在每个 worker 实例中一直缓存到实例重启,因此修改后的覆盖可能要过一段时间才生效;没有覆盖的语言 5 分钟后会再次查找。覆盖只影响分组消息——控制台使用其内置的翻译。
## 表情开关
`Group.emoji`(默认 `true`)控制该分组消息中是否显示事件表情。关闭后,标题、描述、字段与链接中的所有表情都会被去除。里程碑进度条(🟢🟡🟠⬜)属于数据可视化,不受该开关影响。
`Group.emoji`(默认 `true`)控制该分组消息中是否显示事件表情。关闭后,格式化器添加到标题、描述、字段与链接中的表情都不会出现;取自载荷的文本(提交信息、issue 标题、自定义 webhook 字段)保留其中自带的表情。里程碑进度条(🟢🟡🟠⬜)属于数据可视化,不受该开关影响。