dsh-plugin-vrmpet3d 0.1.0 → 0.1.2

package/lib/setup-page.js

@@ -23,6 +23,176 @@
   var core = globalThis.__VRMPET3D_CORE__;
   if (!core) return;
 
+  /**
+   * This page's own words, in the two languages — the shape every surface here uses (`lib/menu.js`'s `LABELS`,
+   * `lib/model-picker.js`'s `TEXT`): `{ zh: {...}, en: {...} }`, one table per surface rather than one dictionary
+   * for the whole plugin, and the SAME KEYS in both halves (a suite asserts that).
+   *
+   * The markup carries its Chinese inline as the no-JS fallback and names the key that replaces it
+   * (`core.applyI18n`); the entries below are what this script writes at run time, read through `t()` at CALL time
+   * and never captured in a module-level variable — a captured string would freeze the first language the page
+   * happened to boot in. `{...}` tokens are filled from `t`'s second argument, which is also how the core's own
+   * status lines name their clock.
+   *
+   * What is NOT here: data (provider, model and file names, folder paths, counts — they are translated around,
+   * never translated), and the 碎碎念 content, which belongs to `core.js` and already ships in both languages.
+   */
+  var TEXT = {
+    zh: {
+      // The chrome, and the stepper the script reads its own words back from.
+      pageTitle: 'vrmpet3d · 初次安装引导',
+      guideTitle: '初次安装引导',
+      guideDoneTitle: '配置完成',
+      reading: '正在读取…',
+      stepsAria: '引导进度',
+      stepWelcome: '欢迎',
+      stepModel: '偏好模型',
+      stepSurface: '桌宠界面',
+      stepSpeech: 'AI 碎碎念',
+      stepMotions: '模型动作',
+      stepDone: '完成',
+      // 界面语言 — the one control the welcome screen adds, and the only choice applied before 完成.
+      language: '界面语言',
+      languageAuto: '自动',
+      languageZh: '中文',
+      languageEn: 'English',
+      // ① 欢迎
+      welcomeTitle: '欢迎，也先说清楚风险',
+      welcomeRisk: '这是一个<strong>早期版本</strong>的插件，作者也是第一次开发 DSH 插件。它<strong>还没有经过系统性的验证</strong>，可能存在 bug，也可能带来性能下降；设置页面的排版也可能比较混乱。',
+      welcomeWarning: '如果你在使用中遇到任何性能问题，请<strong>第一时间禁用这个插件</strong>，再慢慢排查。',
+      // ③ 桌宠界面, including the runtime folder the launcher is about to create.
+      surfaceTitle: '桌宠出现在哪里',
+      surfaceAuto: '自动',
+      surfaceAutoNote: 'Desktop端自动开启独立桌宠',
+      surfaceApp: '只在内置桌宠',
+      runtimeBorrow: '<strong>浮窗会借用一份 DSH 自带的运行时。</strong>独立浮窗需要无边框、置顶、点击穿透的系统窗口，这只有 Electron 能给，而插件不自带（那会多出两百多兆）。所以启用浮窗时，启动器会在 <strong>DSH 安装目录所在的分区</strong>里建一个运行时目录，用 <strong>硬链接</strong>指向 DSH 自己的那批客户端文件 —— 于是它看起来就是一份没改动过的 DSH。',
+      runtimeLinks: '<strong>硬链接与 DSH 共享同一份数据，不额外占盘</strong>（新增的只有一个小 app 壳），并且它<strong>必须与 DSH 同盘</strong>：硬链接不能跨卷。删掉这个目录是安全的，下次启用浮窗会重新建一份。',
+      runtimeDir: '这次用的运行时目录：{dir}',
+      // ④ AI 碎碎念
+      speechTitle: 'AI 碎碎念',
+      speechEnabled: '开启碎碎念',
+      speechBuiltin: '内置台词',
+      speechBuiltinNote: '内置台词基本已经够用',
+      speechAi: 'AI 生成',
+      speechProvider: 'AI 来源',
+      speechAiNote: '人格信息和不同状态的提示词，都在 通用设置 → 碎碎念 里设置。',
+      speechDisclaimerA: '<strong>碎碎念只是玩笑，请勿当真。</strong>这些话要么来自内置台词，要么由你配置的模型即兴生成，都属于角色扮演：不是宠物的真实判断，也不构成任何建议。',
+      speechDisclaimerB: '插件<strong>不会对你的项目或文件做任何实际操作</strong>（不执行命令、不改动代码），只读取会话的<strong>运行状态</strong>（进行中 / 等待确认 / 完成 等）来决定表情和动作，会话文字、工具参数与附件都不会被它读取；你导入的模型或动作，只会被复制到插件自己的目录里。<strong>它也不会干扰 DSH 本身的运行</strong>，且不带任何运行时依赖。不过在配置较差的机器上，3D 渲染与弹簧骨物理可能带来轻微的性能影响 —— 关掉桌宠，或把尺寸调小一些，就能缓解。',
+      noProviders: '没有可用的 provider。',
+      // ⑤ 模型动作
+      motionsTitle: '模型动作',
+      motionsPick: '选择动作文件夹…',
+      motionsManual: '手动输入路径',
+      motionsPath: '文件夹路径',
+      motionsAdd: '导入',
+      motionsImportedCount: '已导入 {count} 个动作文件夹',
+      motionsImportedRow: '已导入',
+      motionsClips: '{name}（{clips} 支）',
+      motionsRemove: '移除',
+      motionDefaultsKnown: '各状态的默认动作：{list}。这些默认值可以在通用设置 → 状态与动作里改。',
+      motionDefaultsNone: '动作包已按工作状态分好目录（{count} 支）：每个状态的选择框里只会列出它自己目录里的动作。当前这版还没有预置状态→动作的默认映射，所以你需要在通用设置 → 状态与动作里为状态勾选动作。',
+      motionImporting: '正在导入动作…',
+      motionImportedName: '已导入动作文件夹：{name}（{clips} 支）',
+      motionImported: '已导入动作。',
+      motionImportFailed: '导入失败：{error}',
+      motionRemoved: '已移除插件复制的那一份。',
+      motionRemoveFailed: '移除失败：{error}',
+      // The list separators `motionDefaultsKnown` is assembled with — prose punctuation, so it travels with the words.
+      sepList: '、',
+      sepClause: '；',
+      // 完成, and the footer.
+      doneTitle: '完成',
+      doneSaved: '配置已保存。',
+      finishButton: '完成',
+      closeWindow: '关闭窗口',
+      later: '稍后配置',
+      back: '上一步',
+      next: '下一步',
+      // Status lines this script writes (the picker's own status is the component's, not this table's).
+      hostNoStore: '这个宿主没有提供设置接口，改动只在本页生效。',
+      coreNoStore: '这个版本的 core 没有设置接口，页面只能展示默认值。',
+      pickerMissing: '这个页面没有加载模型选择组件（model-picker.js）。',
+      noNativePicker: '这个窗口没有原生选择器（不是在 DSH 桌面版里打开的），请在下面直接输入路径。',
+      readSettings: '已读取当前设置。',
+      savedNoGuide: '已保存：这个引导不会再出现了。',
+      setupComplete: '配置完成。',
+      saveFailed: '保存失败：{error}',
+      skipped: '已跳过：下次插件启动时会再提醒你一次。',
+    },
+    en: {
+      pageTitle: 'vrmpet3d · First-run guide',
+      guideTitle: 'First-run guide',
+      guideDoneTitle: 'Setup complete',
+      reading: 'Reading…',
+      stepsAria: 'Guide progress',
+      stepWelcome: 'Welcome',
+      stepModel: 'Preferred model',
+      stepSurface: 'Pet surface',
+      stepSpeech: 'AI chit-chat',
+      stepMotions: 'Model motions',
+      stepDone: 'Done',
+      language: 'Interface language',
+      languageAuto: 'Auto',
+      languageZh: '中文',
+      languageEn: 'English',
+      welcomeTitle: 'Welcome — and the risks first',
+      welcomeRisk: 'This is an <strong>early build</strong> of the plugin, and its author is writing a DSH plugin for the first time. It has <strong>not been through systematic testing</strong> yet: it may have bugs and may cost you performance, and the settings pages may be laid out awkwardly.',
+      welcomeWarning: 'If you run into any performance problem while using it, <strong>disable the plugin first</strong> and then work out what happened.',
+      surfaceTitle: 'Where the pet appears',
+      surfaceAuto: 'Automatic',
+      surfaceAutoNote: 'On DSH Desktop the floating pet opens by itself',
+      surfaceApp: 'In-app pet only',
+      runtimeBorrow: '<strong>The floating pet borrows a runtime that ships with DSH.</strong> An independent floating window needs a borderless, always-on-top, click-through system window, and only Electron can provide one — which this plugin does not ship (that would add a couple of hundred megabytes). So when the floating pet is enabled, the launcher creates a runtime folder <strong>on the same volume as the DSH install</strong> and <strong>hard-links</strong> it to DSH\'s own client files, which is why it looks like an untouched copy of DSH.',
+      runtimeLinks: '<strong>Hard links share DSH\'s own data and take no extra disk space</strong> (the only new thing is a small app shell), and the folder <strong>has to be on the same volume as DSH</strong>: hard links cannot cross volumes. Deleting the folder is safe — the next time the floating pet is enabled, it is created again.',
+      runtimeDir: 'Runtime folder in use: {dir}',
+      speechTitle: 'AI chit-chat',
+      speechEnabled: 'Turn chit-chat on',
+      speechBuiltin: 'Built-in lines',
+      speechBuiltinNote: 'The built-in lines are usually enough',
+      speechAi: 'Generated by AI',
+      speechProvider: 'AI source',
+      speechAiNote: 'The persona and the per-state prompts live in General settings → Chit-chat.',
+      speechDisclaimerA: '<strong>The chit-chat is a joke — do not take it seriously.</strong> The lines either come from the built-in script or are improvised by the model you configured; either way it is role-play, not the pet\'s real judgement, and not advice of any kind.',
+      speechDisclaimerB: 'The plugin <strong>takes no real action on your project or files</strong> (it runs no commands and changes no code). It reads only the session\'s <strong>run state</strong> (working / waiting for confirmation / done, and so on) to choose expressions and motions — session text, tool arguments and attachments are never read, and the models or motions you import are only copied into the plugin\'s own folder. <strong>It does not interfere with DSH itself</strong> and has no runtime dependencies. On a weak machine, though, the 3D rendering and spring-bone physics can cost a little performance — turning the pet off or making it smaller eases that.',
+      noProviders: 'No provider is available.',
+      motionsTitle: 'Model motions',
+      motionsPick: 'Choose a motions folder…',
+      motionsManual: 'Type a path',
+      motionsPath: 'Folder path',
+      motionsAdd: 'Import',
+      motionsImportedCount: '{count} motion folders imported',
+      motionsImportedRow: 'Imported',
+      motionsClips: '{name} ({clips} clips)',
+      motionsRemove: 'Remove',
+      motionDefaultsKnown: 'Default motions by state: {list}. They can be changed in General settings → States & motions.',
+      motionDefaultsNone: 'The pack is already split into per-state folders ({count} clips): a state\'s picker only lists the clips in its own folder. This build ships no state→motion defaults yet, so you need to tick motions per state in General settings → States & motions.',
+      motionImporting: 'Importing motions…',
+      motionImportedName: 'Imported the motions folder {name} ({clips} clips)',
+      motionImported: 'Motions imported.',
+      motionImportFailed: 'Import failed: {error}',
+      motionRemoved: 'Removed the plugin\'s own copy.',
+      motionRemoveFailed: 'Could not remove it: {error}',
+      sepList: ', ',
+      sepClause: '; ',
+      doneTitle: 'Done',
+      doneSaved: 'Your settings are saved.',
+      finishButton: 'Finish',
+      closeWindow: 'Close window',
+      later: 'Configure later',
+      back: 'Back',
+      next: 'Next',
+      hostNoStore: 'This host offers no settings API — a change applies to this page only.',
+      coreNoStore: 'This build of core offers no settings API; the page can only show the defaults.',
+      pickerMissing: 'This page did not load the model picker (model-picker.js).',
+      noNativePicker: 'This window has no native picker (it was not opened by DSH Desktop) — type the path below instead.',
+      readSettings: 'Read the current settings.',
+      savedNoGuide: 'Saved: this guide will not appear again.',
+      setupComplete: 'Setup complete.',
+      saveFailed: 'Could not save: {error}',
+      skipped: 'Skipped: the guide will ask once more the next time the plugin starts.',
+    },
+  };
+
   /**
    * Every screen the markup carries — INCLUDING the ones this run may not visit.
    *
@@ -36,9 +206,35 @@
   var hasSnapshot = false;
   var preferences = core.cleanPreferences({});
   var hostSync = null;
+  /**
+   * The language this page is drawn in RIGHT NOW: the stored answer resolved against the page's own environment.
+   *
+   * It starts as the markup's own language and is replaced by `applyLanguage` before anything is drawn. Every string
+   * is read through `t()` against this value, so a language change has no captured copy to go stale.
+   */
+  var language = 'zh';
+  /**
+   * A 界面语言 pick made BEFORE the first snapshot — the one case where "local first, write when allowed" is not
+   * enough on its own.
+   *
+   * `patchPreferences` refuses to write before the snapshot (the data-loss latch, see the header), and this page's
+   * language control sits on the FIRST screen: a reader who cannot read the page reaches it in the first second,
+   * well before the store has answered. The pick is applied locally either way, and this remembers it so the first
+   * snapshot can write it rather than putting the stored answer back over it.
+   */
+  var pendingLanguage = null;
   /** The imported lists, as the host reports them: what to show and what a 移除 acts on. */
   var importedModels = [];
   var importedMotions = [];
