@butlerw/vellum 0.1.0

package/src/tui/i18n/__tests__/locale-detection.test.ts

@@ -0,0 +1,250 @@
+/**
+ * Locale Detection Unit Tests
+ *
+ * Tests for system locale detection:
+ * - parseLocaleString() parsing POSIX locale formats
+ * - detectSystemLocale() with env var mocking
+ * - Priority chain: LC_ALL > LC_MESSAGES > LANG
+ *
+ * @module tui/i18n/__tests__/locale-detection
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { detectSystemLocale, parseLocaleString } from "../locale-detection.js";
+
+// =============================================================================
+// T021: parseLocaleString Tests
+// =============================================================================
+
+describe("parseLocaleString", () => {
+  describe("valid locale strings", () => {
+    it("parses 'zh_CN.UTF-8' correctly", () => {
+      const result = parseLocaleString("zh_CN.UTF-8");
+      expect(result).toEqual({ language: "zh", territory: "CN" });
+    });
+
+    it("parses 'en_US' correctly", () => {
+      const result = parseLocaleString("en_US");
+      expect(result).toEqual({ language: "en", territory: "US" });
+    });
+
+    it("parses language-only format 'en'", () => {
+      const result = parseLocaleString("en");
+      expect(result).toEqual({ language: "en" });
+    });
+
+    it("parses language-only format 'zh'", () => {
+      const result = parseLocaleString("zh");
+      expect(result).toEqual({ language: "zh" });
+    });
+
+    it("parses locale with encoding 'en_US.UTF-8'", () => {
+      const result = parseLocaleString("en_US.UTF-8");
+      expect(result).toEqual({ language: "en", territory: "US" });
+    });
+
+    it("parses locale with modifier 'en_US.UTF-8@euro'", () => {
+      const result = parseLocaleString("en_US.UTF-8@euro");
+      expect(result).toEqual({ language: "en", territory: "US" });
+    });
+
+    it("handles uppercase language codes by lowercasing", () => {
+      const result = parseLocaleString("EN_US");
+      expect(result).toEqual({ language: "en", territory: "US" });
+    });
+
+    it("handles lowercase territory codes by uppercasing", () => {
+      const result = parseLocaleString("en_us");
+      expect(result).toEqual({ language: "en", territory: "US" });
+    });
+
+    it("parses three-letter language codes", () => {
+      const result = parseLocaleString("deu_DE");
+      expect(result).toEqual({ language: "deu", territory: "DE" });
+    });
+  });
+
+  describe("invalid locale strings", () => {
+    it("returns null for 'C'", () => {
+      expect(parseLocaleString("C")).toBeNull();
+    });
+
+    it("returns null for 'POSIX'", () => {
+      expect(parseLocaleString("POSIX")).toBeNull();
+    });
+
+    it("returns null for empty string", () => {
+      expect(parseLocaleString("")).toBeNull();
+    });
+
+    it("returns null for whitespace-only string", () => {
+      expect(parseLocaleString("   ")).toBeNull();
+    });
+
+    it("returns null for single character", () => {
+      expect(parseLocaleString("e")).toBeNull();
+    });
+
+    it("handles whitespace around valid locale", () => {
+      const result = parseLocaleString("  en_US  ");
+      expect(result).toEqual({ language: "en", territory: "US" });
+    });
+  });
+});
+
+// =============================================================================
+// T021: detectSystemLocale Tests
+// =============================================================================
+
+describe("detectSystemLocale", () => {
+  const originalEnv = process.env;
+
+  beforeEach(() => {
+    // Reset process.env before each test
+    vi.resetModules();
+    process.env = { ...originalEnv };
+    // Clear all locale-related env vars
+    delete process.env.LC_ALL;
+    delete process.env.LC_MESSAGES;
+    delete process.env.LANG;
+    delete process.env.VELLUM_LANGUAGE;
+  });
+
+  afterEach(() => {
+    process.env = originalEnv;
+  });
+
+  describe("priority chain", () => {
+    it("LC_ALL has highest priority", () => {
+      process.env.LC_ALL = "zh_CN.UTF-8";
+      process.env.LC_MESSAGES = "en_US.UTF-8";
+      process.env.LANG = "en_US.UTF-8";
+
+      const result = detectSystemLocale();
+
+      expect(result.locale).toBe("zh");
+      expect(result.source).toBe("LC_ALL");
+    });
+
+    it("LC_MESSAGES is second priority when LC_ALL not set", () => {
+      process.env.LC_MESSAGES = "zh_CN.UTF-8";
+      process.env.LANG = "en_US.UTF-8";
+
+      const result = detectSystemLocale();
+
+      expect(result.locale).toBe("zh");
+      expect(result.source).toBe("LC_MESSAGES");
+    });
+
+    it("LANG is third priority when LC_ALL and LC_MESSAGES not set", () => {
+      process.env.LANG = "zh_CN.UTF-8";
+
+      const result = detectSystemLocale();
+
+      expect(result.locale).toBe("zh");
+      expect(result.source).toBe("LANG");
+    });
+
+    it("VELLUM_LANGUAGE is checked after POSIX vars", () => {
+      process.env.VELLUM_LANGUAGE = "zh";
+
+      const result = detectSystemLocale();
+
+      expect(result.locale).toBe("zh");
+      expect(result.source).toBe("VELLUM_LANGUAGE");
+    });
+
+    it("skips invalid locale in LC_ALL and checks next", () => {
+      process.env.LC_ALL = "C";
+      process.env.LANG = "zh_CN.UTF-8";
+
+      const result = detectSystemLocale();
+
+      expect(result.locale).toBe("zh");
+      expect(result.source).toBe("LANG");
+    });
+  });
+
+  describe("supported locale detection", () => {
+    it("detects English locale from LANG", () => {
+      process.env.LANG = "en_US.UTF-8";
+
+      const result = detectSystemLocale();
+
+      expect(result.locale).toBe("en");
+      expect(result.source).toBe("LANG");
+    });
+
+    it("detects Chinese locale from LANG", () => {
+      process.env.LANG = "zh_CN.UTF-8";
+
+      const result = detectSystemLocale();
+
+      expect(result.locale).toBe("zh");
+      expect(result.source).toBe("LANG");
+    });
+
+    it("returns null locale for unsupported language", () => {
+      process.env.LANG = "fr_FR.UTF-8";
+
+      const result = detectSystemLocale();
+
+      // May return default on Windows or null on other platforms
+      if (process.platform === "win32") {
+        expect(result.locale).toBe("en");
+        expect(result.source).toBeNull();
+      } else {
+        expect(result.locale).toBeNull();
+        expect(result.source).toBeNull();
+      }
+    });
+  });
+
+  describe("edge cases", () => {
+    it("returns appropriate result when no env vars set", () => {
+      const result = detectSystemLocale();
+
+      // Windows returns default, others return null
+      if (process.platform === "win32") {
+        expect(result.locale).toBe("en");
+        expect(result.source).toBeNull();
+      } else {
+        expect(result.locale).toBeNull();
+        expect(result.source).toBeNull();
+      }
+    });
+
+    it("handles empty env var values", () => {
+      process.env.LC_ALL = "";
+      process.env.LANG = "en_US.UTF-8";
+
+      const result = detectSystemLocale();
+
+      expect(result.locale).toBe("en");
+      expect(result.source).toBe("LANG");
+    });
+
+    it("validates VELLUM_LANGUAGE against supported locales", () => {
+      process.env.VELLUM_LANGUAGE = "invalid";
+
+      const result = detectSystemLocale();
+
+      // Should not use invalid VELLUM_LANGUAGE
+      if (process.platform === "win32") {
+        expect(result.locale).toBe("en");
+      } else {
+        expect(result.locale).toBeNull();
+      }
+    });
+
+    it("accepts valid VELLUM_LANGUAGE", () => {
+      process.env.VELLUM_LANGUAGE = "en";
+
+      const result = detectSystemLocale();
+
+      expect(result.locale).toBe("en");
+      expect(result.source).toBe("VELLUM_LANGUAGE");
+    });
+  });
+});

package/src/tui/i18n/__tests__/settings-integration.test.ts

@@ -0,0 +1,262 @@
+/**
+ * Settings Integration Unit Tests
+ *
+ * Tests for language preference storage:
+ * - getSavedLanguage() retrieval
+ * - saveLanguage() persistence
+ * - clearSavedLanguage() removal
+ * - File system mocking for all operations
+ *
+ * @module tui/i18n/__tests__/settings-integration
+ */
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { clearSavedLanguage, getSavedLanguage, saveLanguage } from "../settings-integration.js";
+
+// Mock the fs module
+vi.mock("node:fs");
+vi.mock("node:os");
+
+// =============================================================================
+// Test Setup
+// =============================================================================
+
+const mockHomedir = "/mock/home";
+const mockSettingsDir = path.join(mockHomedir, ".vellum");
+const mockSettingsPath = path.join(mockSettingsDir, "settings.json");
+
+describe("settings-integration", () => {
+  beforeEach(() => {
+    vi.resetAllMocks();
+    vi.mocked(os.homedir).mockReturnValue(mockHomedir);
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  // ===========================================================================
+  // T022: getSavedLanguage Tests
+  // ===========================================================================
+
+  describe("getSavedLanguage", () => {
+    it("returns undefined when settings file does not exist", () => {
+      vi.mocked(fs.existsSync).mockReturnValue(false);
+
+      const result = getSavedLanguage();
+
+      expect(result).toBeUndefined();
+      expect(fs.existsSync).toHaveBeenCalledWith(mockSettingsPath);
+    });
+
+    it("returns locale when settings has valid language", () => {
+      vi.mocked(fs.existsSync).mockReturnValue(true);
+      vi.mocked(fs.readFileSync).mockReturnValue(JSON.stringify({ language: "zh" }));
+
+      const result = getSavedLanguage();
+
+      expect(result).toBe("zh");
+    });
+
+    it("returns English locale when settings has 'en'", () => {
+      vi.mocked(fs.existsSync).mockReturnValue(true);
+      vi.mocked(fs.readFileSync).mockReturnValue(JSON.stringify({ language: "en" }));
+
+      const result = getSavedLanguage();
+
+      expect(result).toBe("en");
+    });
+
+    it("returns undefined on corrupted JSON (no throw)", () => {
+      vi.mocked(fs.existsSync).mockReturnValue(true);
+      vi.mocked(fs.readFileSync).mockReturnValue("{ invalid json }");
+
+      const result = getSavedLanguage();
+
+      expect(result).toBeUndefined();
+    });
+
+    it("returns undefined when language key is missing", () => {
+      vi.mocked(fs.existsSync).mockReturnValue(true);
+      vi.mocked(fs.readFileSync).mockReturnValue(JSON.stringify({ otherKey: "value" }));
+
+      const result = getSavedLanguage();
+
+      expect(result).toBeUndefined();
+    });
+
+    it("returns undefined for unsupported locale in settings", () => {
+      vi.mocked(fs.existsSync).mockReturnValue(true);
+      vi.mocked(fs.readFileSync).mockReturnValue(JSON.stringify({ language: "fr" }));
+
+      const result = getSavedLanguage();
+
+      expect(result).toBeUndefined();
+    });
+
+    it("returns undefined on file read error (no throw)", () => {
+      vi.mocked(fs.existsSync).mockReturnValue(true);
+      vi.mocked(fs.readFileSync).mockImplementation(() => {
+        throw new Error("Permission denied");
+      });
+
+      const result = getSavedLanguage();
+
+      expect(result).toBeUndefined();
+    });
+
+    it("returns undefined when settings is an array (invalid structure)", () => {
+      vi.mocked(fs.existsSync).mockReturnValue(true);
+      vi.mocked(fs.readFileSync).mockReturnValue(JSON.stringify(["en"]));
+
+      const result = getSavedLanguage();
+
+      expect(result).toBeUndefined();
+    });
+
+    it("returns undefined when settings is null (invalid structure)", () => {
+      vi.mocked(fs.existsSync).mockReturnValue(true);
+      vi.mocked(fs.readFileSync).mockReturnValue("null");
+
+      const result = getSavedLanguage();
+
+      expect(result).toBeUndefined();
+    });
+  });
+
+  // ===========================================================================
+  // T022: saveLanguage Tests
+  // ===========================================================================
+
+  describe("saveLanguage", () => {
+    it("creates settings file with language when no file exists", () => {
+      vi.mocked(fs.existsSync).mockImplementation((p) => {
+        if (p === mockSettingsPath) return false;
+        if (p === mockSettingsDir) return false;
+        return false;
+      });
+
+      saveLanguage("zh");
+
+      expect(fs.mkdirSync).toHaveBeenCalledWith(mockSettingsDir, { recursive: true });
+      expect(fs.writeFileSync).toHaveBeenCalledWith(
+        mockSettingsPath,
+        JSON.stringify({ language: "zh" }, null, 2),
+        "utf-8"
+      );
+    });
+
+    it("updates existing settings file preserving other keys", () => {
+      vi.mocked(fs.existsSync).mockImplementation((p) => {
+        if (p === mockSettingsPath) return true;
+        if (p === mockSettingsDir) return true;
+        return false;
+      });
+      vi.mocked(fs.readFileSync).mockReturnValue(
+        JSON.stringify({ otherKey: "value", language: "en" })
+      );
+
+      saveLanguage("zh");
+
+      expect(fs.writeFileSync).toHaveBeenCalledWith(
+        mockSettingsPath,
+        JSON.stringify({ otherKey: "value", language: "zh" }, null, 2),
+        "utf-8"
+      );
+    });
+
+    it("creates directory if it does not exist", () => {
+      vi.mocked(fs.existsSync).mockImplementation((p) => {
+        if (p === mockSettingsPath) return false;
+        if (p === mockSettingsDir) return false;
+        return false;
+      });
+
+      saveLanguage("en");
+
+      expect(fs.mkdirSync).toHaveBeenCalledWith(mockSettingsDir, { recursive: true });
+    });
+
+    it("handles write errors gracefully (no throw)", () => {
+      vi.mocked(fs.existsSync).mockReturnValue(false);
+      vi.mocked(fs.mkdirSync).mockImplementation(() => {
+        throw new Error("Permission denied");
+      });
+
+      // Should not throw
+      expect(() => saveLanguage("zh")).not.toThrow();
+    });
+  });
+
+  // ===========================================================================
+  // T022: clearSavedLanguage Tests
+  // ===========================================================================
+
+  describe("clearSavedLanguage", () => {
+    it("removes language key from settings", () => {
+      vi.mocked(fs.existsSync).mockReturnValue(true);
+      vi.mocked(fs.readFileSync).mockReturnValue(
+        JSON.stringify({ language: "zh", otherKey: "value" })
+      );
+
+      clearSavedLanguage();
+
+      expect(fs.writeFileSync).toHaveBeenCalledWith(
+        mockSettingsPath,
+        JSON.stringify({ otherKey: "value" }, null, 2),
+        "utf-8"
+      );
+    });
+
+    it("does nothing when settings file does not exist", () => {
+      vi.mocked(fs.existsSync).mockReturnValue(false);
+
+      clearSavedLanguage();
+
+      expect(fs.writeFileSync).not.toHaveBeenCalled();
+    });
+
+    it("preserves other settings when clearing language", () => {
+      vi.mocked(fs.existsSync).mockReturnValue(true);
+      vi.mocked(fs.readFileSync).mockReturnValue(
+        JSON.stringify({
+          language: "zh",
+          theme: "dark",
+          customSetting: 123,
+        })
+      );
+
+      clearSavedLanguage();
+
+      expect(fs.writeFileSync).toHaveBeenCalledWith(
+        mockSettingsPath,
+        JSON.stringify({ theme: "dark", customSetting: 123 }, null, 2),
+        "utf-8"
+      );
+    });
+
+    it("handles corrupted JSON gracefully (no throw)", () => {
+      vi.mocked(fs.existsSync).mockReturnValue(true);
+      vi.mocked(fs.readFileSync).mockReturnValue("{ invalid }");
+
+      // Should not throw
+      expect(() => clearSavedLanguage()).not.toThrow();
+      expect(fs.writeFileSync).not.toHaveBeenCalled();
+    });
+
+    it("does nothing when settings has no language key", () => {
+      vi.mocked(fs.existsSync).mockReturnValue(true);
+      vi.mocked(fs.readFileSync).mockReturnValue(JSON.stringify({ otherKey: "value" }));
+
+      clearSavedLanguage();
+
+      // Still writes since we destructure and create new object
+      expect(fs.writeFileSync).toHaveBeenCalled();
+    });
+  });
+});

package/src/tui/i18n/index.ts

@@ -0,0 +1,72 @@
+/**
+ * TUI i18n Module
+ *
+ * Internationalization support for TUI components.
+ *
+ * @module tui/i18n
+ */
+
+// Initialization
+export type { ResolvedLocale, ResolvedLocaleSource, ResolveLocaleOptions } from "./init.js";
+export { initI18n, resolveLocale } from "./init.js";
+export type { LanguageInfo, LocaleCode } from "./language-config.js";
+// Language configuration
+export {
+  DEFAULT_LOCALE,
+  getAvailableLocales,
+  getLanguageDisplayName,
+  isLocaleSupported,
+  LANGUAGES,
+  SUPPORTED_LOCALES,
+} from "./language-config.js";
+// Locale detection
+export type { DetectedLocale, LocaleSource, ParsedLocale } from "./locale-detection.js";
+export { detectSystemLocale, parseLocaleString } from "./locale-detection.js";
+// Settings integration
+export {
+  clearSavedLanguage,
+  type DiffViewMode,
+  getAlternateBufferEnabled,
+  getBannerSeen,
+  getDiffViewMode,
+  getModeFromSettings,
+  getModelSettings,
+  getSavedLanguage,
+  getThemeFromSettings,
+  getThinkingDisplayMode,
+  getThinkingSettings,
+  getUISettings,
+  loadSettings,
+  type ModelSettings,
+  saveLanguage,
+  saveSettings,
+  saveUserSetting,
+  setAlternateBufferEnabled,
+  setBannerSeen,
+  setDiffViewMode,
+  setModeInSettings,
+  setModelSettings,
+  setThemeInSettings,
+  setThinkingDisplayMode,
+  setThinkingSettings,
+  type ThinkingDisplayMode,
+  type ThinkingSettings,
+  type UISettings,
+  type VellumSettings,
+} from "./settings-integration.js";
+
+// Hook and utilities
+export {
+  getGlobalLocale,
+  setGlobalLocale,
+  translate,
+  useTUITranslation,
+} from "./tui-namespace.js";
+
+// Types
+export type {
+  TranslationFunction,
+  TUITranslationKey,
+  TUITranslations,
+  UseTUITranslationReturn,
+} from "./types.js";