feat(validation): add upfront language code validation (Issue #3)

Fixed user experience issue where invalid language codes were only caught
during API calls, leading to cryptic error messages. Now validates all
language codes upfront before making any API requests.

Changes:
- Added VALID_LANGUAGES Set with all 30 supported DeepL language codes
- Added validateLanguageCodes() method to TranslateCommand class
- Validates single language codes (--to es)
- Validates multiple language codes (--to es,fr,de)
- Validates across all translation paths: text, file, directory, document
- Clear error messages list all valid language codes
- Empty strings after trimming are properly detected and rejected
- Added 6 comprehensive tests covering all validation scenarios

Benefits:
- Users get immediate, actionable feedback about invalid language codes
- Error messages include the full list of 30 valid codes for easy reference
- Prevents wasted API calls with invalid parameters
- Consistent validation across all translation workflows
- Better developer experience with early error detection

Test Coverage:
- All 1442 tests passing (100% pass rate)
- New tests: multi-language validation suite (6 tests)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: sjsyrek

CHANGELOG.md

@@ -16,6 +16,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - **Impact**: Ensures future developers understand the importance of property order
   - Location: `src/services/translation.ts:386-417`, test added to `tests/unit/translation-service.test.ts`
 
+- **Language Code Validation** - Upfront validation prevents late API errors (Issue #3)
+  - Validates all language codes before making API calls
+  - Applies to single language (`--to es`) and multiple languages (`--to es,fr,de`)
+  - Validates across all translation workflows: text, file, directory, and document translation
+  - Clear error messages list all 30 valid language codes
+  - Empty language codes after trimming are detected and rejected
+  - **Impact**: Users get immediate feedback about invalid language codes instead of cryptic API errors
+  - **Example**: `deepl translate "Hello" --to invalid` now shows: "Invalid target language code: "invalid". Valid codes: ar, bg, cs, ..."
+  - Added 6 comprehensive tests covering single/multi-language validation
+  - Location: `src/cli/commands/translate.ts:81-92` (validation method), multiple call sites
+
 ### Fixed
 - **Critical: Duplicate text handling in batch translation** - Fixed data loss bug for duplicate inputs
   - When input array contained duplicate texts (e.g., `["Hello", "Hello", "World"]`), only the last occurrence received translation

src/cli/commands/translate.ts

@@ -16,6 +16,13 @@ import { Language } from '../../types/index.js';
 import { formatTranslationJson, formatMultiTranslationJson, formatMultiTranslationTable } from '../../utils/formatters.js';
 import { Logger } from '../../utils/logger.js';
 
+// Valid language codes supported by DeepL
+const VALID_LANGUAGES: ReadonlySet<string> = new Set([
+  'ar', 'bg', 'cs', 'da', 'de', 'el', 'en', 'es', 'et', 'fi', 'fr',
+  'hu', 'id', 'it', 'ja', 'ko', 'lt', 'lv', 'nb', 'nl', 'pl', 'pt',
+  'ro', 'ru', 'sk', 'sl', 'sv', 'tr', 'uk', 'zh'
+]);
+
 // Constants for text-based file caching
 const TEXT_BASED_EXTENSIONS = ['.txt', '.md', '.html', '.htm', '.srt', '.xlf', '.xliff'];
 const SAFE_TEXT_SIZE_LIMIT = 100 * 1024; // 100 KiB (safe threshold, API limit is 128 KiB)
@@ -71,6 +78,19 @@ export class TranslateCommand {
     this.config = config;
   }
 
+  /**
+   * Validate language codes
+   * Throws error if any language code is invalid
+   * Fix for Issue #3: Validate language codes upfront to provide clear error messages
+   */
+  private validateLanguageCodes(langCodes: string[]): void {
+    for (const lang of langCodes) {
+      if (!VALID_LANGUAGES.has(lang)) {
+        throw new Error(`Invalid target language code: "${lang}". Valid codes: ${Array.from(VALID_LANGUAGES).sort().join(', ')}`);
+      }
+    }
+  }
+
   /**
    * Resolve glossary ID from name or ID
    * If input looks like a UUID (glossary-*), use it directly as ID
@@ -207,7 +227,13 @@ export class TranslateCommand {
 
     // Check if translating to multiple languages (must be done BEFORE text file optimization)
     if (options.to.includes(',')) {
-      const targetLangs = options.to.split(',').map(lang => lang.trim()) as Language[];
+      const targetLangs = options.to.split(',').map(lang => lang.trim());
+
+      // Validate all language codes (Issue #3)
+      this.validateLanguageCodes(targetLangs);
+
+      // Now safe to cast as Language[]
+      const validTargetLangs = targetLangs as Language[];
 
       const translationOptions: {
         sourceLang?: Language;
@@ -227,11 +253,11 @@ export class TranslateCommand {
 
       const results = await this.fileTranslationService.translateFileToMultiple(
         filePath,
-        targetLangs,
+        validTargetLangs,
         translationOptions
       );
 
-      return `Translated ${filePath} to ${targetLangs.length} languages:\n` +
+      return `Translated ${filePath} to ${validTargetLangs.length} languages:\n` +
         results.map(r => `  [${r.targetLang}] ${r.outputPath}`).join('\n');
     }
 
@@ -269,6 +295,9 @@ export class TranslateCommand {
       return this.translateDocument(filePath, options);
     }
 
+    // Validate single language code for file translation (Issue #3)
+    this.validateLanguageCodes([options.to]);
+
     // Single language translation using file translation service
     const translationOptions: {
       targetLang: Language;
@@ -317,6 +346,9 @@ export class TranslateCommand {
       return this.translateToMultiple(text, options);
     }
 
+    // Validate single language code (Issue #3)
+    this.validateLanguageCodes([options.to]);
+
     // Build translation options
     const translationOptions: {
       targetLang: Language;
@@ -429,7 +461,13 @@ export class TranslateCommand {
    * Translate to multiple target languages
    */
   private async translateToMultiple(text: string, options: TranslateOptions): Promise<string> {
-    const targetLangs = options.to.split(',').map(lang => lang.trim()) as Language[];
+    const targetLangs = options.to.split(',').map(lang => lang.trim());
+
+    // Validate all language codes (Issue #3)
+    this.validateLanguageCodes(targetLangs);
+
+    // Now safe to cast as Language[]
+    const validTargetLangs = targetLangs as Language[];
 
     const translationOptions: {
       sourceLang?: Language;
@@ -461,7 +499,7 @@ export class TranslateCommand {
 
     const results = await this.translationService.translateToMultiple(
       text,
-      targetLangs,
+      validTargetLangs,
       { ...translationOptions, skipCache: !options.cache }
     );
 
@@ -488,6 +526,9 @@ export class TranslateCommand {
       throw new Error('Output directory is required for batch translation. Use --output <dir>');
     }
 
+    // Validate language code (Issue #3)
+    this.validateLanguageCodes([options.to]);
+
     // Build translation options
     const targetLang = options.to as Language;
     const translationOptions: {
@@ -576,6 +617,9 @@ export class TranslateCommand {
    * Used for small .txt, .md, .html, .srt, .xlf files
    */
   private async translateTextFile(filePath: string, options: TranslateOptions): Promise<string> {
+    // Validate language code (Issue #3)
+    this.validateLanguageCodes([options.to]);
+
     // Read file content
     const content = fs.readFileSync(filePath, 'utf-8');
 
@@ -674,6 +718,9 @@ export class TranslateCommand {
    * Translate binary document (PDF, DOCX, etc.)
    */
   private async translateDocument(filePath: string, options: TranslateOptions): Promise<string> {
+    // Validate language code (Issue #3)
+    this.validateLanguageCodes([options.to]);
+
     const outputPath = options.output!;
 
     // Build translation options

tests/unit/translate-command.test.ts

@@ -1509,4 +1509,82 @@ describe('TranslateCommand', () => {
       );
     });
   });
+
+  describe('multi-language validation (Issue #3)', () => {
+    it('should reject invalid language codes in comma-separated list', async () => {
+      await expect(
+        translateCommand.translateText('Hello', {
+          to: 'es,invalid,fr',
+        })
+      ).rejects.toThrow('Invalid target language code: "invalid"');
+    });
+
+    it('should accept all valid language codes', async () => {
+      (mockTranslationService.translateToMultiple as jest.Mock).mockResolvedValueOnce([
+        { targetLang: 'es', text: 'Hola' },
+        { targetLang: 'fr', text: 'Bonjour' },
+        { targetLang: 'de', text: 'Hallo' },
+      ]);
+
+      const result = await translateCommand.translateText('Hello', {
+        to: 'es,fr,de',
+      });
+
+      expect(result).toContain('Hola');
+      expect(result).toContain('Bonjour');
+      expect(result).toContain('Hallo');
+      expect(mockTranslationService.translateToMultiple).toHaveBeenCalledWith(
+        'Hello',
+        ['es', 'fr', 'de'],
+        expect.any(Object)
+      );
+    });
+
+    it('should reject invalid single language code', async () => {
+      await expect(
+        translateCommand.translateText('Hello', {
+          to: 'invalid',
+        })
+      ).rejects.toThrow('Invalid target language code: "invalid"');
+    });
+
+    it('should trim whitespace in language codes', async () => {
+      (mockTranslationService.translateToMultiple as jest.Mock).mockResolvedValueOnce([
+        { targetLang: 'es', text: 'Hola' },
+        { targetLang: 'fr', text: 'Bonjour' },
+      ]);
+
+      const result = await translateCommand.translateText('Hello', {
+        to: ' es , fr ',
+      });
+
+      expect(result).toContain('Hola');
+      expect(mockTranslationService.translateToMultiple).toHaveBeenCalledWith(
+        'Hello',
+        ['es', 'fr'],
+        expect.any(Object)
+      );
+    });
+
+    it('should reject empty language codes after trimming', async () => {
+      await expect(
+        translateCommand.translateText('Hello', {
+          to: 'es,,fr',
+        })
+      ).rejects.toThrow('Invalid target language code: ""');
+    });
+
+    it('should validate language codes for file translation', async () => {
+      const fs = jest.requireActual('fs');
+      jest.spyOn(fs, 'statSync').mockReturnValue({ size: 1024, isDirectory: () => false } as any);
+      jest.spyOn(fs, 'readFileSync').mockReturnValue('Hello world');
+
+      await expect(
+        (translateCommand as any).translateFile('/input.txt', {
+          to: 'es,invalid,fr',
+          output: '/output',
+        })
+      ).rejects.toThrow('Invalid target language code: "invalid"');
+    });
+  });
 });