@butlerw/vellum 0.1.0

package/src/tui/i18n/init.ts

@@ -0,0 +1,131 @@
+/**
+ * i18n Initialization Module
+ *
+ * Provides locale resolution and initialization functions.
+ * Implements the priority chain for determining the active locale.
+ *
+ * @module tui/i18n/init
+ */
+
+import { DEFAULT_LOCALE, isLocaleSupported, type LocaleCode } from "./language-config.js";
+import { detectSystemLocale } from "./locale-detection.js";
+import { getSavedLanguage } from "./settings-integration.js";
+import { setGlobalLocale } from "./tui-namespace.js";
+
+/**
+ * Options for resolving the locale.
+ */
+export interface ResolveLocaleOptions {
+  /** CLI --language flag value */
+  cliLanguage?: string;
+}
+
+/**
+ * Source of the resolved locale.
+ */
+export type ResolvedLocaleSource = "cli-flag" | "env-var" | "settings" | "system" | "default";
+
+/**
+ * Result of locale resolution.
+ */
+export interface ResolvedLocale {
+  /** The resolved locale code */
+  locale: LocaleCode;
+  /** Source that provided the locale */
+  source: ResolvedLocaleSource;
+}
+
+/**
+ * Resolve the locale to use based on priority chain.
+ *
+ * Priority order (highest to lowest):
+ * 1. CLI flag (`options.cliLanguage`) → source: "cli-flag"
+ * 2. VELLUM_LANGUAGE environment variable → source: "env-var"
+ * 3. Saved settings (user preference) → source: "settings"
+ * 4. System locale detection → source: "system"
+ * 5. Default locale (en) → source: "default"
+ *
+ * Each source is validated with `isLocaleSupported()` before use.
+ *
+ * @param options - Resolution options
+ * @returns Resolved locale with source information
+ *
+ * @example
+ * ```typescript
+ * // With CLI flag
+ * resolveLocale({ cliLanguage: "zh" });
+ * // { locale: "zh", source: "cli-flag" }
+ *
+ * // Without options, uses priority chain
+ * resolveLocale();
+ * // { locale: "en", source: "settings" } // if saved in settings
+ * ```
+ */
+export function resolveLocale(options?: ResolveLocaleOptions): ResolvedLocale {
+  // 1. CLI flag (highest priority)
+  if (options?.cliLanguage && isLocaleSupported(options.cliLanguage)) {
+    return {
+      locale: options.cliLanguage as LocaleCode,
+      source: "cli-flag",
+    };
+  }
+
+  // 2. VELLUM_LANGUAGE environment variable
+  const envLocale = process.env.VELLUM_LANGUAGE;
+  if (envLocale && isLocaleSupported(envLocale)) {
+    return {
+      locale: envLocale as LocaleCode,
+      source: "env-var",
+    };
+  }
+
+  // 3. Saved settings
+  const savedLocale = getSavedLanguage();
+  if (savedLocale && isLocaleSupported(savedLocale)) {
+    return {
+      locale: savedLocale,
+      source: "settings",
+    };
+  }
+
+  // 4. System locale detection
+  const systemDetected = detectSystemLocale();
+  if (systemDetected.locale && isLocaleSupported(systemDetected.locale)) {
+    return {
+      locale: systemDetected.locale,
+      source: "system",
+    };
+  }
+
+  // 5. Default locale (lowest priority)
+  return {
+    locale: DEFAULT_LOCALE,
+    source: "default",
+  };
+}
+
+/**
+ * Initialize the i18n system with resolved locale.
+ *
+ * Resolves the locale using the priority chain and sets it as
+ * the global locale for the application.
+ *
+ * @param options - Resolution options
+ * @returns Resolved locale with source information
+ *
+ * @example
+ * ```typescript
+ * // Initialize with CLI flag
+ * const result = initI18n({ cliLanguage: "zh" });
+ * console.log(`Using ${result.locale} from ${result.source}`);
+ *
+ * // Initialize without options
+ * const result = initI18n();
+ * // Uses priority chain: cli-flag → env-var → settings → system → default
+ * ```
+ */
+export function initI18n(options?: ResolveLocaleOptions): ResolvedLocale {
+  const resolved = resolveLocale(options);
+  setGlobalLocale(resolved.locale);
+  return resolved;
+}

package/src/tui/i18n/language-config.ts

