@ruoyang/dsh-plugin-deepseek-balance 1.0.0 → 1.0.2

package/README.md

@@ -14,6 +14,7 @@ calls.
 | Badge text | total balance in the primary currency, e.g. `¥4.94` |
 | Hover panel | per-currency totals, granted vs topped-up split, whether the account is callable, and the query time |
 | Interaction | click to refresh, drag to reposition, automatic refresh every 60 seconds |
+| Language | every label comes from this plugin's own locale namespace, so the badge follows the UI language (English / Chinese) |
 
 The badge itself is a pill pinned to the lower-right corner; drag it anywhere and it stays there for
 the session.
@@ -43,6 +44,20 @@ In the Web UI: **Settings → Plugins**, then install by the package name above.
 Through an agent session, the equivalent is the `plugin_manager` tool with
 `action: install_bundle` and that package name as `target`.
 
+### If you install through a registry mirror
+
+`registry.npmmirror.com` and other read-only mirrors lag behind npmjs.org, and a package they have
+not synced yet answers **404** — which looks exactly like "no such package". If your npm or pnpm is
+pointed at a mirror (common on machines set up for fast installs), either wait for the sync or send
+this scope to the official registry:
+
+```sh
+npm config set @ruoyang:registry https://registry.npmjs.org/
+```
+
+A scope key is a different setting from `registry`, so it also survives an inherited
+`npm_config_registry` environment variable, which outranks every `.npmrc`.
+
 A new bundle activates immediately; if the badge does not appear, reload the page once so the
 browser picks up the new client module.
 
@@ -88,9 +103,18 @@ A 404 on that path means the row did not mount — check that the bundle is enab
 
 ## Known limitations
 
-- Visible badge text is currently Chinese only; it does not yet go through the Client locale service,
-  so an English UI still shows Chinese labels in the hover panel.
 - The badge position resets on page reload; it is not persisted.
+- Only the two languages the harness ships (English, Chinese) have dictionaries; a third language
+  falls back to the harness's own chain and then to the key, so add a dictionary before adding a
+  language.
+
+## Language
+
+Strings live in the plugin's own locale namespace and reach the component through the `t` seat the
+slot framework injects for a registration that names a `locale` namespace, so switching
+**Settings → General → Language** re-words the badge live. Host-side failures arrive as a
+machine-readable `code` that the badge translates; an unrecognised code falls back to the host's own
+message so a novel failure stays legible.
 
 ## 中文
 
@@ -125,8 +149,10 @@ curl "http://127.0.0.1:3080/deepseek-balance/api?force=1"  # 绕过宿主半 20
 返回 `NO_KEY` = 没配密钥，`HTTP_401` = 密钥被拒，`TRANSPORT` = 宿主机连不上
 `api.deepseek.com`；404 = 行没挂上，去 **设置 → 插件** 看是否启用。
 
-**已知限制**：徽标内的可见文字目前是硬编码中文，还没接 Client locale 服务，所以英文界面下悬停
-面板仍是中文；徽标位置刷新页面后重置。
+**已知限制**：徽标位置在刷新页面后重置（不做持久化）；内置字典只有 harness 自带的两种语言
+（中/英），加第三种语言前需要先补字典。
+
+徽标文字走本插件自己的 locale 命名空间，**设置 → 通用 → 语言** 切换后会实时改文案。
 
 ## Releasing (maintainer)
 

package/client.js

@@ -10,8 +10,14 @@
  * build step is involved. `id` must equal the package name. React comes from the
  * browser module table via `require`.
  *
