@linkdesk/plugin-docs 0.1.50 → 0.1.51

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -337,7 +337,7 @@ The difference from `configuration`: `configuration` defines **your own** settin
337
337
  {
338
338
  "contributes": {
339
339
  "themes": [
340
- { "id": "my-theme-dark", "label": "My Theme Dark", "uiTheme": "dark", "path": "themes/my-dark.json" }
340
+ { "id": "my-theme-dark", "label": "我的深色主题", "uiTheme": "dark", "path": "themes/my-dark.json" }
341
341
  ]
342
342
  }
343
343
  }
@@ -346,10 +346,20 @@ The difference from `configuration`: `configuration` defines **your own** settin
346
346
  | Field | Required | Description |
347
347
  |------|:--:|------|
348
348
  | `id` | ✅ | theme ID |
349
- | `label` | ✅ | display name |
349
+ | `label` | ✅ | display name — **write the original Chinese text** (a Chinese UI shows it verbatim); the English translation lives in your own `i18n/en.json` (§3.9). ⛔ Do not write a bilingual literal |
350
350
  | `uiTheme` | ✅ | `"dark"` \| `"light"` \| `"highContrast"` |
351
351
  | `path` | ✅ | path to the theme definition JSON file (`appearance` + `colorways[]`) — **relative to the plugin directory** |
352
352
 
353
+ > **🔥 How names are written (2026-10-01 user decision: "no more bilingual names")**: `label`, the top-level `name`
354
+ > of the recipe JSON that `path` points to, and `colorways[].name` **all carry the original Chinese text** — a
355
+ > Chinese UI shows it verbatim, and an English UI gets the translation from **your own dictionary** via the shell's
356
+ > `t()` (the same rule as `app.themeColor`: whoever owns the repo owns the translation). ⛔ **Do not write a
357
+ > bilingual literal** (`"薄荷苏打 Mint Soda"`) — a Chinese UI would then mix Chinese and English, and that disease
358
+ > is only cured by "literal pure Chinese + translation lives in the dictionary". A machine check guards this:
359
+ > stage ⑧ of `npm run verify` (`@linkdesk/plugin-sdk/own-dict-coverage`) covers **all three** places
360
+ > (`themes[].label` plus `name`/`colorways[].name` in the recipe file), and a missing translation turns red on the
361
+ > spot. For the exact form and an example see [11-authoring-themes](11-authoring-themes.md) §⑤.
362
+
353
363
  The declaration is metadata-only; theme color data is fetched asynchronously at load time. A legacy top-level `themes` field is normalized automatically (see `02 §2.1`).
354
364
 
355
365
  > **🔥 Recipe JSON contract (now folded into plugin-sdk)**: the recipe file that `path` points to is validated against `theme.schema.json` — inside the repo that is `public/schemas/theme.schema.json` (`npm run check` chains `check-theme-schema.mjs`, and a format error turns the light red with exit 1 on the spot instead of staying silent); for npm authors it is the `schemas/theme.schema.json` shipped with `@linkdesk/plugin-sdk` plus the SDK's `validateThemeJson` (the same schema file, so the rules never drift). At runtime, a `parseThemeRecipe` toast is the second line of defense. Theme files should begin with `"$schema"` pointing at the schema to get editor IntelliSense (for the npm path see [11-authoring-themes](11-authoring-themes.md) §②).
