chore: locale specific glossaries

4 files changed, 158 insertions, 0 deletions

diff --git a/.opencode/agent/glossary/README.md b/.opencode/agent/glossary/README.md
new file mode 100644
index 000000000..39d0456ae
--- /dev/null
+++ b/.opencode/agent/glossary/README.md
@@ -0,0 +1,60 @@
+# Locale Glossaries
+
+Use this folder for locale-specific translation guidance that supplements `.opencode/agent/translator.md`.
+
+The global glossary in `translator.md` remains the source of truth for shared do-not-translate terms (commands, code, paths, product names, etc.). These locale files capture community learnings about phrasing and terminology preferences.
+
+## File Naming
+
+- One file per locale
+- Use lowercase locale slugs that match docs locales when possible (for example, `zh-cn.md`, `zh-tw.md`)
+- If only language-level guidance exists, use the language code (for example, `fr.md`)
+
+## What To Put In A Locale File
+
+- **Sources**: PRs/issues/discussions that motivated the guidance
+- **Do Not Translate (Locale Additions)**: locale-specific terms or casing decisions
+- **Preferred Terms**: recurring UI/docs words with preferred translations
+- **Guidance**: tone, style, and consistency notes
+- **Avoid** (optional): common literal translations or wording we should avoid
+
+Prefer guidance that is:
+
+- Repeated across multiple docs/screens
+- Easy to apply consistently
+- Backed by a community contribution or review discussion
+
+## Template
+
+```md
+# <locale> Glossary
+
+## Sources
+
+- PR #12345: https://github.com/anomalyco/opencode/pull/12345
+
+## Do Not Translate (Locale Additions)
+
+- `OpenCode` (preserve casing)
+
+## Preferred Terms
+
+| English | Preferred | Notes     |
+| ------- | --------- | --------- |
+| prompt  | ...       | preferred |
+| session | ...       | preferred |
+
+## Guidance
+
+- Prefer natural phrasing over literal translation
+
+## Avoid
+
+- Avoid ... when ...
+```
+
+## Contribution Notes
+
+- Mark entries as preferred when they may evolve
+- Keep examples short
+- Add or update the `Sources` section whenever you add a new rule
diff --git a/.opencode/agent/glossary/zh-cn.md b/.opencode/agent/glossary/zh-cn.md
new file mode 100644
index 000000000..054e94b7e
--- /dev/null
+++ b/.opencode/agent/glossary/zh-cn.md
@@ -0,0 +1,42 @@
+# zh-cn Glossary
+
+## Sources
+
+- PR #13942: https://github.com/anomalyco/opencode/pull/13942
+
+## Do Not Translate (Locale Additions)
+
+- `OpenCode` (preserve casing in prose; keep `opencode` only when it is part of commands, package names, paths, or code)
+- `OpenCode Zen`
+- `OpenCode CLI`
+- `CLI`, `TUI`, `MCP`, `OAuth`
+- `Model Context Protocol` (prefer the English expansion when introducing `MCP`)
+
+## Preferred Terms
+
+These are preferred terms for docs/UI prose and may evolve.
+
+| English                 | Preferred | Notes                                       |
+| ----------------------- | --------- | ------------------------------------------- |
+| prompt                  | 提示词    | Keep `--prompt` unchanged in flags/code     |
+| session                 | 会话      |                                             |
+| provider                | 提供商    |                                             |
+| share link / shared URL | 分享链接  | Prefer `分享` for user-facing share actions |
+| headless (server)       | 无界面    | Docs wording                                |
+| authentication          | 认证      | Prefer in auth/OAuth contexts               |
+| cache                   | 缓存      |                                             |
+| keybind / shortcut      | 快捷键    | User-facing docs wording                    |
+| workflow                | 工作流    | e.g. GitHub Actions workflow                |
+
+## Guidance
+
+- Prefer natural, concise phrasing over literal translation
+- Keep the tone direct and friendly (PR #13942 consistently moved wording in this direction)
+- Preserve technical artifacts exactly: commands, flags, code, inline code, URLs, file paths, model IDs
+- Keep enum-like values in English when they are literals (for example, `default`, `json`)
+- Prefer consistent terminology across pages once a term is chosen (`会话`, `提供商`, `提示词`, etc.)
+
+## Avoid
+
+- Avoid `opencode` in prose when referring to the product name; use `OpenCode`
+- Avoid mixing alternative terms for the same concept across docs when a preferred term is already established
diff --git a/.opencode/agent/glossary/zh-tw.md b/.opencode/agent/glossary/zh-tw.md
new file mode 100644
index 000000000..283660e12
--- /dev/null
+++ b/.opencode/agent/glossary/zh-tw.md
@@ -0,0 +1,42 @@
+# zh-tw Glossary
+
+## Sources
+
+- PR #13942: https://github.com/anomalyco/opencode/pull/13942
+
+## Do Not Translate (Locale Additions)
+
+- `OpenCode` (preserve casing in prose; keep `opencode` only when it is part of commands, package names, paths, or code)
+- `OpenCode Zen`
+- `OpenCode CLI`
+- `CLI`, `TUI`, `MCP`, `OAuth`
+- `Model Context Protocol` (prefer the English expansion when introducing `MCP`)
+
+## Preferred Terms
+
+These are preferred terms for docs/UI prose and may evolve.
+
+| English                 | Preferred | Notes                                       |
+| ----------------------- | --------- | ------------------------------------------- |
+| prompt                  | 提示詞    | Keep `--prompt` unchanged in flags/code     |
+| session                 | 工作階段  |                                             |
+| provider                | 供應商    |                                             |
+| share link / shared URL | 分享連結  | Prefer `分享` for user-facing share actions |
+| headless (server)       | 無介面    | Docs wording                                |
+| authentication          | 認證      | Prefer in auth/OAuth contexts               |
+| cache                   | 快取      |                                             |
+| keybind / shortcut      | 快捷鍵    | User-facing docs wording                    |
+| workflow                | 工作流程  | e.g. GitHub Actions workflow                |
+
+## Guidance
+
+- Prefer natural, concise phrasing over literal translation
+- Keep the tone direct and friendly (PR #13942 consistently moved wording in this direction)
+- Preserve technical artifacts exactly: commands, flags, code, inline code, URLs, file paths, model IDs
+- Keep enum-like values in English when they are literals (for example, `default`, `json`)
+- Prefer consistent terminology across pages once a term is chosen (`工作階段`, `供應商`, `提示詞`, etc.)
+
+## Avoid
+
+- Avoid `opencode` in prose when referring to the product name; use `OpenCode`
+- Avoid mixing alternative terms for the same concept across docs when a preferred term is already established
diff --git a/.opencode/agent/translator.md b/.opencode/agent/translator.md
index 0c2e176d8..030714071 100644
--- a/.opencode/agent/translator.md
+++ b/.opencode/agent/translator.md
@@ -13,10 +13,24 @@ Requirements:
 - Preserve meaning, intent, tone, and formatting (including Markdown/MDX structure).
 - Preserve all technical terms and artifacts exactly: product/company names, API names, identifiers, code, commands/flags, file paths, URLs, versions, error messages, config keys/values, and anything inside inline code or code blocks.
 - Also preserve every term listed in the Do-Not-Translate glossary below.
+- Also apply locale-specific guidance from `.opencode/agent/glossary/<locale>.md` when available (for example, `zh-cn.md`).
 - Do not modify fenced code blocks.
 - Output ONLY the translation (no commentary).
 
 If the target locale is missing, ask the user to provide it.
+If no locale-specific glossary exists, use the global glossary only.
+
+---
+
+# Locale-Specific Glossaries
+
+When a locale glossary exists, use it to:
+
+- Apply preferred wording for recurring UI/docs terms in that locale
+- Preserve locale-specific do-not-translate terms and casing decisions
+- Prefer natural phrasing over literal translation when the locale file calls it out
+
+Locale guidance does not override code/command preservation rules or the global Do-Not-Translate glossary below.
 
 ---