- * The factory itself stays side-effect free: the stylesheet, the interval and the
- * slot registration are all created inside `apply` and owned by that fiber.
+ * Every visible string lives in this plugin's own locale namespace and reaches
+ * the component through the `t` seat the slot framework injects for a
+ * registration that names a `locale` namespace, so the badge follows the active
+ * language instead of being Chinese-only.
+ *
+ * The factory itself stays side-effect free: the stylesheet, the dictionaries,
+ * the interval and the slot registration are all created inside `apply` and
+ * owned by that fiber.
  */
 window.__ModuleLoader__.load({
   id: '@ruoyang/dsh-plugin-deepseek-balance',
@@ -26,6 +32,72 @@ window.__ModuleLoader__.load({
     const SYMBOLS = { CNY: '¥', USD: '$' }
     /** Id of the one style node this fiber owns. */
     const STYLE_ID = 'dsh-balance-styles'
+    /**
+     * Locale namespace this plugin owns. It is also the namespace named on the
+     * slot registration, which is what makes the framework inject `t`.
+     */
+    const NS = 'deepseek-balance'
+
+    /**
+     * Dictionaries for every built-in locale. Registration requires the complete
+     * set, and both dictionaries carry the same keys.
+     */
+    const DICTS = {
+      en: {
+        'pill.loading': 'Balance …',
+        'pill.unavailable': 'Balance unavailable',
+        'pill.title': 'DeepSeek balance · click to refresh · drag to move',
+        'panel.totalIn': '{currency} total',
+        'panel.grantSplit': '  granted / topped up',
+        'panel.balance': 'Balance',
+        'panel.noData': 'no data',
+        'panel.callable': 'Callable',
+        'panel.yes': 'yes',
+        'panel.no': 'no',
+        'panel.updated': 'Updated',
+        'panel.state': 'State',
+        'panel.querying': 'Querying …',
+        'panel.error': 'Error',
+        'panel.credential': 'Credential',
+        'hint': 'Click to refresh · drag to move',
+        'error.fallback': 'Balance temporarily unavailable',
+        'error.NO_KEY': 'No DEEPSEEK_API_KEY credential — configure it under Settings → Models',
+        'error.TRANSPORT': 'The host could not reach api.deepseek.com',
+        'error.BAD_JSON': 'The balance response was not valid JSON',
+        'error.TIMEOUT': 'The balance query timed out',
+        'error.NO_OUTPUT': 'The balance query returned nothing parseable',
+        'error.HTTP_401': 'The API key was rejected',
+        'error.HTTP_403': 'This API key is not permitted',
+        'error.HTTP_429': 'Rate limited — try again shortly',
+      },
+      zh: {
+        'pill.loading': '余额 …',
+        'pill.unavailable': '余额不可用',
+        'pill.title': 'DeepSeek 余额 · 点击刷新 · 拖动移动',
+        'panel.totalIn': '{currency} 总余额',
+        'panel.grantSplit': '  赠金 / 充值',
+        'panel.balance': '余额',
+        'panel.noData': '无数据',
+        'panel.callable': '可调用',
+        'panel.yes': '是',
+        'panel.no': '否',
+        'panel.updated': '更新于',
+        'panel.state': '状态',
+        'panel.querying': '查询中 …',
+        'panel.error': '错误',
+        'panel.credential': '凭据',
+        'hint': '点击刷新 · 按住拖动可移动位置',
+        'error.fallback': '余额暂不可用',
+        'error.NO_KEY': '未找到 DEEPSEEK_API_KEY 凭据 —— 请在 设置 → Models 里配置',
+        'error.TRANSPORT': '宿主机连不上 api.deepseek.com',
+        'error.BAD_JSON': '余额响应不是合法 JSON',
+        'error.TIMEOUT': '余额查询超时',
+        'error.NO_OUTPUT': '余额查询没有返回可解析的结果',
+        'error.HTTP_401': 'API key 被拒绝',
+        'error.HTTP_403': '这个 API key 没有权限',
+        'error.HTTP_429': '被限流了 —— 稍后再试',
+      },
+    }
 
     const CSS = [
       '.dsh-balance-root{position:fixed;z-index:60;pointer-events:auto;user-select:none;',
@@ -92,6 +164,44 @@ window.__ModuleLoader__.load({
       return pad(date.getHours()) + ':' + pad(date.getMinutes()) + ':' + pad(date.getSeconds())
     }
 
+    /**
+     * Stand-in used only when the slot framework injects no `t` seat.
+     *
+     * The framework throws rather than omitting the seat for a registration that
+     * names a locale namespace, so this is a guard against a future change on a
+     * harness this plugin deliberately declares no version dependency on: a
+     * missing seat degrades the wording instead of blanking the badge.
+     */
+    function fallbackTranslate(key) {
+      return DICTS.zh[key] !== undefined ? DICTS.zh[key] : key
+    }
+
+    /** Take the injected translate seat, falling back when it is absent. */
+    function translatorOf(props) {
+      if (props !== null && typeof props === 'object' && typeof props.t === 'function') return props.t
+      return fallbackTranslate
+    }
+
+    /**
+     * Wording for a failed snapshot.
+     *
+     * The host half already answers a machine-readable `code`; translating that
+     * keeps the badge in the active language, while an unrecognised code falls
+     * back to the host's own message so a novel failure is still legible. An
+     * unknown key resolves to the key itself, which is how the miss is detected.
+     */
+    function failureText(t, payload) {
+      if (payload !== null && typeof payload === 'object' && typeof payload.code === 'string' && payload.code !== '') {
+        const key = 'error.' + payload.code
+        const text = t(key)
+        if (text !== key) return text
+      }
+      if (payload !== null && typeof payload === 'object' && typeof payload.message === 'string' && payload.message !== '') {
+        return payload.message
+      }
+      return t('error.fallback')
+    }
+
     /** One key/value line of the hover panel. */
     function row(key, value, extraClass) {
       return React.createElement(
@@ -111,34 +221,33 @@ window.__ModuleLoader__.load({
      * and freshness. The failure branch names the credential so a missing key is
      * obvious without opening logs.
      */
-    function panelRows(data, failure, phase) {
+    function panelRows(t, data, failure, phase) {
       const rows = []
       if (data !== null) {
         if (data.infos.length === 0) {
-          rows.push(row('余额', '无数据'))
+          rows.push(row(t('panel.balance'), t('panel.noData')))
         } else {
           for (const info of data.infos) {
             const symbol = symbolOf(info.currency)
-            rows.push(row(info.currency + ' 总余额', symbol + info.total))
-            rows.push(row('  赠金 / 充值', symbol + info.granted + ' / ' + symbol + info.toppedUp))
+            rows.push(row(t('panel.totalIn', { currency: info.currency }), symbol + info.total))
+            rows.push(row(t('panel.grantSplit'), symbol + info.granted + ' / ' + symbol + info.toppedUp))
           }
         }
-        rows.push(row('可调用', data.isAvailable === true ? '是' : '否'))
-        rows.push(row('更新于', formatTime(data.at)))
+        rows.push(row(t('panel.callable'), data.isAvailable === true ? t('panel.yes') : t('panel.no')))
+        rows.push(row(t('panel.updated'), formatTime(data.at)))
       } else if (phase === 'loading') {
-        rows.push(row('状态', '查询中 …'))
-        rows.push(row('凭据', 'DEEPSEEK_API_KEY'))
+        rows.push(row(t('panel.state'), t('panel.querying')))
+        rows.push(row(t('panel.credential'), 'DEEPSEEK_API_KEY'))
       } else {
-        rows.push(row('错误', failure === null ? '余额暂不可用' : failure, 'dsh-balance-err'))
-        rows.push(row('凭据', 'DEEPSEEK_API_KEY'))
+        rows.push(row(t('panel.error'), failure === null ? t('error.fallback') : failure, 'dsh-balance-err'))
+        rows.push(row(t('panel.credential'), 'DEEPSEEK_API_KEY'))
       }
-      rows.push(React.createElement('div', { className: 'dsh-balance-hint', key: 'hint' },
-        '点击刷新 · 按住拖动可移动位置'))
+      rows.push(React.createElement('div', { className: 'dsh-balance-hint', key: 'hint' }, t('hint')))
       return rows
     }
 
     return {
-      inject: ['slots', 'timer'],
+      inject: ['slots', 'timer', 'locale'],
       apply(ctx) {
         ctx.effect(() => {
           if (document.getElementById(STYLE_ID) === null) {
@@ -150,10 +259,13 @@ window.__ModuleLoader__.load({
           return () => { document.getElementById(STYLE_ID)?.remove() }
         }, 'deepseek-balance: styles')
 
+        ctx.effect(() => ctx.locale.register(NS, DICTS), 'deepseek-balance: dictionaries')
+
         // Defined inside apply so the component closes over this fiber's context
         // and can own its own interval. One mount per client run keeps the
         // component identity stable across re-renders.
-        function BalanceBadge() {
+        function BalanceBadge(props) {
+          const t = translatorOf(props)
           const [snapshot, setSnapshot] = React.useState({ phase: 'loading' })
           const [busy, setBusy] = React.useState(false)
           const [position, setPosition] = React.useState({ right: 22, bottom: 22 })
@@ -215,17 +327,16 @@ window.__ModuleLoader__.load({
           const data = snapshot.phase === 'ready' && snapshot.data !== null && snapshot.data.ok === true
             ? snapshot.data
             : null
-          const failure = snapshot.phase === 'error'
-            ? snapshot.message
-            : (snapshot.phase === 'ready' && snapshot.data !== null && snapshot.data.ok !== true
-                ? snapshot.data.message
-                : null)
+          const failed = snapshot.phase === 'error'
+            ? { message: snapshot.message }
+            : (snapshot.phase === 'ready' && snapshot.data !== null && snapshot.data.ok !== true ? snapshot.data : null)
+          const failure = failed === null ? null : failureText(t, failed)
 
           let tone = 'idle'
-          let label = '余额 …'
-          if (snapshot.phase === 'error' || failure !== null) {
+          let label = t('pill.loading')
+          if (failure !== null) {
             tone = 'error'
-            label = '余额不可用'
+            label = t('pill.unavailable')
           } else if (data !== null) {
             tone = data.isAvailable === true ? 'ok' : 'warn'
             label = symbolOf(data.currency) + data.total
@@ -237,12 +348,12 @@ window.__ModuleLoader__.load({
               className: 'dsh-balance-root dsh-balance-tone-' + tone,
               style: { right: position.right + 'px', bottom: position.bottom + 'px' },
             },
-            React.createElement('div', { className: 'dsh-balance-panel' }, panelRows(data, failure, snapshot.phase)),
+            React.createElement('div', { className: 'dsh-balance-panel' }, panelRows(t, data, failure, snapshot.phase)),
             React.createElement(
               'div',
               {
                 className: 'dsh-balance-pill',
-                title: 'DeepSeek 余额 · 点击刷新 · 拖动移动',
+                title: t('pill.title'),
                 onPointerDown,
                 onPointerMove,
                 onPointerUp,
@@ -256,7 +367,9 @@ window.__ModuleLoader__.load({
         }
 
         ctx.effect(() => ctx.slots.inject('shell.overlay', () => ctx.slots.register(
-          { name: 'shell.overlay', id: 'deepseek-balance', order: 200 },
+          // Naming the locale namespace is what makes the framework inject the
+          // `t` seat (and re-render every outlet when the language changes).
+          { name: 'shell.overlay', id: 'deepseek-balance', order: 200, locale: NS },
           BalanceBadge,
         )), 'deepseek-balance: overlay badge')
       },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ruoyang/dsh-plugin-deepseek-balance",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Floating DeepSeek API balance badge for the DeepSeek Harness Web UI, backed by the harness's own DEEPSEEK_API_KEY credential",
   "license": "MIT",
   "type": "module",
@@ -42,6 +42,7 @@
       "platform": "web",
       "immediately": true,
       "inject": [
+        "@deepseek-ai/dsh-client-locale",
         "@deepseek-ai/dsh-client-ui-layout"
       ]
     }