@linkdesk/plugin-docs 0.1.46 → 0.1.47
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.
|
@@ -497,15 +497,55 @@ Plugin A contributes, plugin B references (`"icon": "stm32-chip"` + `"iconSource
|
|
|
497
497
|
- Translation files are loaded through `fetchPluginDataFile` (bypassing the Vite glob cache — JSON in a newly installed plugin directory is discovered in real time).
|
|
498
498
|
- The plugin text iron rule: **all UI text goes through `t()`**, and the i18n key is the original Chinese text (`05 §6`).
|
|
499
499
|
|
|
500
|
+
#### 🔴 Whoever declares it translates it — your own text must be translated in your own repo (**a rule, not advice**)
|
|
501
|
+
|
|
502
|
+
**In one line**: **the text you declare is the text you translate.** Anything your plugin declares that is rendered
|
|
503
|
+
as UI text (`name` / `description` in `plugin.json`, view and container titles, command titles, configuration
|
|
504
|
+
**group names / section descriptions / enum display names**, status-bar text, menu and title-bar labels,
|
|
505
|
+
`titleActions` buttons and their dropdown items…), its translation **must live in your own repo's
|
|
506
|
+
`i18n/<lang>.json`** and be declared in `contributes.i18n`.
|
|
507
|
+
|
|
508
|
+
```jsonc
|
|
509
|
+
// plugin.json
|
|
510
|
+
{ "contributes": { "i18n": { "en": "i18n/en.json" } } }
|
|
511
|
+
```
|
|
512
|
+
```jsonc
|
|
513
|
+
// i18n/en.json — key = the original Chinese text you declared, value = the translation
|
|
514
|
+
{ "设置插件": "Settings", "打开方式": "Opening mode" }
|
|
515
|
+
```
|
|
516
|
+
|
|
517
|
+
**Why "anywhere is fine" is not fine**: when the declaration lives in your repo and the translation lives in
|
|
518
|
+
**another repo** (for example `lang-defaults` in the shell repo), **the two can never keep up** — you add a
|
|
519
|
+
declaration here and nobody over there knows; cross-repo sync relies on someone remembering, and nobody does.
|
|
520
|
+
(This rule comes from a real miss: the settings plugin's own declaration items stayed Chinese in the English UI.)
|
|
521
|
+
|
|
522
|
+
**Self-check and severity** (leg ⑧ of `npm run verify`; the judge itself lives in the SDK, your repo only calls it):
|
|
523
|
+
|
|
524
|
+
| Object | Severity | Meaning |
|
|
525
|
+
|------|:--:|------|
|
|
526
|
+
| A renderable Chinese string you declared in `plugin.json` has no translation in your own repo | 🔴 **red** | Whoever holds the declaration owns the translation — another repo cannot save it |
|
|
527
|
+
| A key from `t("original Chinese")` in your `src/**` is missing from your own dictionary | ⚠️ **yellow** | The app-level dictionary (`lang-defaults`) is a **legitimate provider**, but ownership is not yours |
|
|
528
|
+
|
|
529
|
+
**⛔ Do not read "it's already in the app-level dictionary" as "nothing to do"** — that means **the UI looks fine
|
|
530
|
+
today**, not that ownership is settled. If that dictionary changes, or your plugin happens to load in a different
|
|
531
|
+
order on someone else's machine, you cannot predict the result. **Adding the pair to your own repo costs one JSON file.**
|
|
532
|
+
|
|
533
|
+
**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.
|
|
539
|
+
|
|
500
540
|
#### Bucket-key naming advice — **give your keys an owner** (advice, not a requirement)
|
|
501
541
|
|
|
502
542
|
Your translation file is **one flat layer of keys**, and everyone writes into the same table: every plugin's keys, the shell's own keys, and the `lang-defaults` language pack's keys **live in one dictionary**. Within a language, the later registrant overwrites the earlier one — **and until now there was no notice at all**.
|
|
503
543
|
|
|
504
544
|
**Advice**: give your keys an owner-bearing name, e.g. `serial-monitor.打开端口` instead of `打开端口`. Then even an accidental name clash is nobody else's business.
|
|
505
545
|
|
|
506
|
-
🔴 **Why this is advice and not a requirement**: **
|
|
546
|
+
🔴 **Why this is advice and not a requirement**: **a key may legitimately live in the app-level dictionary** (the rule above governs **ownership**, not **reachability**). Inside your plugin repo there is only your own `i18n/*.json` — **you cannot see the shell's dictionary, nor any other plugin** — so "your key collided with someone" is **never decidable from your own repo**. Making it a blocker means guaranteed false positives, and false positives invalidate the rules that should really block. ⇒ **It is a yellow light, not a red one.**
|
|
507
547
|
|
|
508
|
-
**How much overlap actually exists** (told plainly, not exaggerated — the counts below are a **measurement**, taken when the roster was 18 official plugins, not a live figure): those plugins declared **414 keys**, **65 of which overlap** the `lang-defaults` keys, and **3 of those already have divergent translations** — for example `命令`, where the shell says `Command` while `serial-monitor` says `Commands`. **When both are written into the same dictionary, which one the user actually sees depends on plugin load order.**
|
|
548
|
+
**How much overlap actually exists** (told plainly, not exaggerated — the counts below are a **measurement**, taken when the roster was 18 official plugins, not a live figure): those plugins declared **414 keys**, **65 of which overlap** the `lang-defaults` keys, and **3 of those already have divergent translations** — for example `命令`, where the shell says `Command` while `serial-monitor` says `Commands`. **When both are written into the same dictionary, which one the user actually sees depends on plugin load order.** ⚠️ The cleanup for the ownership rule above is **additive** (your own dictionary gets the pair first, the old app-level entries **stay** for now — other plugins and the shell still reference them), so this overlap figure **does not drop to zero just because your repo grew a dictionary**.
|
|
509
549
|
|
|
510
550
|
⚠️ **Runtime behaviour**: when an overwrite happens the shell emits a `console.warn` naming the **key + language + writer**:
|
|
511
551
|
|
|
@@ -515,6 +555,8 @@ Your translation file is **one flat layer of keys**, and everyone writes into th
|
|
|
515
555
|
|
|
516
556
|
**It is a notice, not a blocker** — the value is still written (the later registrant wins, exactly as today); the collision merely becomes traceable. The wording says only "already has this key, source unknown": the shell **can report who overwrote, but cannot report who owned it originally**, and it does not claim what it cannot do.
|
|
517
557
|
|
|
558
|
+
⚠️ **Identical values stay silent** (since 2026-09-30): when both sides write the **same pair** (byte-identical value), nothing is reported — there is zero visible difference, and reporting it would drown out real divergence. During the cleanup for the ownership rule above, "own dictionary + app-level dictionary holding the same pair" is the normal state, so only a **differing value** is a real problem.
|
|
559
|
+
|
|
518
560
|
🔴 **When NOT prefixing is legitimate**: **extensions** such as `.py` / `.ts`, and **language codes** such as `zh` / `en` — they are not "unowned", they **should never have an owner**, and prefixing them would be a semantic error.
|
|
519
561
|
|
|
520
562
|
### 3.10 `contributes.titleBar` — top bar buttons
|
|
@@ -247,7 +247,7 @@ Multi-theme package:
|
|
|
247
247
|
| `minAppVersion` | `string` | Minimum app version requirement |
|
|
248
248
|
| `docs` | `string` | Bundled documentation path (for resource plugins) |
|
|
249
249
|
| `cardDocMap` | `object` | Card ID → documentation anchor mapping |
|
|
250
|
-
| `i18n` | `object` | Plugin-bundled translations `{ "en": "i18n/en.json", "ja": "i18n/ja.json" }` — key = the plugin UI's source text (the author's native language is recommended). It lives under `contributes.i18n`, not at the top level |
|
|
250
|
+
| `i18n` | `object` | Plugin-bundled translations `{ "en": "i18n/en.json", "ja": "i18n/ja.json" }` — key = the plugin UI's source text (the author's native language is recommended). It lives under `contributes.i18n`, not at the top level. 🔴 **Text your plugin declares must be translated in your own repo** (whoever declares it translates it — see `03 §3.9`) |
|
|
251
251
|
| `cssVars` | `object` | Plugin-defined CSS variables `{ "--name": { "dark": "#fff", "light": "#000" } }` |
|
|
252
252
|
| `permissions` | `string[]` | Permission declarations `["serial", "filesystem", "network"]` (enabled in Phase 5+) |
|
|
253
253
|
|
|
@@ -495,15 +495,49 @@ node_modules/@linkdesk/plugin-sdk/schemas/host-reserved.json
|
|
|
495
495
|
- 翻译文件经 `fetchPluginDataFile` 加载(绕开 Vite glob 缓存——新装插件目录的 JSON 实时发现)。
|
|
496
496
|
- 插件文字铁律:**所有 UI 文字走 `t()`**,i18n key = 中文原文(`05 §6`)。
|
|
497
497
|
|
|
498
|
+
#### 🔴 谁的仓谁译文——自有文案的译名必须住本仓(**规则,不是建议**)
|
|
499
|
+
|
|
500
|
+
**一句话**:**你声明的文案,译名就归你。** 插件自己声明、会被渲染成界面文字的东西(`plugin.json` 的 `name` /
|
|
501
|
+
`description`、视图与容器标题、命令标题、配置**分组名/分节说明/枚举显示名**、状态栏文本、菜单与标题栏标签、
|
|
502
|
+
`titleActions` 按钮与下拉项…),译名**必须写在你自己仓的 `i18n/<lang>.json` 里**并在 `contributes.i18n` 声明。
|
|
503
|
+
|
|
504
|
+
```jsonc
|
|
505
|
+
// plugin.json
|
|
506
|
+
{ "contributes": { "i18n": { "en": "i18n/en.json" } } }
|
|
507
|
+
```
|
|
508
|
+
```jsonc
|
|
509
|
+
// i18n/en.json——key = 中文原文(你声明的那些字),value = 译文
|
|
510
|
+
{ "设置插件": "Settings", "打开方式": "Opening mode" }
|
|
511
|
+
```
|
|
512
|
+
|
|
513
|
+
**为什么不是「写哪儿都行」**:声明在本仓、译名住在**另一个仓**(例如壳仓的 `lang-defaults`)时,
|
|
514
|
+
**两边永远追不上**——你在这边加一条声明,那边没有人知道;跨仓同步只能靠人记,人一定记不住。
|
|
515
|
+
(这条规则就来自一次真实漏翻:设置插件在设置页里的声明项,英文界面下一直是中文。)
|
|
516
|
+
|
|
517
|
+
**自检 + 严重度**(`npm run verify` 的 ⑧ 段;判据本体在 SDK,本仓调它):
|
|
518
|
+
|
|
519
|
+
| 对象 | 严重度 | 说明 |
|
|
520
|
+
|------|:--:|------|
|
|
521
|
+
| 你在 `plugin.json` 里声明的可渲染中文串没有本仓译名 | 🔴 **红** | 声明在谁手里译名就归谁——跨仓救不了 |
|
|
522
|
+
| 你 `src/**` 里 `t("中文原文")` 的键不在本仓字典 | ⚠️ **黄** | 应用级字典(`lang-defaults`)是**合法提供方**,只是归属不在你手上 |
|
|
523
|
+
|
|
524
|
+
**⛔ 别把「应用级字典里有」当成「不用补」**——那是**今天界面不错**,不是归属落位;哪天那本字典改了、
|
|
525
|
+
或者你的插件在别人的机器上碰巧换了加载顺序,你就无从预料。**补进自己仓只多一份 JSON。**
|
|
526
|
+
|
|
527
|
+
**哪些不算**(有据的豁免,别乱补):命令与参数的 `description`(**声明数据**——给契约与 AI 看,不进 UI)·
|
|
528
|
+
主题/语言包的 `label` 与 `langDefs` 的 `aliases`(品牌名与语言自称,**专名不译**)· 一切路径/ID/上下文键字段
|
|
529
|
+
(`entry` / `render` / `path` / `when` / `key` / 菜单槽位 `group`…)。豁免的**唯一真相源**是 SDK 的
|
|
530
|
+
`own-dict-coverage` 模块头注——**改 schema 时同笔改那里**,⛔ 别在这里手抄第二份清单。
|
|
531
|
+
|
|
498
532
|
#### 桶键命名建议——**给键加上归属**(建议,不是强制)
|
|
499
533
|
|
|
500
534
|
你的翻译文件是**平铺的一层键**,谁都往同一张表里写:所有插件的键、宿主自己的键、`lang-defaults` 语言包的键,**住在同一本字典里**。同一语言下后注册者覆盖先者,**且此前没有任何提示**。
|
|
501
535
|
|
|
502
536
|
**建议**:给自己的键起带归属的名字,例如 `serial-monitor.打开端口` 而不是 `打开端口`。这样即使名字碰巧相同也与别人无关。
|
|
503
537
|
|
|
504
|
-
🔴
|
|
538
|
+
🔴 **为什么这是建议而不是强制**:**键可以合法住在应用级字典**(§3.9 上一条规则管的是**归属**,不是**能不能查得到**)。插件仓里只有你自己的 `i18n/*.json`——**看不到宿主的字典,也看不到其余插件**,所以「你的键撞了别人」在你自己仓里**永远判不出来**。把它做成拦截 = 必然误报,而误报会让真正该拦的规则失效。⇒ **它是黄灯,不是红灯。**
|
|
505
539
|
|
|
506
|
-
**真实存在多少重合**(如实告诉你,不夸大——下面的数是**一次测量**,取当时官方 18 只的名单,不是活读数):官方插件声明了 **414 个键**,其中与 `lang-defaults` 的键 **65 条重合**,而这 65 条里 **3 条译文已经不一致**——例如 `命令`,宿主给的是 `Command`,而 `serial-monitor` 给的是 `Commands`。**两条都写进同一本字典时,用户看到的究竟是哪一条,取决于插件加载顺序。**
|
|
540
|
+
**真实存在多少重合**(如实告诉你,不夸大——下面的数是**一次测量**,取当时官方 18 只的名单,不是活读数):官方插件声明了 **414 个键**,其中与 `lang-defaults` 的键 **65 条重合**,而这 65 条里 **3 条译文已经不一致**——例如 `命令`,宿主给的是 `Command`,而 `serial-monitor` 给的是 `Commands`。**两条都写进同一本字典时,用户看到的究竟是哪一条,取决于插件加载顺序。** ⚠️ 上面那条归属规则的清扫是**加法**(自有字典先补上,应用级字典里的旧条目**暂留**——别的插件与宿主仍在引用),所以这份重合读数**不会因为你的仓补了字典就立刻归零**。
|
|
507
541
|
|
|
508
542
|
⚠️ **运行时行为**:发生覆盖时宿主会 `console.warn` 出声,点明**键名 + 语言 + 写入者**:
|
|
509
543
|
|
|
@@ -513,6 +547,8 @@ node_modules/@linkdesk/plugin-sdk/schemas/host-reserved.json
|
|
|
513
547
|
|
|
514
548
|
**它是提示,不是拦截**——值照常写入(后注册者胜,语义与今天完全一致),只是这条碰撞从此可查。措辞只称「已有同键,来源未知」:**宿主报得出「谁覆盖了」,报不出「原本属于谁」**,不宣称做不到的事。
|
|
515
549
|
|
|
550
|
+
⚠️ **同值不出声**(2026-09-30 起):两处写的是**同一对映射**(值一模一样)时**不报**——界面零差别,报它只会把真分歧淹掉。上面那条归属规则的清扫期,「自有字典 + 应用级字典并存同一对映射」正是常态,所以只有**值不同**才是真问题。
|
|
551
|
+
|
|
516
552
|
🔴 **不加前缀的合法情形**:`.py` / `.ts` 这类**扩展名**、`zh` / `en` 这类**语言码**——它们不是「没主」,是**本就不该有主**,加前缀反而语义错误。
|
|
517
553
|
|
|
518
554
|
### 3.10 `contributes.titleBar`——顶栏按钮
|
|
@@ -247,7 +247,7 @@ my-plugin/
|
|
|
247
247
|
| `minAppVersion` | `string` | 最低软件版本要求 |
|
|
248
248
|
| `docs` | `string` | 附带文档路径(资源插件联动) |
|
|
249
249
|
| `cardDocMap` | `object` | 卡片 ID → 文档锚点映射 |
|
|
250
|
-
| `i18n` | `object` | 插件自带翻译 `{ "en": "i18n/en.json", "ja": "i18n/ja.json" }`——key=插件 UI 原文(建议作者母语)。放在 `contributes.i18n`
|
|
250
|
+
| `i18n` | `object` | 插件自带翻译 `{ "en": "i18n/en.json", "ja": "i18n/ja.json" }`——key=插件 UI 原文(建议作者母语)。放在 `contributes.i18n` 下,非顶层。🔴 **本插件自己声明的可渲染文案,译名必须住本仓**(「谁的仓谁译文」——规则与判据见 `03 §3.9`) |
|
|
251
251
|
| `cssVars` | `object` | 插件自定义 CSS 变量 `{ "--name": { "dark": "#fff", "light": "#000" } }` |
|
|
252
252
|
| `permissions` | `string[]` | 权限声明 `["serial", "filesystem", "network"]`(Phase 5+ 启用) |
|
|
253
253
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@linkdesk/plugin-docs",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.47",
|
|
4
4
|
"description": "LinkDesk 插件作者文档(离线包)——作者面文档树的发布产物(英文 `docs/03-plugin-authoring` 在包根、中文 `docs/03-插件制造` 在 `zh/`):从零学会做一个插件(导览 / 三档动线 / 区域地图 / 组件速查 / 主题 / API 入口)。",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"files": [
|