agentvibes 4.4.1 → 4.5.0

package/setup-windows.ps1

@@ -283,8 +283,8 @@ if (-not (Test-Path $HooksDir)) {
 $HookScriptInfo = @(
     @{ Name = "play-tts.ps1"; Desc = "Main TTS router - dispatches to active provider" },
     @{ Name = "play-tts-soprano.ps1"; Desc = "Soprano neural voice provider (fastest)" },
-    @{ Name = "play-tts-windows-piper.ps1"; Desc = "Piper offline neural voice provider" },
-    @{ Name = "play-tts-windows-sapi.ps1"; Desc = "Windows built-in SAPI voice provider" },
+    @{ Name = "play-tts-piper.ps1"; Desc = "Piper offline neural voice provider" },
+    @{ Name = "play-tts-sapi.ps1"; Desc = "Windows built-in SAPI voice provider" },
     @{ Name = "provider-manager.ps1"; Desc = "Switch between TTS providers" },
     @{ Name = "voice-manager-windows.ps1"; Desc = "Browse and select voice models" },
     @{ Name = "audio-cache-utils.ps1"; Desc = "Manage TTS audio file cache" },
@@ -765,11 +765,11 @@ try {
             }
         }
         "piper" {
-            & "$HooksDir\play-tts-windows-piper.ps1" $TestMessage | Out-Null
+            & "$HooksDir\play-tts-piper.ps1" $TestMessage | Out-Null
             Write-Ok "Piper TTS is working"
         }
         "sapi" {
-            & "$HooksDir\play-tts-windows-sapi.ps1" $TestMessage | Out-Null
+            & "$HooksDir\play-tts-sapi.ps1" $TestMessage | Out-Null
             Write-Ok "Windows SAPI is working"
         }
     }

package/src/console/app.js

@@ -14,7 +14,9 @@ import { fileURLToPath } from 'node:url';
 import { spawnSync, execFileSync } from 'node:child_process';
 import { NavigationService, TAB_ORDER } from '../services/navigation-service.js';
 import { setupNavigation } from './navigation.js';
-import { createPlaceholderTab, TAB_DISPLAY_LABELS, TAB_SHORTCUT_KEYS } from './tabs/placeholder-tab.js';
+import { createPlaceholderTab, TAB_DISPLAY_LABELS, TAB_SHORTCUT_KEYS, getTabLabel } from './tabs/placeholder-tab.js';
+import { LanguageService } from '../services/language-service.js';
+import { t } from '../i18n/strings.js';
 import { FOOTER_CONFIG, DEFAULT_FOOTER_COLOR } from './footer-config.js';
 import { createModalOverlay } from './modals/modal-overlay.js';
 import { BRAND_PINK } from './brand-colors.js';
@@ -169,7 +171,7 @@ export class AgentVibesConsole {
     });
 
     // Row 1: subtitle