@@ -446,7 +456,7 @@ No `font` section → zero custom fonts (codicon fallback / a pure image-asset t
446
456
 
447
457
  > **🔥 mappings JSON contract (established — icon-theme.schema.json rewritten to align with the engine's normalizeIconThemeMappings)**: the mappings file that `path` points to is validated against `icon-theme.schema.json` — inside the repo that is `public/schemas/icon-theme.schema.json` (`npm run check` chains `check-theme-schema.mjs`, which also scans `contributes.iconThemes`); for npm authors it is the `schemas/icon-theme.schema.json` shipped with `@linkdesk/plugin-sdk` plus the SDK's `validateIconThemeJson` (the same schema file, so the rules never drift). A runtime parse failure with warn/toast is the second line of defense. Files should begin with `"$schema"` pointing at the schema to get editor IntelliSense.
448
458
 
449
- **id naming rule:** an icon-theme id is judged on **one thing only** — it must **not** be the host fallback id `default` (red: the id is not registered, plus one `console.error`). The "carry your repo prefix" criterion is **not applied here**: an icon-theme id is **shown verbatim in the settings page** (the picker renders the id text), so renaming it would change user-visible text ⇒ it stays as it is. If you want it to read better in the dropdown, change the `label` (display name), not the id.
459
+ **id naming rule:** an icon-theme id is judged on **one thing only** — it must **not** be the host fallback id `default` (red: the id is not registered, plus one `console.error`). The "carry your repo prefix" criterion is **not applied here**: an icon-theme id is a **registration key** (the value users store in `app.iconTheme`), so renaming it means migrating old values for no gain ⇒ it stays as it is. ⚠️ **Correction, 2026-10-01**: the dropdown **now renders the `label`** (display path wired up — see the exemption note below) — to make it read better in the dropdown, translate the `label` (in your own dictionary), ⛔ not the id.
450
460
 
451
461
  ```
452
462
  → "appearanceIconThemeIds": ["default"] ← icon-theme column (this is its only entry)
@@ -496,6 +506,7 @@ Plugin A contributes, plugin B references (`"icon": "stm32-chip"` + `"iconSource
496
506
  - In `contributes.i18n` the key = a language code and the value = the path to a JSON translation file (key = the original Chinese text, value = the translation). **No zh.json is needed** — Chinese keys fall back to themselves.
497
507
  - Translation files are loaded through `fetchPluginDataFile` (bypassing the Vite glob cache — JSON in a newly installed plugin directory is discovered in real time).
498
508
  - The plugin text iron rule: **all UI text goes through `t()`**, and the i18n key is the original Chinese text (`05 §6`).
509
+ - 🔴 **Literals carry the original text only — never a bilingual string** (2026-10-01 user decision: "no more bilingual names"): writing the literal as `"薄荷苏打 Mint Soda"` makes **the Chinese UI mix Chinese and English too** (the key *is* the display text; with no translation available it is emitted verbatim). The correct form is the literal `"薄荷苏打"` plus your own dictionary entry `{ "薄荷苏打": "Mint Soda" }` — a Chinese UI falls back to the original, an English UI reads the translation. The check does not test for "contains Latin letters" (a Chinese name may legitimately contain a proper noun such as 「Cascadia Mono 终端」, and a mechanical test would produce false positives); what it enforces is **"the name must live in a dictionary"**: either drop the English or translate it in your own dictionary — both require work in your own repo.
499
510
 
500
511
  #### 🔴 Whoever declares it translates it — your own text must be translated in your own repo (**a rule, not advice**)
501
512
 
@@ -531,11 +542,19 @@ today**, not that ownership is settled. If that dictionary changes, or your plug
531
542
  order on someone else's machine, you cannot predict the result. **Adding the pair to your own repo costs one JSON file.**
532
543
 
533
544
  **What does not count** (documented exemptions — don't "fix" them): `description` of commands and params
534
- (**declaration data** — for contracts and AI, never rendered) · theme/language-pack `label` and `langDefs`
535
- `aliases` (brand names and language self-names, **proper nouns, never translated**) · every path/ID/context-key
536
- field (`entry` / `render` / `path` / `when` / `key` / menu-slot `group`…). The **single source of truth** for the
537
- exemptions is the header of the SDK's `own-dict-coverage` module — **change that when the schema changes**, and
538
- ⛔ never hand-copy a second list here.
545
+ (**declaration data** — for contracts and AI, never rendered) · **language-pack** `label` and `langDefs`
546
+ `aliases` (language self-names such as `English`/`English (US)`, **proper nouns, never translated**) · an icon theme's
547
+ **icon data file** (mappings: `class`/`imagePath`, **no display-name field**, not translated) · every
548
+ path/ID/context-key field (`entry` / `render` / `path` / `when` / `key` / menu `group` slots…).
549
+ ⛔ **An icon theme's `label` is no longer exempt either** (2026-10-01, display path wired up): the shell's
550
+ `app.iconTheme` dropdown **now shows "id + display name"** instead of raw ids only (`IconRegistry.iconThemeEnumOptions`
551
+ pushes `label` as `enumDescriptions`, resolved by the settings page through `t()`) ⇒ that `label` is what users read
552
+ in the dropdown, so `contributes.iconThemes[].label` needs a translation in your own repo (Chinese literal,
553
+ translation in your `i18n/en.json`).
554
+ ⛔ **A theme's `label` is likewise not exempt** (2026-10-01 de-bilingualization): a theme name must follow the UI
555
+ language, so `themes[].label` and the recipe file's `name`/`colorways[].name` all need a translation in your own
556
+ repo (`11 §⑤`). The **single source of truth** for exemptions is the header of the SDK's `own-dict-coverage`
557
+ module — **change that one when you change the schema**, ⛔ never hand-copy a second list here.
539
558
 
540
559
  #### Bucket-key naming advice — **give your keys an owner** (advice, not a requirement)
541
560
 
@@ -45,11 +45,11 @@ theme-myglass/
45
45
  // plugin.json — theme declaration goes through contributes.themes (modeled on VS Code; authoritative schema in plugin.schema.json)
46
46
  {
47
47
  "id": "theme-myglass",
48
- "name": "My Glass Theme",
48
+ "name": "我的玻璃主题",
49
49
  "version": "0.1.0",
50
50
  "contributes": {
51
51
  "themes": [
52
- { "id": "myglass", "label": "My Glass", "uiTheme": "dark", "path": "themes/myglass.json" }
52
+ { "id": "myglass", "label": "我的玻璃", "uiTheme": "dark", "path": "themes/myglass.json" }
53
53
  ]
54
54
  }
55
55
  }
@@ -67,7 +67,7 @@ theme-myglass/
67
67
  // Malformed-input interception: editor IntelliSense + the SDK's validateThemeJson (the same channel for npm projects and the official plugin repo)
68
68
  // Full field table in "themes/02-theme-field-index" and the SDK's theme.schema.json; the runtime parseThemeRecipe toast is the second line of defense
69
69
  {
70
- "id": "myglass", "name": "My Glass", "type": "dark",
70
+ "id": "myglass", "name": "我的玻璃", "type": "dark",
71
71
  "appearance": {
72
72
  "radius": { "md": 10, "lg": 16 },
73
73
  "glass": { "blur": 16, "saturate": 1.3, "tint": "rgba(255,255,255,0.06)", "opacity": 0.9 },
@@ -75,8 +75,8 @@ theme-myglass/
75
75
  "background": { "image": "assets/bg.png", "opacity": 0.85, "mask": 0.3 } // mask = 0-1 brightness coefficient (number); the base color goes through maskColor separately
76
76
  },
77
77
  "colorways": [
78
- { "id": "violet", "name": "Violet", "colors": { "bg-window": "#0E0B16", "accent": "#8B5CF6" } },
79
- { "id": "emerald", "name": "Emerald", "colors": { "bg-window": "#0A1410", "accent": "#34D399" } }
78
+ { "id": "violet", "name": "紫罗兰", "colors": { "bg-window": "#0E0B16", "accent": "#8B5CF6" } },
79
+ { "id": "emerald", "name": "翡翠", "colors": { "bg-window": "#0A1410", "accent": "#34D399" } }
80
80
  ]
81
81
  }
82
82
  ```
@@ -109,7 +109,7 @@ theme-liquid-glass/
109
109
  // themes/liquid-glass.json
110
110
  {
111
111
  "id": "liquid-glass",
112
- "name": "Liquid Glass",
112
+ "name": "液态玻璃",
113
113
  "type": "dark",
114
114
  "appearance": {
115
115
  "radius": { "xs": 2, "sm": 4, "md": 8, "lg": 14, "xl": 20, "2xl": 24 },
@@ -118,9 +118,9 @@ theme-liquid-glass/
118
118
  "background": { "image": "assets/aurora.jpg", "opacity": 1, "mask": "rgba(0,0,0,0.88)" }
119
119
  },
120
120
  "colorways": [
121
- { "id": "aurora", "name": "Aurora Violet", "colors": { "bg-window": "#0E0B16", "accent": "#8B5CF6" } },
122
- { "id": "emerald", "name": "Emerald", "colors": { "bg-window": "#0A1410", "accent": "#34D399" } },
123
- { "id": "ocean", "name": "Deep Ocean", "colors": { "bg-window": "#0B121E", "accent": "#38BDF8" } }
121
+ { "id": "aurora", "name": "极光紫", "colors": { "bg-window": "#0E0B16", "accent": "#8B5CF6" } },
122
+ { "id": "emerald", "name": "翡翠", "colors": { "bg-window": "#0A1410", "accent": "#34D399" } },
123
+ { "id": "ocean", "name": "深海", "colors": { "bg-window": "#0B121E", "accent": "#38BDF8" } }
124
124
  ]
125
125
  }
126
126
  ```
@@ -135,11 +135,41 @@ theme-liquid-glass/
135
135
 
136
136
  > **Sparse and omittable:** the fully-loaded example only means "every domain is written" — missing domains inherit the shell defaults and missing keys within a domain inherit too (§3 sparse override); the less you write, the more stable it is. A pure-color theme = only `colorways` (and can skip even `assets/`).
137
137
 
138
+ ### ⑤ Names and translations (Chinese source + your own dictionary)
139
+
140
+ Three names are **always written as the Chinese source**: `contributes.themes[].label` in `plugin.json`, the recipe
141
+ JSON's top-level `name`, and `colorways[].name`. The Chinese UI shows them as-is; for the English UI the shell runs
142
+ them through `t()` and looks the translation up in **your own repo's dictionary** — the same rule as `app.themeColor`
143
+ (whoever declares it translates it, see [03-contributes-spec](03-contributes-spec.md) §3.9).
144
+
145
+ ```jsonc
146
+ // plugin.json — label is the Chinese source
147
+ { "contributes": { "themes": [{ "id": "my-theme.mint", "label": "薄荷苏打", "path": "themes/mint.json" }],
148
+ "i18n": { "en": "i18n/en.json" } } }
149
+ ```
150
+ ```jsonc
151
+ // themes/mint.json — the recipe name and the colorway names are the Chinese source too
152
+ { "name": "薄荷苏打", "colorways": [{ "id": "my-theme.mint-bubble", "name": "薄荷冰露" }] }
153
+ ```
154
+ ```jsonc
155
+ // i18n/en.json — key = the Chinese source, value = the translation (no zh.json needed: a Chinese key falls back to itself)
156
+ { "薄荷苏打": "Mint Soda", "薄荷冰露": "Mint Frost" }
157
+ ```
158
+
159
+ ⛔ **Never write a bilingual literal** (`"薄荷苏打 Mint Soda"`): the key **is** the displayed text, and when the
160
+ Chinese UI finds no translation for it, it prints the string verbatim ⇒ even the Chinese UI shows a mixed-script
161
+ name. The judge enforces this mechanically: leg ⑧ of `npm run verify` (`@linkdesk/plugin-sdk/own-dict-coverage`) puts
162
+ all three places in scope (`label` **plus** the data file's `name`/`colorways[].name`), and a missing translation goes red on the spot.
163
+
164
+ ⓘ The JSON snippets in this doc keep their name literals in Chinese for exactly this reason — a theme file must
165
+ contain the Chinese source no matter which language this page is written in.
166
+
138
167
  ## 3. Pitfalls
139
168
 
140
169
  | Pitfall | Explanation |
141
170
  |:--|:--|
142
171
  | Recipe json flattened into the plugin root | **Forbidden (§2 ⓪ directory spec)** — always put it in `themes/`; future i18n/README each get their own home |
172
+ | Bilingual names (`"薄荷苏打 Mint Soda"`) | The Chinese UI would show a mixed-script name too — write the **Chinese source** literal; the translation lives in your own `i18n/en.json` (§2 ⑤) |
143
173
  | Writing a top-level `colors` (no `colorways`) | **The old format is deprecated** (decision F) — the engine reads only `colorways[]`; even a single colorway goes in an array with 1 item |
144
174
  | Writing absolute paths | Everything blows up under packaged `file://` — always relative paths + getPluginAssetPath |
145
175
  | Repeating every color | Sparse override = write only the differing keys; unwritten ones inherit `:root`, which is more stable |
@@ -335,7 +335,7 @@ useEffect(() => {
335
335
  {
336
336
  "contributes": {
337
337
  "themes": [
338
- { "id": "my-theme-dark", "label": "My Theme Dark", "uiTheme": "dark", "path": "themes/my-dark.json" }
338
+ { "id": "my-theme-dark", "label": "我的深色主题", "uiTheme": "dark", "path": "themes/my-dark.json" }
339
339
  ]
340
340
  }
341
341
  }
@@ -344,10 +344,17 @@ useEffect(() => {
344
344
  | 字段 | 必需 | 说明 |
345
345
  |------|:--:|------|
346
346
  | `id` | ✅ | 主题 ID |
347
- | `label` | ✅ | 显示名称 |
347
+ | `label` | ✅ | 显示名称——**写中文原文**(中文界面原样显示);英文译名住本仓 `i18n/en.json`(§3.9)。⛔ 不写双语字面量 |
348
348
  | `uiTheme` | ✅ | `"dark"` \| `"light"` \| `"highContrast"` |
349
349
  | `path` | ✅ | 主题定义 JSON 文件路径(`appearance` + `colorways[]`)——**相对插件目录** |
350
350
 
351
+ > **🔥 名字的写法(2026-10-01 用户拍板「我不要双语了」)**:`label`、`path` 指向的配方 JSON 的顶层 `name`、
352
+ > `colorways[].name` **一律写中文原文**——中文界面原样显示,英文界面由壳过 `t()` 显示**本仓字典**里的译名
353
+ > (与 `app.themeColor` 同一条规则:谁的仓谁译文)。⛔ **不要写双语字面量**(`"薄荷苏打 Mint Soda"`)——
354
+ > 中文界面会中英混排,而「名字里自带译名」这条病只有「字面量纯中文 + 译名住字典」治得掉。
355
+ > 判据机械守:`npm run verify` 第 ⑧ 段(`@linkdesk/plugin-sdk/own-dict-coverage`)把这三处**都**纳入判域
356
+ > (`themes[].label` + 配方文件里的 `name`/`colorways[].name`),缺译名当场红。写法与例见 [11-主题制作](11-主题制作.md) §⑤。
357
+
351
358
  声明是 metadata-only;主题颜色数据在加载时异步 fetch。旧格式顶层 `themes` 字段自动归一化(见 `02 §二.1`)。
352
359
 
353
360
  > **🔥 配方 JSON 契约(已随 plugin-sdk 收编)**:`path` 指向的配方文件按 `theme.schema.json` 校验——repo 内 = `public/schemas/theme.schema.json`(`npm run check` 链 `check-theme-schema.mjs`,格式错当场红灯 exit 1 不静默);npm 作者 = 随 `@linkdesk/plugin-sdk` 分发的 `schemas/theme.schema.json` + SDK `validateThemeJson`(同一 schema 文件,规则永不漂移)。运行时 `parseThemeRecipe` toast 是第二道防线。主题文件建议首行 `"$schema"` 引 schema 拿编辑器 IntelliSense(npm 路径见 [11-主题制作](11-主题制作.md) §②)。
@@ -444,7 +451,7 @@ node_modules/@linkdesk/plugin-sdk/schemas/host-reserved.json
444
451
 
445
452
  > **🔥 mappings JSON 契约(立——icon-theme.schema.json 重写对齐引擎 normalizeIconThemeMappings)**:`path` 指向的 mappings 文件按 `icon-theme.schema.json` 校验——repo 内 = `public/schemas/icon-theme.schema.json`(`npm run check` 链 `check-theme-schema.mjs` 兼扫 `contributes.iconThemes`);npm 作者 = 随 `@linkdesk/plugin-sdk` 分发的 `schemas/icon-theme.schema.json` + SDK `validateIconThemeJson`(同一 schema 文件,规则永不漂移)。运行时解析失败 warn/toast 是第二道防线。文件建议首行 `"$schema"` 引 schema 拿编辑器 IntelliSense。
446
453
 
447
- **id 命名规则:** 图标主题 id 只判**一条**——**不得**用宿主兜底 id `default`(判红:该 id 注册不上 + 一条 `console.error`)。**不判**"带不带本仓前缀":图标主题 id 会**原样显示在设置页**(选择器直接渲染 id 文本),给它改名 = 用户可见文字变化 ⇒ 本轮不动。想让它在下拉里好看,改的是 `label`(显示名),不是 id。
454
+ **id 命名规则:** 图标主题 id 只判**一条**——**不得**用宿主兜底 id `default`(判红:该 id 注册不上 + 一条 `console.error`)。**不判**"带不带本仓前缀":图标主题 id 是**注册键**(用户选中的值存在 `app.iconTheme` 里),改名 = 要迁移盘上旧值,收益只落在 id 本身 ⇒ 本轮不动。⚠️ **2026-10-01 更正**:下拉**已改为渲染 `label`**(显示面打通,见下文豁免段)——想让它在下拉里好看,改的是 `label` 的**译名**(本仓字典),⛔ 不是改 id。
448
455
 
449
456
  ```
450
457
  → "appearanceIconThemeIds": ["default"] ← 图标主题栏(只有这一条)
@@ -494,6 +501,7 @@ node_modules/@linkdesk/plugin-sdk/schemas/host-reserved.json
494
501
  - `contributes.i18n` 的 key = 语言代码,value = JSON 翻译文件路径(key = 中文原文,value = 译文)。**不需要 zh.json**——中文 key 自带兜底。
495
502
  - 翻译文件经 `fetchPluginDataFile` 加载(绕开 Vite glob 缓存——新装插件目录的 JSON 实时发现)。
496
503
  - 插件文字铁律:**所有 UI 文字走 `t()`**,i18n key = 中文原文(`05 §6`)。
504
+ - 🔴 **字面量只写原文,⛔ 不写双语**(2026-10-01 用户拍板「我不要双语了」):字面量写成 `"薄荷苏打 Mint Soda"` 时,**中文界面也显中英混排**(key 即显示文本,取不到译文就原样输出)。正确写法 = 字面量 `"薄荷苏打"` + 本仓字典 `{ "薄荷苏打": "Mint Soda" }`——中文界面回退原文、英文界面取译名。判据不判「有没有拉丁字母」(中文名里合法含专名,如「Cascadia Mono 终端」,机械判必假红),把关的是**「名字必须住字典」**:要么去掉英文,要么在字典里自我翻译,两条路都得本仓动手。
497
505
 
498
506
  #### 🔴 谁的仓谁译文——自有文案的译名必须住本仓(**规则,不是建议**)
499
507
 
@@ -525,8 +533,15 @@ node_modules/@linkdesk/plugin-sdk/schemas/host-reserved.json
525
533
  或者你的插件在别人的机器上碰巧换了加载顺序,你就无从预料。**补进自己仓只多一份 JSON。**
526
534
 
527
535
  **哪些不算**(有据的豁免,别乱补):命令与参数的 `description`(**声明数据**——给契约与 AI 看,不进 UI)·
528
- 主题/语言包的 `label` 与 `langDefs` 的 `aliases`(品牌名与语言自称,**专名不译**)· 一切路径/ID/上下文键字段
529
- (`entry` / `render` / `path` / `when` / `key` / 菜单槽位 `group`…)。豁免的**唯一真相源**是 SDK 的
536
+ **语言包**的 `label` 与 `langDefs` 的 `aliases`(语言自称/`English`/`English (US)` 这种自称形式,**专名不译**)·
537
+ 图标主题的**图标数据文件**(mappings:`class`/`imagePath`,**没有显示名字段**,不译)· 一切路径/ID/上下文键字段
538
+ (`entry` / `render` / `path` / `when` / `key` / 菜单槽位 `group`…)。
539
+ ⛔ **图标主题的 `label` 也不再豁免**(2026-10-01 显示面打通):壳侧 `app.iconTheme` 下拉**已从「只列原始 id」改为
540
+ 「id + 显示名」**(`IconRegistry.iconThemeEnumOptions` 把 `label` 当 `enumDescriptions` 推给设置页,设置页
541
+ `t(enumDescriptions[i])` 解析)⇒ 那条 `label` 就是用户在下拉里读到的字,`contributes.iconThemes[].label`
542
+ 要有本仓译名(字面量纯中文、译名进本仓 `i18n/en.json`)。
543
+ ⛔ **主题的 `label` 同样不豁免**(2026-10-01 去双语化):主题名要跟着界面语言走,故 `themes[].label` 与配方
544
+ 文件里的 `name`/`colorways[].name` 都要有本仓译名(`11 §⑤`)。豁免的**唯一真相源**是 SDK 的
530
545
  `own-dict-coverage` 模块头注——**改 schema 时同笔改那里**,⛔ 别在这里手抄第二份清单。
531
546
 
532
547
  #### 桶键命名建议——**给键加上归属**(建议,不是强制)
@@ -49,7 +49,7 @@ theme-myglass/
49
49
  "version": "0.1.0",
50
50
  "contributes": {
51
51
  "themes": [
52
- { "id": "myglass", "label": "My Glass", "uiTheme": "dark", "path": "themes/myglass.json" }
52
+ { "id": "myglass", "label": "我的玻璃", "uiTheme": "dark", "path": "themes/myglass.json" }
53
53
  ]
54
54
  }
55
55
  }
@@ -66,7 +66,7 @@ theme-myglass/
66
66
  // 格式错拦截:编辑器 IntelliSense + SDK validateThemeJson(npm 工程与官方插件仓同一条通道)
67
67
  // 全量字段见「主题/02-主题字段速查」与随 SDK 的 theme.schema.json;运行时 parseThemeRecipe toast 是第二道防线
68
68
  {
69
- "id": "myglass", "name": "My Glass", "type": "dark",
69
+ "id": "myglass", "name": "我的玻璃", "type": "dark",
70
70
  "appearance": {
71
71
  "radius": { "md": 10, "lg": 16 },
72
72
  "glass": { "blur": 16, "saturate": 1.3, "tint": "rgba(255,255,255,0.06)", "opacity": 0.9 },
@@ -134,11 +134,36 @@ theme-liquid-glass/
134
134
 
135
135
  > **稀疏可省:** 满配只是「所有域都写了」——缺的域继承壳默认、域内缺的键继承(§3 稀疏覆盖),写越少越稳。纯配色主题 = 只写 colorways(连 `assets/` 都可以没有)。
136
136
 
137
+ ### ⑤ 名字与译名(中文原文 + 本仓字典)
138
+
139
+ 三处名字**一律写中文原文**:`plugin.json` 的 `contributes.themes[].label`、配方 JSON 的顶层 `name`、
140
+ `colorways[].name`。中文界面原样显示;英文界面由壳过 `t()` 取**本仓字典**里的译名——与 `app.themeColor`
141
+ 同一条规则(谁的仓谁译文,见 [03-contributes规范](03-插件contributes规范.md) §3.9)。
142
+
143
+ ```jsonc
144
+ // plugin.json —— label 是中文原文
145
+ { "contributes": { "themes": [{ "id": "my-theme.mint", "label": "薄荷苏打", "path": "themes/mint.json" }],
146
+ "i18n": { "en": "i18n/en.json" } } }
147
+ ```
148
+ ```jsonc
149
+ // themes/mint.json —— 配方名与配色名同样是中文原文
150
+ { "name": "薄荷苏打", "colorways": [{ "id": "my-theme.mint-bubble", "name": "薄荷冰露" }] }
151
+ ```
152
+ ```jsonc
153
+ // i18n/en.json —— key = 中文原文,value = 译名(不需要 zh.json:中文 key 自带兜底)
154
+ { "薄荷苏打": "Mint Soda", "薄荷冰露": "Mint Frost" }
155
+ ```
156
+
157
+ ⛔ **不要写双语字面量**(`"薄荷苏打 Mint Soda"`):key **就是**显示文本,中文界面取不到译文即原样输出 ⇒
158
+ 中文界面也中英混排。判据机械守:`npm run verify` 第 ⑧ 段(`@linkdesk/plugin-sdk/own-dict-coverage`)把这三处
159
+ **都**纳入判域(`label` + 数据文件的 `name`/`colorways[].name`),缺译名当场红。
160
+
137
161
  ## 3. 避坑
138
162
 
139
163
  | 坑 | 说明 |
140
164
  |:--|:--|
141
165
  | 配方 json 平铺在插件根目录 | **禁(§2 ⓪ 目录规范)**——一律放 `themes/`;未来 i18n/README 各归其位 |
166
+ | 名字写双语(`"薄荷苏打 Mint Soda"`) | 中文界面会中英混排——字面量写**中文原文**,译名住本仓 `i18n/en.json`(§2 ⑤) |
142
167
  | 写顶层 `colors`(无 `colorways`) | **旧格式已弃**(决策 F)——引擎只读 `colorways[]`;单配色也写数组 1 项 |
143
168
  | 写绝对路径 | 打包后 `file://` 全炸——一律相对路径 + getPluginAssetPath |
144
169
  | 重复写全部颜色 | 稀疏覆盖 = 只写差异键,未写继承 `:root`,更稳 |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@linkdesk/plugin-docs",
3
- "version": "0.1.50",
3
+ "version": "0.1.51",
4
4
  "description": "LinkDesk 插件作者文档(离线包)——作者面文档树的发布产物(英文 `docs/03-plugin-authoring` 在包根、中文 `docs/03-插件制造` 在 `zh/`):从零学会做一个插件(导览 / 三档动线 / 区域地图 / 组件速查 / 主题 / API 入口)。",
5
5
  "type": "module",
6
6
  "files": [