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 @@ Set `Group.lang` (e.g. `"zh"`) to choose the message language for every route in
## Custom Overrides
Translation overrides are merged from KV under the key `i18n:<lang>` as a flat JSON object of key → text. Any key from the built-in dictionaries (en/zh) can be overridden; unknown keys fall back to English.
Additional message languages are read from KV under the key `i18n:<lang>`: a JSON object with the same nested structure as the built-in dictionaries (`server/lib/lib/locales/en.ts`). Every key you do not provide falls back to English. The built-in `en` and `zh` are never read from KV, so they cannot be overridden this way; use another language code (e.g. `zh-custom`) and set it as the group's `lang`.
```jsonc
// KV key: i18n:zh
// KV key: i18n:zh-custom
{
"events.push.title": "{repo}: 推送了 {count} 个提交到 {ref}",
"events": {
"push": { "title": "{repo}: 推送了 {count} 个提交到 {ref}" },
},
}
```
Overrides apply to group messages (and console UI where applicable). To add a brand-new language, store a full dictionary at `i18n:<lang>` — every key you do not provide falls back to English.
A loaded dictionary stays cached in each worker instance until it restarts, so a changed override may take a while to apply; a language with no override is looked up again after 5 minutes. Overrides affect group messages only — the console has its own built-in translations.
## Emoji Toggle
`Group.emoji` (default `true`) controls whether event emoji appear in that group's messages. When disabled, all emoji are stripped from titles, descriptions, fields, and links. Milestone progress bars (🟢🟡🟠⬜) are data visualization and stay regardless of the toggle.
`Group.emoji` (default `true`) controls whether event emoji appear in that group's messages. When disabled, the emoji the formatters add are left out of titles, descriptions, fields, and links; text taken from the payload (commit messages, issue titles, custom webhook fields) keeps any emoji it contains. Milestone progress bars (🟢🟡🟠⬜) are data visualization and stay regardless of the toggle.