@@ -0,0 +1,106 @@
+/**
+ * Language Configuration Module
+ *
+ * Core language configuration for i18n support.
+ * Defines supported locales and provides validation utilities.
+ *
+ * @module tui/i18n/language-config
+ */
+
+/**
+ * Supported locale codes.
+ * Add new locales here as they are implemented.
+ */
+export type LocaleCode = "en" | "zh";
+
+/**
+ * Metadata for a supported language.
+ */
+export interface LanguageInfo {
+  /** ISO locale code */
+  readonly locale: LocaleCode;
+  /** English name of the language */
+  readonly name: string;
+  /** Native name of the language */
+  readonly nativeName: string;
+  /** Flag emoji for the language */
+  readonly flag: string;
+}
+
+/**
+ * Language metadata for all supported locales.
+ */
+export const LANGUAGES: Record<LocaleCode, LanguageInfo> = {
+  en: {
+    locale: "en",
+    name: "English",
+    nativeName: "English",
+    flag: "🇺🇸",
+  },
+  zh: {
+    locale: "zh",
+    name: "Chinese",
+    nativeName: "中文",
+    flag: "🇨🇳",
+  },
+} as const;
+
+/**
+ * Array of all supported locale codes.
+ */
+export const SUPPORTED_LOCALES: readonly LocaleCode[] = Object.keys(LANGUAGES) as LocaleCode[];
+
+/**
+ * Default locale used when no locale is specified.
+ */
+export const DEFAULT_LOCALE: LocaleCode = "en";
+
+/**
+ * Type guard to check if a string is a supported locale code.
+ *
+ * @param locale - The locale string to validate
+ * @returns True if the locale is supported
+ *
+ * @example
+ * ```typescript
+ * const userLocale = getUserLocale();
+ * if (isLocaleSupported(userLocale)) {
+ *   // userLocale is now typed as LocaleCode
+ *   setLocale(userLocale);
+ * }
+ * ```
+ */
+export function isLocaleSupported(locale: string): locale is LocaleCode {
+  return locale in LANGUAGES;
+}
+
+/**
+ * Get the native display name for a locale.
+ *
+ * @param locale - The locale code
+ * @returns The native name of the language
+ *
+ * @example
+ * ```typescript
+ * getLanguageDisplayName("zh"); // "中文"
+ * getLanguageDisplayName("en"); // "English"
+ * ```
+ */
+export function getLanguageDisplayName(locale: LocaleCode): string {
+  return LANGUAGES[locale].nativeName;
+}
+
+/**
+ * Get all available locale codes.
+ *
+ * @returns Readonly array of supported locale codes
+ *
+ * @example
+ * ```typescript
+ * const locales = getAvailableLocales();
+ * // ["en", "zh"]
+ * ```
+ */
+export function getAvailableLocales(): readonly LocaleCode[] {
+  return SUPPORTED_LOCALES;
+}

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