+  /**
+   * The last `/vrmpet3d/motions` payload, kept so a language change can re-say the defaults line.
+   *
+   * That line is built from the pack's own data (`renderMotionDefaults`) and the route is fetched once at boot;
+   * caching the payload is what makes it re-renderable without asking the host a second time. `null` until the
+   * first reply, and `renderMotionDefaults` is skipped while it is — the line's "no data" branch would otherwise
+   * claim an empty pack on every boot.
+   */
+  var motionBody = null;
   /** The shared model picker the ② 偏好模型 step mounts (`lib/model-picker.js`). */
   var picker = null;
   /** Which model a surface reports it is showing, from the snapshot's `live` — what ends the progress bar. */
@@ -48,6 +244,43 @@
 
   function el(id) { return document.getElementById(id); }
 
+  /** One of this page's own strings, in the language it is drawn in right now; `{name}` tokens are filled in. */
+  function t(key, values) {
+    var out = core.textOf(TEXT, language, key);
+    if (!values) return out;
+    Object.keys(values).forEach(function (name) {
+      out = out.split('{' + name + '}').join(String(values[name]));
+    });
+    return out;
+  }
+
+  /**
+   * The status line's own last state, so a LANGUAGE CHANGE can say it again in the new language.
+   *
+   * `core.applyI18n` walks the whole document, and without this it would put the shipped 「正在读取…」 back over a
+   * line this page has since replaced ("已导入动作文件夹：…", "保存失败：…"). Every line this page writes comes from a
+   * table KEY, which is what makes re-saying it possible; the shared picker's own status is the exception (those
+   * words are the component's, and arrive in the component's language), so it passes through as raw text.
+   */
+  var statusLine = { key: 'reading', values: null, kind: '', text: '' };
+
+  /** Say one of this page's own strings — and remember the key, so a language change says it again. */
+  function say(key, values, kind) {
+    statusLine = { key: key, values: values || null, kind: kind || '', text: '' };
+    setStatus(t(key, values), kind);
+  }
+
+  /** Say a line whose words are NOT this table's (the shared picker's own status). */
+  function noteStatus(text, kind) {
+    statusLine = { key: '', values: null, kind: kind || '', text: text || '' };
+    setStatus(text, kind);
+  }
+
+  /** The status line again, in the current language — what `applyLanguage` calls after the markup table. */
+  function restateStatus() {
+    setStatus(statusLine.key ? t(statusLine.key, statusLine.values) : statusLine.text, statusLine.kind);
+  }
+
   function setStatus(text, kind) {
     var node = el('status');
     if (!node) return;
@@ -156,9 +389,11 @@
     var back = el('setup-back');
     var next = el('setup-next');
     if (back) back.disabled = current === 0;
-    if (next) next.textContent = current === last ? '完成' : '下一步';
+    // Both of these are re-stated from the table rather than written once: `goto` is what `applyLanguage` calls, so
+    // this is the function that has to know the language as it is NOW.
+    if (next) next.textContent = t(current === last ? 'finishButton' : 'next');
     var header = document.querySelector('.page-header h1');
-    if (header) header.textContent = current === last ? '配置完成' : '初次安装引导';
+    if (header) header.textContent = t(current === last ? 'guideDoneTitle' : 'guideTitle');
     // The finish screen's own button is the one that WRITES; the footer says the same thing for a user who
     // navigates by keyboard.
     if (next) next.hidden = false;
@@ -175,7 +410,7 @@
   function patchPreferences(patch) {
     Object.keys(patch).forEach(function (key) { preferences[key] = patch[key]; });
     if (!hasSnapshot || !hostSync || typeof hostSync.push !== 'function') {
-      if (!hostSync) setStatus('这个宿主没有提供设置接口，改动只在本页生效。', 'warn');
+      if (!hostSync) say('hostNoStore', null, 'warn');
       return;
     }
     hostSync.push({ preferences: patch });
@@ -214,12 +449,14 @@
     var mount = el('setup-model-picker');
     var api = globalThis.__VRMPET3D_MODEL_PICKER__;
     if (!mount || !api || typeof api.createModelPicker !== 'function') {
-      setStatus('这个页面没有加载模型选择组件（model-picker.js）。', 'warn');
+      say('pickerMissing', null, 'warn');
       return null;
     }
     picker = api.createModelPicker({
       mount: mount,
-      language: 'zh',
+      // The component is BUILT in this language; `applyLanguage` hands it a later change through `setLanguage`
+      // (which relabels the same nodes and keeps the catalog and any switch in flight).
+      language: language,
       currentModelId: function () { return preferences.modelId || ''; },
       /**
        * Which model a pet reports it is SHOWING (`snapshot.live`), so the progress bar is about the LOAD rather
@@ -229,7 +466,8 @@
       // Choosing a model in a guide called 「偏好模型」 and then not choosing it would be a strange half-step:
       // the component calls this for a CLICK and after an import, and both mean "this is my model now".
       onSwitch: function (id) { patchPreferences({ modelId: id }); },
-      onStatus: setStatus,
+      // The component's own lines, in the component's own language (see `statusLine`).
+      onStatus: noteStatus,
     });
     return picker;
   }
@@ -283,7 +521,8 @@
       .then(function (response) { return response.ok ? response.json() : null; })
       .then(function (status) {
         var dir = status && typeof status.runtimeDir === 'string' ? status.runtimeDir : '';
-        line.textContent = dir ? '这次用的运行时目录：' + dir : '';
+        // The path is data; the sentence around it is this table's, and is read at THIS moment.
+        line.textContent = dir ? t('runtimeDir', { dir: dir }) : '';
       })
       .catch(function () { line.textContent = ''; });
   }
@@ -359,9 +598,7 @@
     if (note) {
       var available = providerList().length;
       // The count is data; the sentence around it was explanation, so only a real problem is stated.
-      note.textContent = speech.source === 'ai' && !available
-        ? '没有可用的 provider。'
-        : '';
+      note.textContent = speech.source === 'ai' && !available ? t('noProviders') : '';
     }
   }
 
@@ -404,15 +641,16 @@
     var list = el('setup-motion-list');
     var note = el('setup-motion-note');
     var count = el('setup-motion-count');
-    if (count) count.textContent = importedMotions.length ? '已导入 ' + importedMotions.length + ' 个动作文件夹' : '';
+    if (count) count.textContent = importedMotions.length ? t('motionsImportedCount', { count: importedMotions.length }) : '';
     if (list) {
       clear(list);
       importedMotions.forEach(function (entry) {
         var row = document.createElement('div');
         row.className = 'row';
-        row.appendChild(text('span', 'k', '已导入'));
-        row.appendChild(text('span', 'grow note', entry.name + '（' + entry.clips + ' 支）')).title = entry.source || entry.dir;
-        var remove = text('button', 'ghost', '移除');
+        row.appendChild(text('span', 'k', t('motionsImportedRow')));
+        // The name and the clip count are the host's data; only the words around them are translated.
+        row.appendChild(text('span', 'grow note', t('motionsClips', { name: entry.name, clips: entry.clips }))).title = entry.source || entry.dir;
+        var remove = text('button', 'ghost', t('motionsRemove'));
         remove.addEventListener('click', function () { removeMotion(entry.dir); });
         row.appendChild(remove);
         list.appendChild(row);
@@ -426,6 +664,8 @@
   function refreshMotions() {
     return getJson('/vrmpet3d/motions').then(function (body) {
       importedMotions = body && Array.isArray(body.importedMotions) ? body.importedMotions : [];
+      // Kept for `applyLanguage`: this route is fetched once, and the defaults line below is built from its payload.
+      motionBody = body || null;
       renderMotions();
       renderMotionDefaults(body);
       return body;
@@ -448,26 +688,33 @@
     names.forEach(function (entry) { byId[entry.id] = entry.name; });
     var states = (core.MOTION_STATES || []).filter(function (state) { return (defaults[state] || []).length; });
     if (states.length) {
-      node.textContent = '各状态的默认动作：' + states.map(function (state) {
-        return state + ' → ' + (defaults[state] || []).map(function (id) { return byId[id] || id; }).join('、');
-      }).join('；') + '。这些默认值可以在通用设置 → 状态与动作里改。';
+      // The states and the clips are the pack's own names; the sentence and its list punctuation are this table's.
+      node.textContent = t('motionDefaultsKnown', {
+        list: states.map(function (state) {
+          return state + ' → ' + (defaults[state] || []).map(function (id) { return byId[id] || id; }).join(t('sepList'));
+        }).join(t('sepClause')),
+      });
       return;
     }
-    node.textContent = '动作包已按工作状态分好目录（' + names.length + ' 支）：每个状态的选择框里只会列出它自己目录里的动作。'
-      + '当前这版还没有预置状态→动作的默认映射，所以你需要在通用设置 → 状态与动作里为状态勾选动作。';
+    node.textContent = t('motionDefaultsNone', { count: names.length });
   }
 
   function importMotion(path) {
     if (!path) return Promise.resolve();
-    setStatus('正在导入动作…');
+    say('motionImporting');
     return post('/vrmpet3d/motions', { importDir: path }).then(function (payload) {
       importedMotions = payload && Array.isArray(payload.importedMotions) ? payload.importedMotions : importedMotions;
       renderMotions();
-      if (payload) renderMotionDefaults(payload);
+      if (payload) {
+        // The same shape `refreshMotions` caches: an import reply carries the whole catalog (`lib/index.js`).
+        motionBody = payload;
+        renderMotionDefaults(payload);
+      }
       var last = importedMotions[importedMotions.length - 1];
-      setStatus(last ? '已导入动作文件夹：' + last.name + '（' + last.clips + ' 支）' : '已导入动作。');
+      if (last) say('motionImportedName', { name: last.name, clips: last.clips });
+      else say('motionImported');
     }).catch(function (error) {
-      setStatus('导入失败：' + (error && error.message ? error.message : error), 'warn');
+      say('motionImportFailed', { error: error && error.message ? error.message : error }, 'warn');
     });
   }
 
@@ -475,9 +722,9 @@
     return post('/vrmpet3d/motions', { unimportDir: dir }).then(function (payload) {
       importedMotions = payload && Array.isArray(payload.importedMotions) ? payload.importedMotions : importedMotions;
       renderMotions();
-      setStatus('已移除插件复制的那一份。');
+      say('motionRemoved');
     }).catch(function (error) {
-      setStatus('移除失败：' + (error && error.message ? error.message : error), 'warn');
+      say('motionRemoveFailed', { error: error && error.message ? error.message : error }, 'warn');
     });
   }
 
@@ -501,7 +748,7 @@
         if (!choose) {
           if (row) row.hidden = false;
           if (input) input.focus();
-          setStatus('这个窗口没有原生选择器（不是在 DSH 桌面版里打开的），请在下面直接输入路径。', 'warn');
+          say('noNativePicker', null, 'warn');
           return;
         }
         Promise.resolve(choose()).then(function (chosen) { return chosen ? onChosen(chosen) : null; });
@@ -543,9 +790,9 @@
      */
     var complete = function () {
       post('/vrmpet3d/setup-state', { completed: true }).then(function () {
-        if (note) note.textContent = '已保存：这个引导不会再出现了。';
+        if (note) note.textContent = t('savedNoGuide');
         if (finish) finish.disabled = true;
-        setStatus('配置完成。');
+        say('setupComplete');
         closeWindow();
         /**
          * And if the window is STILL here, offer the button rather than a dead end.
@@ -558,11 +805,11 @@
           view.setTimeout(function () {
             if (view.closed === true) return;
             if (close) close.hidden = false;
-            if (note) note.textContent = '已保存：这个引导不会再出现了。';
+            if (note) note.textContent = t('savedNoGuide');
           }, 300);
         }
       }).catch(function (error) {
-        if (note) note.textContent = '保存失败：' + (error && error.message ? error.message : error);
+        if (note) note.textContent = t('saveFailed', { error: error && error.message ? error.message : error });
       });
     };
     if (finish) finish.addEventListener('click', complete);
@@ -584,13 +831,36 @@
     var later = el('setup-later');
     if (later) {
       later.addEventListener('click', function () {
-        setStatus('已跳过：下次插件启动时会再提醒你一次。');
+        say('skipped');
         closeWindow();
       });
     }
   }
 
   function wireChoices() {
+    /**
+     * 界面语言, on the welcome screen — and the ONE choice here that is not saved for 完成.
+     *
+     * Operator, 2026-10-15: 「在初始安装引导页的第一页欢迎页面中加上语言选择」, and the point of putting it on the FIRST
+     * screen is that it has to work BEFORE the reader has finished reading: a reader who cannot read 中文 picks
+     * English and wants the sentence in front of them to change, not the next screen. So this patches the setting
+     * through the page's own path ({@link patchPreferences}, snapshot-guarded and local-first) and then re-labels
+     * everything in place ({@link applyLanguage}).
+     *
+     * The value written is the STORED answer — `auto` included, never a resolved 'zh'/'en' (`core.cleanLanguage`
+     * documents why: a profile that froze the resolved language could never follow the machine again).
+     */
+    var lang = el('setup-language');
+    if (lang) {
+      lang.addEventListener('change', function () {
+        var choice = core.cleanLanguage(lang.value);
+        // See `pendingLanguage`: before the first snapshot this pick cannot be written yet, and the snapshot that
+        // arrives next would otherwise overwrite it with the stored answer.
+        pendingLanguage = hasSnapshot ? null : choice;
+        patchPreferences({ language: choice });
+        applyLanguage();
+      });
+    }
     var surface = el('setup-surface');
     if (surface) {
       Array.prototype.forEach.call(surface.querySelectorAll('input[name="setup-surface"]'), function (input) {
@@ -623,6 +893,71 @@
     }
   }
 
+  /** The language THIS page would draw in: the stored answer resolved against the page's own environment. */
+  function resolvedLanguage() {
+    // `browserLanguageHints` is the browser's answer first and the document's own `lang` second (see core). The
+    // document is marked by `applyLanguage` itself, so on every pass after the first the second hint is the
+    // language already in force — stable, and still overruled by an explicit 中文/English or by the browser.
+    return core.resolveLanguage(preferences.language, core.browserLanguageHints());
+  }
+
+  /** The selector shows the STORED answer — `auto` included — never the language it resolved to. */
+  function renderLanguage() {
+    var select = el('setup-language');
+    if (select) select.value = core.cleanLanguage(preferences.language);
+  }
+
+  /**
+   * Draw this page in the language it should be drawn in — the ONE place that knows how, and the only thing a
+   * language change calls.
+   *
+   * It has three jobs rather than one, because this page's words live in three places and each needs its own step:
+   *
+   *   1. the MARKUP, which keeps its Chinese inline as the no-JS fallback and names its key — `core.applyI18n`;
+   *   2. the strings this script writes — every one of them is read through `t()` at call time, so re-running the
+   *      section renderers (`goto`, `renderSurface`, `renderSpeech`, `renderMotions`, `renderMotionDefaults`) is
+   *      what re-states them;
+   *   3. the SHARED model picker, which is BUILT in one language (`createModelPicker`'s `language`) and relabels
+   *      through its own `setLanguage` — the same nodes, the same catalog, a switch in flight left alone. A picker
+   *      without that call (an older component) is mounted again instead: `destroy` removes exactly the subtree it
+   *      owns, and the mount point, the store callbacks and the catalog refresh are all reused.
+   *
+   * `documentElement.lang` follows the resolved language, which is what makes a host-served page honest about its
+   * own language (and is where `browserLanguageHints`' second hint comes from on the next pass).
+   *
+   * The status line is the one node `applyI18n` would overwrite with a shipped default, so it is re-stated from
+   * the key it was last written with — see `statusLine`.
+   */
+  function applyLanguage() {
+    language = resolvedLanguage();
+    if (document.documentElement) document.documentElement.lang = language;
+    core.applyI18n(document, TEXT, language);
+    renderLanguage();
+    if (!picker) {
+      mountModelPicker();
+      refreshModels();
+    } else if (typeof picker.setLanguage === 'function') {
+      picker.setLanguage(language);
+    } else {
+      // An older component that only takes its words at construction: mount it again, and re-read the catalog the
+      // new instance does not have yet. `destroy` is its own API and the mount is cleared as well, so a component
+      // that grew a different teardown cannot leave a stale grid behind the new one.
+      if (typeof picker.destroy === 'function') picker.destroy();
+      var mount = el('setup-model-picker');
+      if (mount) clear(mount);
+      picker = null;
+      mountModelPicker();
+      refreshModels();
+    }
+    goto(current);
+    renderSurface();
+    renderSpeech();
+    renderMotions();
+    // Skipped until the first `/vrmpet3d/motions` reply: its "no data" branch would claim an empty pack.
+    if (motionBody) renderMotionDefaults(motionBody);
+    restateStatus();
+  }
+
   /**
    * The host's settings store, the same contract the two settings pages use.
    *
@@ -631,7 +966,7 @@
    */
   function watchSettings() {
     if (typeof core.watchHostSettings !== 'function') {
-      setStatus('这个版本的 core 没有设置接口，页面只能展示默认值。', 'warn');
+      say('coreNoStore', null, 'warn');
       renderSurface();
       renderSpeech();
       return;
@@ -643,6 +978,25 @@
       onSnapshot: function (snapshot) {
         preferences = core.cleanPreferences(snapshot.preferences || {});
         hasSnapshot = true;
+        if (pendingLanguage) {
+          // The reader's own pick, made while the page had no write permission: this is the first moment it can be
+          // written, and it outranks the snapshot that was already in flight when they made it. The store merges by
+          // key, so the patch carries this one setting and nothing else.
+          preferences.language = pendingLanguage;
+          if (hostSync && typeof hostSync.push === 'function') hostSync.push({ preferences: { language: pendingLanguage } });
+          pendingLanguage = null;
+        }
+        /**
+         * THE LANGUAGE FIRST, because the snapshot is where the stored answer arrives.
+         *
+         * The selector always follows the STORE, and when the answer RESOLVES to a different language than the one
+         * the page booted in — a profile set to 中文 opened on an English machine, or the other way round — the
+         * whole page is re-labelled before the rest of this snapshot paints. A change that resolves to the same
+         * language needs nothing but the selector.
+         */
+        var before = language;
+        renderLanguage();
+        if (resolvedLanguage() !== before) applyLanguage();
         // The live report, for the picker's progress bar: which model a pet says it is actually showing.
         var live = snapshot && snapshot.live ? snapshot.live : null;
         liveModel = live ? (live.app || live.window || null) : null;
@@ -652,27 +1006,26 @@
         // and this is the call that asks whether an in-flight switch has finished.
         if (picker) picker.setCurrent();
         // Never over a switch's own line: while the bar is up, that line is what the user is reading.
-        if (!(picker && picker.state().switching)) setStatus('已读取当前设置。');
+        if (!(picker && picker.state().switching)) say('readSettings');
       },
     }).start();
   }
 
   function boot() {
-    setStatus('正在读取…');
+    // The language is resolved FIRST: every line below is written through `t`, and the model picker takes its own
+    // language when `applyLanguage` mounts it.
+    language = resolvedLanguage();
+    say('reading');
     wireChoices();
     wireFinish();
-    // The model step is the shared picker; the motion step keeps its pick-or-type row (a folder cannot be
-    // dropped into a form field, and the picker's own component has no folder mode).
-    mountModelPicker();
+    // The model step is the shared picker, mounted by `applyLanguage` because its words are fixed at construction;
+    // the motion step keeps its pick-or-type row (a folder cannot be dropped into a form field, and the picker's
+    // own component has no folder mode).
     wirePicker('setup-motion-pick', 'setup-motion-manual', 'setup-motion-manual-row', 'setup-motion-path', 'setup-motion-add',
       'pickMotionDir', importMotion);
+    applyLanguage();
     watchSettings();
-    renderSurface();
-    renderSpeech();
-    renderMotions();
-    goto(0);
     loadLlm();
-    refreshModels();
     refreshMotions();
   }