-    blessed.text({
+    this._headerSubtitleText = blessed.text({
       parent: this.headerBox,
       top: 1,
       left: 2,
@@ -180,7 +182,7 @@ export class AgentVibesConsole {
     });
 
     // Row 1: Quit shortcut — left-anchored after "Customization Tool" (18 chars at left:2)
-    blessed.text({
+    this._headerQuitText = blessed.text({
       parent: this.headerBox,
       top: 1,
       left: 22,
@@ -291,9 +293,11 @@ export class AgentVibesConsole {
 
     // One box per tab — direct screen children at absolute top:3. No tag parsing, no wrapping.
     this._tabItems = {};
+    this._tabItemXOffsets = {};  // track x positions for label refresh
     let xOffset = 1;
     for (const id of TAB_ORDER) {
-      const label = TAB_DISPLAY_LABELS[id];
+      const lang = this._languageService?.getLang() ?? 'en';
+      const label = getTabLabel(id, lang);
       const shortcutKey = TAB_SHORTCUT_KEYS[id] || label[0];
       const text = ` [${shortcutKey}] ${label} `;
       const el = blessed.box({
@@ -304,11 +308,13 @@ export class AgentVibesConsole {
         height: 1,
         content: text,
         tags: false,
+        wrap: false,
         keys: true,
         focusable: true,
         style: { fg: COLORS.focusCyan, bg: COLORS.tabBarBg },
       });
       this._tabItems[id] = el;
+      this._tabItemXOffsets[id] = xOffset;
       xOffset += text.length + 1; // 1-space gap between tabs
     }
 
@@ -359,9 +365,8 @@ export class AgentVibesConsole {
       const el = this._tabItems[tabIds[i]];
 
       // Blinking block cursor: replace trailing space with █, toggle at 500ms
-      const _tabLabel     = TAB_DISPLAY_LABELS[tabIds[i]];
-      const _baseContent  = ` [${_tabLabel[0]}] ${_tabLabel} `;
-      const _blockContent = _baseContent.slice(0, -1) + '█';
+      // Always derive from current el.content so language changes are preserved.
+      const _getBaseContent = () => el.content.replace(/█$/, ' ');
       let _cursorInterval = null;
       let _cursorOn       = false;
 
@@ -369,18 +374,21 @@ export class AgentVibesConsole {
         el.style.fg = 'white';
         el.style.bg = '#9c27b0'; // purple — cursor on this tab item
         _cursorOn = true;
-        el.setContent(_blockContent);
+        const _base  = _getBaseContent();
+        const _block = _base.slice(0, -1) + '█';
+        el.setContent(_block);
         this.screen.render();
         if (_cursorInterval) { clearInterval(_cursorInterval); _cursorInterval = null; }
         _cursorInterval = setInterval(() => {
           _cursorOn = !_cursorOn;
-          el.setContent(_cursorOn ? _blockContent : _baseContent);
+          const b = _getBaseContent();
+          el.setContent(_cursorOn ? b.slice(0, -1) + '█' : b);
           this.screen.render();
         }, 500);
       });
       el.on('blur', () => {
         if (_cursorInterval) { clearInterval(_cursorInterval); _cursorInterval = null; }
-        el.setContent(_baseContent);
+        el.setContent(_getBaseContent());
         // navigationService set up after _createTabBar, but blur fires lazily — safe
         this._updateTabBar(this.navigationService?.getActiveTab() ?? tabIds[0]);
         this.screen.render();
@@ -474,13 +482,47 @@ export class AgentVibesConsole {
     }
   }
 
+  // ---------------------------------------------------------------------------
+  // Private: Refresh all chrome strings (header subtitle, tab bar labels) when lang changes
+
+  _refreshChrome(lang) {
+    // Update header subtitle "Customization Tool"
+    if (this._headerSubtitleText) {
+      this._headerSubtitleText.setContent(`{green-fg}${t(lang, 'customizationTool')}{/green-fg}`);
+    }
+    if (this._headerQuitText) {
+      this._headerQuitText.setContent(`{#ef9a9a-fg}${t(lang, 'quitLabel')}{/#ef9a9a-fg}`);
+    }
+
+    // Update tab bar item labels — resize and reposition to fit translated labels
+    let xOffset = 1;
+    for (const id of TAB_ORDER) {
+      const el = this._tabItems?.[id];
+      if (!el) continue;
+      const label = getTabLabel(id, lang);
+      const shortcutKey = TAB_SHORTCUT_KEYS[id] || label[0];
+      const text = ` [${shortcutKey}] ${label} `;
+      el.left = xOffset;
+      el.width = text.length;
+      el.setContent(text);
+      xOffset += text.length + 1;
+    }
+
+    // Update active tab's footer text if it supports language-aware footer
+    const activeId = this.navigationService?.getActiveTab();
+    if (activeId) this._updateContextFooter(activeId);
+
+    this.screen.render();
+  }
+
   // ---------------------------------------------------------------------------
   // Private: Render tab bar content string for given active tab
   // (kept as a pure helper for unit tests; real rendering uses _updateTabBar)
 
   _renderTabBarContent(activeTabId) {
+    const lang = this._languageService?.getLang() ?? 'en';
     return TAB_ORDER.map(id => {
-      const label = TAB_DISPLAY_LABELS[id];
+      const label = getTabLabel(id, lang);
       const shortcutKey = TAB_SHORTCUT_KEYS[id] || label[0];
       if (id === activeTabId) {
         return `{bold}{white-fg}[${shortcutKey}] ${label}{/white-fg}{/bold}`;
@@ -614,9 +656,14 @@ export class AgentVibesConsole {
     const providerService = new ProviderService(configService);
     this._configService = configService;
     this._providerService = providerService;
+    const languageService = new LanguageService();
+    this._languageService = languageService;
+    // Refresh UI chrome when language changes
+    languageService.onChange(lang => this._refreshChrome(lang));
     const services = {
       configService,
       providerService,
+      languageService,
       navigationService: this.navigationService,
       updateHeaderStatus: () => this._updateHeaderStatus(),
       focusMainTabBar: () => {

package/src/console/tabs/agents-tab.js

@@ -21,6 +21,7 @@ import {
 import { buildAudioEnv, detectWavPlayer } from '../audio-env.js';
 import { destroyList } from '../widgets/destroy-list.js';
 import { BRAND_PINK } from '../brand-colors.js';
+import { t } from '../../i18n/strings.js';
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 import os from 'node:os';
@@ -57,8 +58,8 @@ const COLORS = {
   linkFg:     'bright-cyan',
 };
 
-const FOOTER_TEXT_BMAD   = '[↑↓/jk] Navigate  [Space] Preview  [Enter] Configure  [A] Auto-assign  [B] Bulk  [X] Reset  [Q] Quit';
-const FOOTER_TEXT_NOBMAD = '[Tab] Switch Tab  [Q] Quit';
+const _FOOTER_BMAD_EN   = '[↑↓/jk] Navigate  [Space] Preview  [Enter] Configure  [A] Auto-assign  [B] Bulk  [X] Reset  [Q] Quit';
+const _FOOTER_NOBMAD_EN = '[Tab] Switch Tab  [Q] Quit';
 
 const _modalTitle = (text) => ` {${BRAND_PINK}-fg}${text}{/${BRAND_PINK}-fg} `;
 
@@ -85,53 +86,43 @@ function createTestStub() {
     hide: () => {},
     onFocus: () => {},
     onBlur: () => {},
-    getFooterText: () => FOOTER_TEXT_BMAD,
+    getFooterText: () => _FOOTER_BMAD_EN,
     getFooterColor: () => COLORS.footerBg,
   };
 }
 
 // ---------------------------------------------------------------------------
-// No-BMAD onboarding content
 
-const ONBOARDING_TEXT = `{bold}{#ce93d8-fg}🧙 BMAD Agents{/#ce93d8-fg}{/bold}
+/**
+ * Create the Agents tab component.
+ */
+export function createAgentsTab(screen, services) {
+  if (IS_TEST) return createTestStub();
+
+  const { configService, providerService, focusMainTabBar, navigationService, languageService } = services;
+  const _tl = (key) => languageService ? languageService.t(key) : t('en', key);
 
-{bold}What is BMAD?{/bold}
+  function _buildOnboardingText() {
+    return `{bold}{#ce93d8-fg}${_tl('bmadTitle')}{/#ce93d8-fg}{/bold}
 
-The BMad Method (Build More Architect Dreams) is an AI-driven development
-framework module within the BMad Method Ecosystem that helps you build
-software through the whole process from ideation and planning all the way
-through agentic implementation. It provides specialized AI agents, guided
-workflows, and intelligent planning that adapts to your project's
-complexity, whether you're fixing a bug or building an enterprise platform.
+{bold}${_tl('bmadWhatIsHeader')}{/bold}
 
-If you're comfortable working with AI coding assistants like Claude,
-Cursor, or GitHub Copilot, you're ready to get started.
+${_tl('bmadDesc')}
 
 
-{bold}Install BMAD in your project:{/bold}
+{bold}${_tl('bmadInstallHeader')}{/bold}
 
   {bright-cyan-fg}npx bmad-method install{/bright-cyan-fg}
 
 
-{bold}Learn more:{/bold}
+{bold}${_tl('bmadLearnMoreHeader')}{/bold}
 
   {bright-cyan-fg}https://docs.bmad-method.org/{/bright-cyan-fg}
   {bright-cyan-fg}https://github.com/bmad-code-org/BMAD-METHOD{/bright-cyan-fg}
 
 
-{#90a4ae-fg}Once BMAD is installed, this tab will show all your agents and let you
-customize each agent's voice, pretext, reverb, personality, and background
-music independently.{/#90a4ae-fg}`;
-
-// ---------------------------------------------------------------------------
-
-/**
- * Create the Agents tab component.
- */
-export function createAgentsTab(screen, services) {
-  if (IS_TEST) return createTestStub();
-
-  const { configService, providerService, focusMainTabBar, navigationService } = services;
+{#90a4ae-fg}${_tl('bmadInstalledNote')}{/#90a4ae-fg}`;
+  }
   const voiceStore = new AgentVoiceStore();
 
   // Capture cwd once at construction (L1 fix)
@@ -183,10 +174,14 @@ export function createAgentsTab(screen, services) {
     keys: true,
     vi: true,
     mouse: true,
-    content: ONBOARDING_TEXT,
+    content: _buildOnboardingText(),
     style: { fg: COLORS.labelFg, bg: COLORS.contentBg },
   });
 
+  onboardingBox.key(['escape'], () => {
+    if (typeof focusMainTabBar === 'function') { focusMainTabBar(); screen.render(); }
+  });
+
   // -------------------------------------------------------------------------
   // BMAD state — section header
 
@@ -486,20 +481,6 @@ export function createAgentsTab(screen, services) {
     }
   }
 
-  // -------------------------------------------------------------------------
-  // Resolve piper binary — shared helper to avoid duplication (#153)
-
-  function _resolvePiperBin() {
-    if (process.platform !== 'win32' || process.env.WSL_DISTRO_NAME) return 'piper';
-    const localAppData = process.env.LOCALAPPDATA ||
-      (process.env.USERPROFILE ? path.join(process.env.USERPROFILE, 'AppData', 'Local') : null);
-    if (localAppData) {
-      const exePath = path.join(localAppData, 'Programs', 'Piper', 'piper.exe');
-      if (fs.existsSync(exePath)) return exePath;
-    }
-    return 'piper';
-  }
-
   // -------------------------------------------------------------------------
   // Kill any playing preview
 
@@ -935,7 +916,16 @@ export function createAgentsTab(screen, services) {
       const tempWav = _secureTempWav('vp');
       const phrase = SAMPLE_PHRASES[Math.floor(Math.random() * SAMPLE_PHRASES.length)];
 
-      const _piperBin = _resolvePiperBin();
+      // Resolve piper binary (on Windows, find piper.exe)
+      let _piperBin = 'piper';
+      if (_isWin) {
+        const _lad = process.env.LOCALAPPDATA ||
+          (process.env.USERPROFILE ? path.join(process.env.USERPROFILE, 'AppData', 'Local') : null);
+        if (_lad) {
+          const _ep = path.join(_lad, 'Programs', 'Piper', 'piper.exe');
+          if (fs.existsSync(_ep)) _piperBin = _ep;
+        }
+      }
 
       const args = ['--model', voicePath, '--output_file', tempWav];
       if (_ms.speakerId != null) args.push('--speaker', String(_ms.speakerId));
@@ -1112,7 +1102,15 @@ export function createAgentsTab(screen, services) {
   /** Windows-native sample: piper.exe → wav → detectWavPlayer */
   function _sampleWithPiperDirect(gen, voiceId, phrase) {
     const _spawnEnv = buildAudioEnv();
-    const piperBin = _resolvePiperBin();
+
+    // Resolve piper binary
+    let piperBin = 'piper';
+    const localAppData = process.env.LOCALAPPDATA ||
+      (process.env.USERPROFILE ? path.join(process.env.USERPROFILE, 'AppData', 'Local') : null);
+    if (localAppData) {
+      const exePath = path.join(localAppData, 'Programs', 'Piper', 'piper.exe');
+      if (fs.existsSync(exePath)) piperBin = exePath;
+    }
 
     // Resolve voice model path
     const ms = parseMultiSpeaker(voiceId);
@@ -1138,7 +1136,6 @@ export function createAgentsTab(screen, services) {
     _playingProcess = piper;
 
     piper.on('exit', (code) => {
-      // Generation changed — another preview was triggered; clean up silently
       if (gen !== _playGeneration) {
         try { fs.unlinkSync(tempWav); } catch {}
         return;
@@ -1150,12 +1147,6 @@ export function createAgentsTab(screen, services) {
         return;
       }
 
-      // Re-check generation after piper exit to close the race window (#154)
-      if (gen !== _playGeneration) {
-        try { fs.unlinkSync(tempWav); } catch {}
-        return;
-      }
-
       // Play the synthesized wav
       const wavPlayer = detectWavPlayer(_spawnEnv);
       if (!wavPlayer) {
@@ -1184,7 +1175,6 @@ export function createAgentsTab(screen, services) {
 
     piper.on('error', () => {
       if (gen === _playGeneration) { _playingProcess = null; _stopSpinner(); }
-      try { fs.unlinkSync(tempWav); } catch {}
     });
   }
 
@@ -1202,12 +1192,10 @@ export function createAgentsTab(screen, services) {
 
   // Common first-name → gender map for gender-aware auto-assign.
   // Only needs to cover names likely used as BMAD agent display names.
-  // Ambiguous names (sam, charlie, dana, max, pat, etc.) are intentionally
-  // omitted so they fall through to the gender-neutral 'other' pool (#156).
   const _NAME_GENDER = {
     // Female
     amelia: 'Female', amy: 'Female', anna: 'Female', betty: 'Female',
-    claire: 'Female', emma: 'Female', faye: 'Female',
+    claire: 'Female', dana: 'Female', emma: 'Female', faye: 'Female',
     grace: 'Female', heather: 'Female', ivy: 'Female', jane: 'Female',
     jenny: 'Female', julia: 'Female', kate: 'Female', laura: 'Female',
     lily: 'Female', maria: 'Female', mary: 'Female', nina: 'Female',
@@ -1216,12 +1204,12 @@ export function createAgentsTab(screen, services) {
     wendy: 'Female', zoe: 'Female',
     // Male
     alan: 'Male', barry: 'Male', bob: 'Male', carl: 'Male',
-    dan: 'Male', david: 'Male', eric: 'Male',
+    charlie: 'Male', dan: 'Male', david: 'Male', eric: 'Male',
     frank: 'Male', george: 'Male', hank: 'Male', jack: 'Male',
     james: 'Male', joe: 'Male', john: 'Male', kevin: 'Male',
-    leo: 'Male', mark: 'Male', murat: 'Male',
+    leo: 'Male', mark: 'Male', max: 'Male', murat: 'Male',
     nick: 'Male', oscar: 'Male', paul: 'Male', ray: 'Male',
-    ryan: 'Male', saif: 'Male', steve: 'Male',
+    ryan: 'Male', saif: 'Male', sam: 'Male', steve: 'Male',
     tom: 'Male', victor: 'Male', winston: 'Male', zach: 'Male',
   };
 
@@ -1250,17 +1238,15 @@ export function createAgentsTab(screen, services) {
     // Assign matching-gender voices first, then fall back to any available
     function assignGroup(agents, preferredPool, fallbackPools) {
       const allPools = [preferredPool, ...fallbackPools];
-      let reuseIdx = 0;
       agents.forEach(agent => {
         let voice = null;
         for (const pool of allPools) {
           voice = pool.find(v => !usedVoices.has(v));
           if (voice) break;
         }
-        // If all unique voices exhausted, round-robin reuse from preferred pool
+        // If all unique voices exhausted, reuse from preferred pool
         if (!voice && preferredPool.length > 0) {
-          voice = preferredPool[reuseIdx % preferredPool.length];
-          reuseIdx++;
+          voice = preferredPool[usedVoices.size % preferredPool.length];
         }
         if (voice) {
           usedVoices.add(voice);
@@ -1642,6 +1628,16 @@ export function createAgentsTab(screen, services) {
     if (typeof focusMainTabBar === 'function') { focusMainTabBar(); screen.render(); }
   });
 
+  // -------------------------------------------------------------------------
+  // Language change handler
+
+  if (languageService) {
+    languageService.onChange(() => {
+      onboardingBox.setContent(_buildOnboardingText());
+      screen.render();
+    });
+  }
+
   // -------------------------------------------------------------------------
   // Tab Component Contract
 
@@ -1674,7 +1670,7 @@ export function createAgentsTab(screen, services) {
     },
 
     getFooterText() {
-      return _bmadDetected ? FOOTER_TEXT_BMAD : FOOTER_TEXT_NOBMAD;
+      return _bmadDetected ? _tl('bmadFooterBmad') : _tl('bmadFooterNobmad');
     },
 
     getFooterColor() {

package/src/console/tabs/help-tab.js

@@ -8,6 +8,8 @@
  * Features: keyboard shortcuts reference, two sections, [/] search.
  */
 
+import { t } from '../../i18n/strings.js';
+
 const IS_TEST = process.env.AGENTVIBES_TEST_MODE === 'true';
 
 let blessed;
@@ -28,65 +30,60 @@ const COLORS = {
   footerBg:   '#607d8b',  // Gray — Help tab footer
 };
 
-const FOOTER_TEXT = '[↑↓/jk] Scroll  [/] Search  [PgUp/PgDn] Page  [S/V/M/A/R] Tab  [Q] Quit';
-
 // ---------------------------------------------------------------------------
-// Keyboard shortcuts data
-
-const SHORTCUT_SECTIONS = Object.freeze([
-  {
-    title: 'Global Shortcuts',
-    shortcuts: [
-      { key: 'Q',         desc: 'Quit the console' },
-      { key: 'Ctrl+C',    desc: 'Force quit' },
-      { key: 'S',         desc: 'Switch to Settings tab' },
-      { key: 'V',         desc: 'Switch to Voices tab' },
-      { key: 'M',         desc: 'Switch to Music tab' },
-      { key: 'R',         desc: 'Switch to Readme tab' },
-      { key: 'H',         desc: 'Switch to Help tab' },
-      { key: 'I',         desc: 'Switch to Install tab' },
-      { key: 'Esc',       desc: 'Close modal / go back' },
-    ],
-  },
-  {
-    title: 'Navigation Shortcuts',
-    shortcuts: [
-      { key: '↑↓ / j k',  desc: 'Navigate lists' },
-      { key: 'Enter',      desc: 'Select / activate' },
-      { key: 'Space',      desc: 'Toggle / preview' },
-      { key: 'Tab',        desc: 'Next button' },
-      { key: 'Shift+Tab',  desc: 'Previous button' },
-      { key: '/',          desc: 'Open search/filter' },
-      { key: 'F',          desc: 'Toggle favorites filter (Voices/Music)' },
-      { key: '*',          desc: 'Toggle favorite (Music tab)' },
-      { key: 'M',          desc: 'Toggle music on/off (Music tab)' },
-
-    ],
-  },
-  {
-    title: 'Tab Color Guide',
-    shortcuts: [
-      { key: 'Blue   (#2196f3)',  desc: 'Settings tab footer' },
-      { key: 'Teal   (#00695c)',  desc: 'Voices tab footer' },
-      { key: 'Orange (#ff9800)',  desc: 'Music tab footer' },
-
-      { key: 'Dark   (#455a64)',  desc: 'Readme tab footer' },
-      { key: 'Gray   (#607d8b)',  desc: 'Help tab footer' },
-      { key: 'Indigo (#3f51b5)',  desc: 'Install tab footer' },
-    ],
-  },
-]);
 
 /**
  * Return all shortcut sections.
  * @returns {{ title: string, shortcuts: { key: string, desc: string }[] }[]}
  */
 export function getShortcutSections() {
-  return [...SHORTCUT_SECTIONS];
+  return [
+    {
+      title: 'Global Shortcuts',
+      shortcuts: [
+        { key: 'Q',   desc: 'Quit the console' },
+        { key: 'Ctrl+C', desc: 'Force quit' },
+        { key: 'S',   desc: 'Switch to Settings tab' },
+        { key: 'V',   desc: 'Switch to Voices tab' },
+        { key: 'M',   desc: 'Switch to Music tab' },
+        { key: 'R',   desc: 'Switch to Readme tab' },
+        { key: 'H',   desc: 'Switch to Help tab' },
+        { key: 'I',   desc: 'Switch to Install tab' },
+        { key: 'Esc', desc: 'Close modal / go back' },
+      ],
+    },
+    {
+      title: 'Navigation Shortcuts',
+      shortcuts: [
+        { key: '↑↓ / j k', desc: 'Navigate lists' },
+        { key: 'Enter',     desc: 'Select / activate' },
+        { key: 'Space',     desc: 'Toggle / preview' },
+        { key: 'Tab',       desc: 'Next button' },
+        { key: 'Shift+Tab', desc: 'Previous button' },
+        { key: '/',         desc: 'Open search/filter' },
+        { key: 'F',         desc: 'Toggle favorites filter (Voices/Music)' },
+        { key: '*',         desc: 'Toggle favorite (Music tab)' },
+        { key: 'M',         desc: 'Toggle music on/off (Music tab)' },
+      ],
+    },
+    {
+      title: 'Tab Color Guide',
+      shortcuts: [
+        { key: 'Blue   (#2196f3)', desc: 'Settings tab footer' },
+        { key: 'Teal   (#00695c)', desc: 'Voices tab footer' },
+        { key: 'Orange (#ff9800)', desc: 'Music tab footer' },
+        { key: 'Dark   (#455a64)', desc: 'Readme tab footer' },
+        { key: 'Gray   (#607d8b)', desc: 'Help tab footer' },
+        { key: 'Indigo (#3f51b5)', desc: 'Install tab footer' },
+      ],
+    },
+  ];
 }
 
 // ---------------------------------------------------------------------------
 
+const _FOOTER_TEXT_EN = '[↑↓/jk] Scroll  [/] Search  [PgUp/PgDn] Page  [S/V/M/A/R] Tab  [Q] Quit';
+
 function createTestStub() {
   return {
     box: {},
@@ -94,7 +91,7 @@ function createTestStub() {
     hide: () => {},
     onFocus: () => {},
     onBlur: () => {},
-    getFooterText: () => FOOTER_TEXT,
+    getFooterText: () => _FOOTER_TEXT_EN,
     getFooterColor: () => COLORS.footerBg,
   };
 }
@@ -111,7 +108,52 @@ function createTestStub() {
 export function createHelpTab(screen, services) {
   if (IS_TEST) return createTestStub();
 
-  const { focusMainTabBar } = services;
+  const { focusMainTabBar, languageService } = services;
+  const _tl = (key) => languageService ? languageService.t(key) : t('en', key);
+
+  function _buildSections() {
+    return [
+      {
+        title: _tl('helpSectionGlobal'),
+        shortcuts: [
+          { key: 'Q',         desc: _tl('helpQuit') },
+          { key: 'Ctrl+C',    desc: _tl('helpForceQuit') },
+          { key: 'S',         desc: _tl('helpSwitchSettings') },
+          { key: 'V',         desc: _tl('helpSwitchVoices') },
+          { key: 'M',         desc: _tl('helpSwitchMusic') },
+          { key: 'R',         desc: _tl('helpSwitchReadme') },
+          { key: 'H',         desc: _tl('helpSwitchHelp') },
+          { key: 'I',         desc: _tl('helpSwitchInstall') },
+          { key: 'Esc',       desc: _tl('helpCloseModal') },
+        ],
+      },
+      {
+        title: _tl('helpSectionNavigation'),
+        shortcuts: [
+          { key: '↑↓ / j k',  desc: _tl('helpNavigateLists') },
+          { key: 'Enter',      desc: _tl('helpSelectActivate') },
+          { key: 'Space',      desc: _tl('helpTogglePreview') },
+          { key: 'Tab',        desc: _tl('helpNextButton') },
+          { key: 'Shift+Tab',  desc: _tl('helpPrevButton') },
+          { key: '/',          desc: _tl('helpOpenSearch') },
+          { key: 'F',          desc: _tl('helpToggleFavFilter') },
+          { key: '*',          desc: _tl('helpToggleFav') },
+          { key: 'M',          desc: _tl('helpToggleMusic') },
+        ],
+      },
+      {
+        title: _tl('helpSectionColors'),
+        shortcuts: [
+          { key: 'Blue   (#2196f3)', desc: _tl('helpColorSettings') },
+          { key: 'Teal   (#00695c)', desc: _tl('helpColorVoices') },
+          { key: 'Orange (#ff9800)', desc: _tl('helpColorMusic') },
+          { key: 'Dark   (#455a64)', desc: _tl('helpColorReadme') },
+          { key: 'Gray   (#607d8b)', desc: _tl('helpColorHelp') },
+          { key: 'Indigo (#3f51b5)', desc: _tl('helpColorInstall') },
+        ],
+      },
+    ];
+  }
 
   // -------------------------------------------------------------------------
   // Container
@@ -133,7 +175,7 @@ export function createHelpTab(screen, services) {
 
   function _buildContent(filterText) {
     const lines = [];
-    for (const section of SHORTCUT_SECTIONS) {
+    for (const section of _buildSections()) {
       lines.push(`{bold}{#546e7a-fg}── ${section.title} ${'─'.repeat(Math.max(0, 60 - section.title.length))}{/#546e7a-fg}{/bold}`);
       for (const { key, desc } of section.shortcuts) {
         const displayKey = key.padEnd(20);
@@ -183,11 +225,11 @@ export function createHelpTab(screen, services) {
     style: { fg: COLORS.keyFg, bg: '#1a3a5c', focus: { bg: '#245a80' } },
   });
 
-  blessed.text({
+  const searchLabel = blessed.text({
     parent: box,
     bottom: 2,
     left: 2,
-    content: 'Search:',
+    content: _tl('helpSearchLabel'),
     style: { fg: COLORS.descFg, bg: COLORS.contentBg },
   });
 
@@ -226,6 +268,17 @@ export function createHelpTab(screen, services) {
     if (typeof focusMainTabBar === 'function') { focusMainTabBar(); screen.render(); }
   });
 
+  // -------------------------------------------------------------------------
+  // Language change handler
+
+  if (languageService) {
+    languageService.onChange(() => {
+      scrollBox.setContent(_buildContent(''));
+      searchLabel.setContent(_tl('helpSearchLabel'));
+      screen.render();
+    });
+  }
+
   // -------------------------------------------------------------------------
   // Tab Component Contract
 
@@ -251,7 +304,7 @@ export function createHelpTab(screen, services) {
     onBlur() {},
 
     getFooterText() {
-      return FOOTER_TEXT;
+      return _tl('helpFooter');
     },
 
     getFooterColor() {