@@ -0,0 +1,173 @@
+/**
+ * Locale Detection Module
+ *
+ * Detects system locale from environment variables.
+ * Follows POSIX locale conventions with Windows fallback support.
+ *
+ * @module tui/i18n/locale-detection
+ */
+
+import { DEFAULT_LOCALE, isLocaleSupported, type LocaleCode } from "./language-config.js";
+
+/**
+ * Result of parsing a POSIX locale string.
+ */
+export interface ParsedLocale {
+  /** ISO 639-1 language code (e.g., "en", "zh") */
+  language: string;
+  /** ISO 3166-1 territory code (e.g., "US", "CN") */
+  territory?: string;
+}
+
+/**
+ * Source of locale detection.
+ */
+export type LocaleSource = "LC_ALL" | "LC_MESSAGES" | "LANG" | "VELLUM_LANGUAGE" | null;
+
+/**
+ * Result of system locale detection.
+ */
+export interface DetectedLocale {
+  /** Detected locale code, or null if not detected */
+  locale: LocaleCode | null;
+  /** Source environment variable that provided the locale */
+  source: LocaleSource;
+}
+
+/**
+ * Parse a POSIX locale string into language and territory components.
+ *
+ * Handles formats like:
+ * - "en" → { language: "en" }
+ * - "en_US" → { language: "en", territory: "US" }
+ * - "zh_CN.UTF-8" → { language: "zh", territory: "CN" }
+ * - "en_US.UTF-8@modifier" → { language: "en", territory: "US" }
+ *
+ * @param localeString - The POSIX locale string to parse
+ * @returns Parsed locale object, or null if invalid or unset ("C", "POSIX")
+ *
+ * @example
+ * ```typescript
+ * parseLocaleString("zh_CN.UTF-8"); // { language: "zh", territory: "CN" }
+ * parseLocaleString("en");          // { language: "en" }
+ * parseLocaleString("C");           // null
+ * parseLocaleString("");            // null
+ * ```
+ */
+export function parseLocaleString(localeString: string): ParsedLocale | null {
+  // Handle empty, null-like, or POSIX default values
+  const trimmed = localeString.trim();
+  if (!trimmed || trimmed === "C" || trimmed === "POSIX") {
+    return null;
+  }
+
+  // Remove encoding (e.g., ".UTF-8") and modifier (e.g., "@euro")
+  // Format: language[_territory][.encoding][@modifier]
+  const withoutModifier = trimmed.split("@")[0] ?? trimmed;
+  const withoutEncoding = withoutModifier.split(".")[0] ?? withoutModifier;
+
+  // Split into language and territory
+  const parts = withoutEncoding.split("_");
+  const languagePart = parts[0];
+  if (!languagePart) {
+    return null;
+  }
+  const language = languagePart.toLowerCase();
+
+  // Validate language code (should be 2-3 characters)
+  if (language.length < 2 || language.length > 3) {
+    return null;
+  }
+
+  const result: ParsedLocale = { language };
+
+  // Add territory if present
+  if (parts[1]) {
+    result.territory = parts[1].toUpperCase();
+  }
+
+  return result;
+}
+
+/**
+ * Environment variables to check for locale, in priority order.
+ */
+const LOCALE_ENV_VARS = ["LC_ALL", "LC_MESSAGES", "LANG"] as const;
+
+/**
+ * Map parsed locale to a supported LocaleCode.
+ *
+ * Handles territory variants by first trying language-territory (e.g., "pt-BR"),
+ * then falling back to just the language code.
+ *
+ * @param parsed - Parsed locale object
+ * @returns Supported LocaleCode or null
+ */
+function mapToSupportedLocale(parsed: ParsedLocale): LocaleCode | null {
+  // Try language-territory format first (e.g., "pt-BR")
+  if (parsed.territory) {
+    const withTerritory = `${parsed.language}-${parsed.territory}`;
+    if (isLocaleSupported(withTerritory)) {
+      return withTerritory as LocaleCode;
+    }
+  }
+
+  // Fall back to just the language code
+  if (isLocaleSupported(parsed.language)) {
+    return parsed.language as LocaleCode;
+  }
+
+  return null;
+}
+
+/**
+ * Detect system locale from environment variables.
+ *
+ * Checks environment variables in priority order:
+ * 1. LC_ALL
+ * 2. LC_MESSAGES
+ * 3. LANG
+ * 4. VELLUM_LANGUAGE (custom override)
+ *
+ * On Windows, if no locale is found, returns DEFAULT_LOCALE as fallback.
+ *
+ * @returns Detection result with locale code and source
+ *
+ * @example
+ * ```typescript
+ * // On a system with LANG=zh_CN.UTF-8
+ * detectSystemLocale(); // { locale: "zh", source: "LANG" }
+ *
+ * // On Windows with no locale set
+ * detectSystemLocale(); // { locale: "en", source: null }
+ * ```
+ */
+export function detectSystemLocale(): DetectedLocale {
+  // Check standard POSIX locale environment variables
+  for (const envVar of LOCALE_ENV_VARS) {
+    const value = process.env[envVar];
+    if (value) {
+      const parsed = parseLocaleString(value);
+      if (parsed) {
+        const locale = mapToSupportedLocale(parsed);
+        if (locale) {
+          return { locale, source: envVar };
+        }
+      }
+    }
+  }
+
+  // Check custom VELLUM_LANGUAGE environment variable
+  const vellumLang = process.env.VELLUM_LANGUAGE;
+  if (vellumLang && isLocaleSupported(vellumLang)) {
+    return { locale: vellumLang as LocaleCode, source: "VELLUM_LANGUAGE" };
+  }
+
+  // Windows fallback: use default locale since LANG/LC_* are typically not set
+  if (process.platform === "win32") {
+    return { locale: DEFAULT_LOCALE, source: null };
+  }
+
+  // No locale detected
+  return { locale: null, source: null };
+}