@hua-labs/i18n-core 2.0.0 → 2.0.4

package/src/__tests__/useI18n.test.tsx

@@ -0,0 +1,181 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { renderHook, act, waitFor } from '@testing-library/react';
+import React from 'react';
+import { I18nProvider, useI18n } from '../hooks/useI18n';
+import { TranslatorFactory } from '../core/translator-factory';
+import { I18nConfig } from '../types';
+
+function createMockConfig(overrides?: Partial<I18nConfig>): I18nConfig {
+  return {
+    defaultLanguage: 'ko',
+    fallbackLanguage: 'en',
+    supportedLanguages: [
+      { code: 'ko', name: 'Korean', nativeName: '한국어' },
+      { code: 'en', name: 'English', nativeName: 'English' },
+    ],
+    namespaces: ['common'],
+    loadTranslations: vi.fn().mockImplementation(async (lang: string, ns: string) => {
+      const data: Record<string, Record<string, any>> = {
+        'ko:common': { greeting: '안녕하세요', welcome: '{name}님 환영합니다' },
+        'en:common': { greeting: 'Hello', welcome: 'Welcome {name}' },
+      };
+      return data[`${lang}:${ns}`] || {};
+    }),
+    ...overrides,
+  };
+}
+
+function createWrapper(config: I18nConfig) {
+  return function Wrapper({ children }: { children: React.ReactNode }) {
+    return React.createElement(I18nProvider, { config }, children);
+  };
+}
+
+describe('useI18n', () => {
+  beforeEach(() => {
+    TranslatorFactory.clear();
+  });
+
+  describe('without Provider', () => {
+    it('should return default values without error', () => {
+      const { result } = renderHook(() => useI18n());
+
+      expect(result.current.currentLanguage).toBe('ko');
+      expect(result.current.isLoading).toBe(false);
+      expect(result.current.isInitialized).toBe(false);
+      expect(result.current.error).toBeNull();
+    });
+
+    it('should return key as-is for t() without provider', () => {
+      const { result } = renderHook(() => useI18n());
+      expect(result.current.t('common:greeting')).toBe('common:greeting');
+    });
+
+    it('should return empty array for tArray() without provider', () => {
+      const { result } = renderHook(() => useI18n());
+      expect(result.current.tArray('common:items')).toEqual([]);
+    });
+
+    it('should return default debug utilities', () => {
+      const { result } = renderHook(() => useI18n());
+      expect(result.current.debug.getCurrentLanguage()).toBe('ko');
+      expect(result.current.debug.getSupportedLanguages()).toEqual(['ko', 'en']);
+      expect(result.current.debug.isReady()).toBe(false);
+    });
+  });
+
+  describe('with Provider', () => {
+    it('should initialize and provide translations', async () => {
+      const config = createMockConfig();
+      const { result } = renderHook(() => useI18n(), {
+        wrapper: createWrapper(config),
+      });
+
+      // Initially loading
+      expect(result.current.isLoading).toBe(true);
+
+      // Wait for initialization
+      await waitFor(() => {
+        expect(result.current.isInitialized).toBe(true);
+      });
+
+      expect(result.current.currentLanguage).toBe('ko');
+    });
+
+    it('should translate keys after initialization', async () => {
+      const config = createMockConfig();
+      const { result } = renderHook(() => useI18n(), {
+        wrapper: createWrapper(config),
+      });
+
+      await waitFor(() => {
+        expect(result.current.isInitialized).toBe(true);
+      });
+
+      // t() should return translated text
+      expect(result.current.t('common:greeting')).toBe('안녕하세요');
+    });
+
+    it('should change language', async () => {
+      const config = createMockConfig();
+      const { result } = renderHook(() => useI18n(), {
+        wrapper: createWrapper(config),
+      });
+
+      await waitFor(() => {
+        expect(result.current.isInitialized).toBe(true);
+      });
+
+      await act(async () => {
+        await result.current.setLanguage('en');
+      });
+
+      expect(result.current.currentLanguage).toBe('en');
+    });
+
+    it('should handle initialTranslations for SSR', async () => {
+      const config = createMockConfig({
+        initialTranslations: {
+          ko: { common: { greeting: 'SSR 안녕' } },
+        },
+      });
+      const { result } = renderHook(() => useI18n(), {
+        wrapper: createWrapper(config),
+      });
+
+      await waitFor(() => {
+        expect(result.current.isInitialized).toBe(true);
+      });
+
+      expect(result.current.t('common:greeting')).toBe('SSR 안녕');
+    });
+
+    it('should provide debug utilities', async () => {
+      const config = createMockConfig();
+      const { result } = renderHook(() => useI18n(), {
+        wrapper: createWrapper(config),
+      });
+
+      await waitFor(() => {
+        expect(result.current.isInitialized).toBe(true);
+      });
+
+      expect(result.current.debug.getCurrentLanguage()).toBe('ko');
+      expect(result.current.debug.getSupportedLanguages()).toContain('ko');
+      expect(result.current.debug.isReady()).toBe(true);
+    });
+
+    it('should handle translation errors gracefully', async () => {
+      // Use a loader that fails once then returns empty - avoids slow retry backoff
+      let callCount = 0;
+      const config = createMockConfig({
+        loadTranslations: vi.fn().mockImplementation(async () => {
+          callCount++;
+          if (callCount <= 2) throw new Error('Load failed');
+          return {};
+        }),
+      });
+      const { result } = renderHook(() => useI18n(), {
+        wrapper: createWrapper(config),
+      });
+
+      // Should eventually initialize even with errors
+      await waitFor(() => {
+        expect(result.current.isInitialized).toBe(true);
+      }, { timeout: 15000 });
+
+      // Should not crash - returns empty/fallback
+      expect(result.current.isLoading).toBe(false);
+    }, 20000);
+
+    it('should provide supported languages from config', async () => {
+      const config = createMockConfig();
+      const { result } = renderHook(() => useI18n(), {
+        wrapper: createWrapper(config),
+      });
+
+      expect(result.current.supportedLanguages).toHaveLength(2);
+      expect(result.current.supportedLanguages[0].code).toBe('ko');
+    });
+  });
+});

package/src/__tests__/useTranslation.test.tsx

@@ -0,0 +1,110 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { renderHook, waitFor } from '@testing-library/react';
+import React from 'react';
+import { useTranslation, useLanguageChange } from '../hooks/useTranslation';
+import { I18nProvider } from '../hooks/useI18n';
+import { TranslatorFactory } from '../core/translator-factory';
+import { I18nConfig } from '../types';
+
+function createMockConfig(overrides?: Partial<I18nConfig>): I18nConfig {
+  return {
+    defaultLanguage: 'ko',
+    fallbackLanguage: 'en',
+    supportedLanguages: [
+      { code: 'ko', name: 'Korean', nativeName: '한국어' },
+      { code: 'en', name: 'English', nativeName: 'English' },
+    ],
+    namespaces: ['common'],
+    loadTranslations: vi.fn().mockImplementation(async (lang: string, ns: string) => {
+      const data: Record<string, Record<string, any>> = {
+        'ko:common': { greeting: '안녕하세요' },
+        'en:common': { greeting: 'Hello' },
+      };
+      return data[`${lang}:${ns}`] || {};
+    }),
+    ...overrides,
+  };
+}
+
+function createWrapper(config: I18nConfig) {
+  return function Wrapper({ children }: { children: React.ReactNode }) {
+    return React.createElement(I18nProvider, { config }, children);
+  };
+}
+
+describe('useTranslation', () => {
+  beforeEach(() => {
+    TranslatorFactory.clear();
+  });
+
+  it('should return all translation utilities', async () => {
+    const config = createMockConfig();
+    const { result } = renderHook(() => useTranslation(), {
+      wrapper: createWrapper(config),
+    });
+
+    await waitFor(() => {
+      expect(result.current.isInitialized).toBe(true);
+    });
+
+    expect(result.current.t).toBeDefined();
+    expect(result.current.tPlural).toBeDefined();
+    expect(result.current.tArray).toBeDefined();
+    expect(result.current.currentLanguage).toBe('ko');
+    expect(result.current.setLanguage).toBeDefined();
+    expect(result.current.debug).toBeDefined();
+  });
+
+  it('should translate using t()', async () => {
+    const config = createMockConfig();
+    const { result } = renderHook(() => useTranslation(), {
+      wrapper: createWrapper(config),
+    });
+
+    await waitFor(() => {
+      expect(result.current.isInitialized).toBe(true);
+    });
+
+    expect(result.current.t('common:greeting')).toBe('안녕하세요');
+  });
+
+  it('should work without provider (returns defaults)', () => {
+    const { result } = renderHook(() => useTranslation());
+    expect(result.current.currentLanguage).toBe('ko');
+    expect(result.current.isInitialized).toBe(false);
+    expect(result.current.t('key')).toBe('key');
+  });
+});
+
+describe('useLanguageChange', () => {
+  beforeEach(() => {
+    TranslatorFactory.clear();
+  });
+
+  it('should provide language change utilities', async () => {
+    const config = createMockConfig();
+    const { result } = renderHook(() => useLanguageChange(), {
+      wrapper: createWrapper(config),
+    });
+
+    expect(result.current.currentLanguage).toBe('ko');
+    expect(result.current.changeLanguage).toBeDefined();
+    expect(result.current.supportedLanguages).toHaveLength(2);
+  });
+
+  it('should warn for unsupported language', async () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const config = createMockConfig();
+    const { result } = renderHook(() => useLanguageChange(), {
+      wrapper: createWrapper(config),
+    });
+
+    await waitFor(() => {
+      // wait for initialization
+    });
+
+    result.current.changeLanguage('fr');
+    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('fr'));
+    warnSpy.mockRestore();
+  });
+});

package/src/components/MissingKeyOverlay.tsx

@@ -195,7 +195,7 @@ export const reportMissingKey = (key: string, options: {
     }));
 
     // 콘솔에도 로그
-    console.warn(`Missing translation key: ${key}`, {
+    if (process.env.NODE_ENV === 'development') console.warn(`Missing translation key: ${key}`, {
       namespace: options.namespace,
       language: options.language,
       component: options.component

package/src/core/lazy-loader.ts

@@ -181,8 +181,8 @@ export class LazyLoader {
    */
   analyzeUsagePatterns(): Record<string, number> {
     const usage: Record<string, number> = {};
-    
-    for (const [key, timestamp] of this.loadHistory.entries()) {
+
+    for (const [key] of this.loadHistory.entries()) {
       const namespace = key.split(':')[1];
       usage[namespace] = (usage[namespace] || 0) + 1;
     }

package/src/core/translator.tsx

@@ -10,21 +10,26 @@ import {
   logTranslationError,
   defaultErrorRecoveryStrategy,
   defaultErrorLoggingConfig,
-  isRecoverableError
+  isRecoverableError,
+  isPluralValue,
+  PluralCategory
 } from '../types';
 
 export interface TranslatorInterface {
-  translate(key: string, language?: string): string;
+  translate(key: string, paramsOrLang?: Record<string, unknown> | string, language?: string): string;
+  tPlural(key: string, count: number, params?: Record<string, unknown>, language?: string): string;
   setLanguage(lang: string): void;
   getCurrentLanguage(): string;
   initialize(): Promise<void>;
   isReady(): boolean;
   debug(): unknown;
   getRawValue(key: string, language?: string): unknown;
+  tArray(key: string, language?: string): string[];
 }
 
 export class Translator implements TranslatorInterface {
   private cache = new Map<string, CacheEntry>();
+  private pluralRulesCache = new Map<string, Intl.PluralRules>();
   private loadedNamespaces = new Set<string>();
   private loadingPromises = new Map<string, Promise<TranslationNamespace>>();
   private allTranslations: Record<string, Record<string, TranslationNamespace>> = {};
@@ -144,9 +149,9 @@ export class Translator implements TranslatorInterface {
           this.loadedNamespaces.add(`${language}:${namespace}`);
         }
       }
-      if (this.config.debug) {
-        console.log('✅ [TRANSLATOR] Initial translations loaded from SSR:', this.loadedNamespaces);
-      }
+      // initialTranslations가 있으면 초기화 완료로 간주 (SSR에서 이미 로드됨)
+      // 이렇게 하면 초기화 전 상태에서도 번역을 사용할 수 있음
+      this.isInitialized = true;
     }
   }
 
@@ -305,28 +310,27 @@ export class Translator implements TranslatorInterface {
       console.warn('Translator not initialized. Call initialize() first.');
     }
     
+    // 초기화되지 않았을 때도 기본 번역 시도 (initialTranslations 사용)
     const { namespace, key: actualKey } = this.parseKey(key);
-    const translations = this.allTranslations[targetLang]?.[namespace];
-
+    
+    // findInNamespace를 사용하여 중첩 키도 처리
+    const result = this.findInNamespace(namespace, actualKey, targetLang);
+    if (result) {
+      if (this.config.debug) {
+        console.log(`✅ [TRANSLATOR] Found fallback translation from initialTranslations:`, result);
+      }
+      return result;
+    }
+    
     if (this.config.debug) {
-      console.log(`🔍 [TRANSLATOR] Not initialized, trying fallback:`, {
+      const translations = this.allTranslations[targetLang]?.[namespace];
+      console.log(`🔍 [TRANSLATOR] Not initialized, fallback failed:`, {
         namespace,
         actualKey,
-        translations,
-        hasTranslation: translations && translations[actualKey]
+        hasTranslations: !!translations,
+        translationsKeys: translations ? Object.keys(translations) : []
       });
     }
-
-    if (translations && translations[actualKey]) {
-      const value = translations[actualKey];
-      if (typeof value === 'string') {
-        if (this.config.debug) {
-          console.log(`✅ [TRANSLATOR] Found fallback translation:`, value);
-        }
-        return value;
-      }
-    }
-    
     return this.config.missingKeyHandler?.(key, targetLang, 'default') || key;
   }
 
@@ -372,12 +376,23 @@ export class Translator implements TranslatorInterface {
   /**
    * 번역 키를 번역된 텍스트로 변환
    */
-  translate(key: string, language?: string): string {
-    const targetLang = language || this.currentLang;
+  translate(key: string, paramsOrLang?: Record<string, unknown> | string, language?: string): string {
+    // 두 번째 인자 타입으로 분기
+    let params: Record<string, unknown> | undefined;
+    let targetLang: string;
+    if (typeof paramsOrLang === 'string') {
+      targetLang = paramsOrLang;
+    } else if (typeof paramsOrLang === 'object' && paramsOrLang !== null) {
+      params = paramsOrLang;
+      targetLang = language || this.currentLang;
+    } else {
+      targetLang = this.currentLang;
+    }
 
     // 초기화되지 않은 경우 처리
     if (!this.isInitialized) {
-      return this.translateBeforeInitialized(key, targetLang);
+      const raw = this.translateBeforeInitialized(key, targetLang);
+      return params ? this.interpolate(raw, params) : raw;
     }
 
     const { namespace, key: actualKey } = this.parseKey(key);
@@ -386,28 +401,29 @@ export class Translator implements TranslatorInterface {
     let result: string | null = this.findInNamespace(namespace, actualKey, targetLang);
     if (result) {
       this.cacheStats.hits++;
-      return result;
+      return params ? this.interpolate(result, params) : result;
     }
-    
+
     // 2단계: 다른 로드된 언어에서 찾기 (언어 변경 중 깜빡임 방지)
     result = this.findInOtherLanguages(namespace, actualKey, targetLang);
     if (result) {
-      return result;
+      return params ? this.interpolate(result, params) : result;
     }
 
     // 3단계: 폴백 언어에서 찾기
     result = this.findInFallbackLanguage(namespace, actualKey, targetLang);
     if (result) {
-      return result;
+      return params ? this.interpolate(result, params) : result;
     }
 
     // 모든 단계에서 찾지 못한 경우
     this.cacheStats.misses++;
-    
+
     if (this.config.debug) {
-      return this.config.missingKeyHandler?.(key, targetLang, namespace) || key;
+      const missing = this.config.missingKeyHandler?.(key, targetLang, namespace) || key;
+      return params ? this.interpolate(missing, params) : missing;
     }
-    
+
     // 프로덕션에서는 빈 문자열 반환 (미싱 키 노출 방지)
     return '';
   }
@@ -442,12 +458,18 @@ export class Translator implements TranslatorInterface {
     if (this.isStringValue(directValue)) {
       return directValue;
     }
+    if (this.isStringArray(directValue)) {
+      return directValue[Math.floor(Math.random() * directValue.length)];
+    }
 
     // 중첩 키 매칭 (예: "user.profile.name")
     const nestedValue = this.getNestedValue(translations, key);
     if (this.isStringValue(nestedValue)) {
       return nestedValue;
     }
+    if (this.isStringArray(nestedValue)) {
+      return nestedValue[Math.floor(Math.random() * nestedValue.length)];
+    }
 
     if (this.config.debug) {
       console.warn(`❌ [TRANSLATOR] No match found for key: ${key} in ${language}/${namespace}`);
@@ -457,6 +479,7 @@ export class Translator implements TranslatorInterface {
 
   /**
    * 중첩된 객체에서 값을 가져오기
+   * 배열도 지원: 최종 값이 string[]이면 그대로 반환
    */
   private getNestedValue(obj: unknown, path: string): unknown {
     if (typeof obj !== 'object' || obj === null || Array.isArray(obj)) {
@@ -464,7 +487,12 @@ export class Translator implements TranslatorInterface {
     }
 
     return path.split('.').reduce((current: unknown, key: string) => {
-      if (current && typeof current === 'object' && !Array.isArray(current) && key in current) {
+      if (current == null) return undefined;
+      if (Array.isArray(current)) {
+        const idx = Number(key);
+        return Number.isInteger(idx) ? current[idx] : undefined;
+      }
+      if (typeof current === 'object' && key in (current as Record<string, unknown>)) {
         return (current as Record<string, unknown>)[key];
       }
       return undefined;
@@ -478,6 +506,14 @@ export class Translator implements TranslatorInterface {
     return typeof value === 'string' && value.length > 0;
   }
 
+  /**
+   * string[] 배열인지 확인하는 타입 가드
+   * 배열 값이 t()에 전달되면 랜덤으로 하나를 선택하여 반환
+   */
+  private isStringArray(value: unknown): value is string[] {
+    return Array.isArray(value) && value.length > 0 && value.every(v => typeof v === 'string');
+  }
+
   /**
    * 원시 값 가져오기 (배열, 객체 포함)
    */
@@ -527,26 +563,77 @@ export class Translator implements TranslatorInterface {
   }
 
   /**
-   * 매개변수 보간
+   * 배열 번역 값 가져오기 (타입 안전)
    */
-  private interpolate(text: string, params: Record<string, unknown>): string {
-    return text.replace(/\{\{(\w+)\}\}/g, (match, key) => {
-      const value = params[key];
-      return value !== undefined ? String(value) : match;
-    });
+  tArray(key: string, language?: string): string[] {
+    const raw = this.getRawValue(key, language);
+    if (Array.isArray(raw) && raw.every((v: unknown) => typeof v === 'string')) {
+      return raw as string[];
+    }
+    if (process.env.NODE_ENV === 'development') {
+      console.warn(`tArray: "${key}" is not a string array`);
+    }
+    return [];
+  }
+
+  /**
+   * Intl.PluralRules 인스턴스 (언어별 캐시)
+   */
+  private getPluralRules(language: string): Intl.PluralRules {
+    let rules = this.pluralRulesCache.get(language);
+    if (!rules) {
+      rules = new Intl.PluralRules(language);
+      this.pluralRulesCache.set(language, rules);
+    }
+    return rules;
   }
 
   /**
-   * 매개변수가 있는 번역
+   * 복수형 번역 (ICU / Intl.PluralRules 기반)
+   *
+   * JSON: { "other": "총 {count}개" }  (ko)
+   *       { "one": "{count} item", "other": "{count} items" }  (en)
+   *
+   * tPlural('common:total_count', 1) → en: "1 item" / ko: "총 1개"
+   * tPlural('common:total_count', 5) → en: "5 items" / ko: "총 5개"
    */
-  translateWithParams(key: string, params?: Record<string, unknown>, language?: string): string {
-    const translated = this.translate(key, language);
+  tPlural(key: string, count: number, params?: Record<string, unknown>, language?: string): string {
+    const targetLang = language || this.currentLang;
+    const raw = this.getRawValue(key, targetLang);
+    const mergedParams: Record<string, unknown> = { count, ...params };
+
+    // PluralValue 객체인 경우: Intl.PluralRules로 카테고리 결정
+    if (isPluralValue(raw)) {
+      const category = this.getPluralRules(targetLang).select(count) as PluralCategory;
+      const text = raw[category] ?? raw.other;
+      return this.interpolate(text, mergedParams);
+    }
 
-    if (!params) {
-      return translated;
+    // fallback: plain string이면 interpolate만
+    if (typeof raw === 'string') {
+      return this.interpolate(raw, mergedParams);
     }
 
-    return this.interpolate(translated, params);
+    // 키를 찾지 못한 경우
+    if (this.config.debug) {
+      return this.interpolate(key, mergedParams);
+    }
+    return '';
+  }
+
+  /**
+   * 매개변수 보간
+   *
+   * 지원 형식:
+   * - {key} - 단일 중괄호 (일반적인 i18n 형식)
+   * - {{key}} - 이중 중괄호 (하위 호환성)
+   */
+  private interpolate(text: string, params: Record<string, unknown>): string {
+    // 단일 중괄호 {key} 또는 이중 중괄호 {{key}} 모두 지원
+    return text.replace(/\{\{?(\w+)\}?\}/g, (match, key) => {
+      const value = params[key];
+      return value !== undefined ? String(value) : match;
+    });
   }
 
   /**
@@ -866,23 +953,25 @@ export class Translator implements TranslatorInterface {
   }
 
   /**
-   * 키 파싱 (네임스페이스:키 또는 네임스페이스.키 형식 지원)
-   * 우선순위: : > . (첫 번째 구분자 사용)
+   * 키 파싱 (네임스페이스:키 형식)
+   * 
+   * - 콜론(:)만 네임스페이스 구분자로 사용
+   * - 점(.)은 키 이름의 일부로 취급 (중첩 객체 접근용)
+   * 
+   * @example
+   * parseKey("home:hero.badge") → { namespace: "home", key: "hero.badge" }
+   * parseKey("hero.badge") → { namespace: "common", key: "hero.badge" }
+   * parseKey("save") → { namespace: "common", key: "save" }
    */
   private parseKey(key: string): { namespace: string; key: string } {
-    // : 구분자 우선 확인
+    // 콜론(:)만 네임스페이스 구분자로 사용
     const colonIndex = key.indexOf(':');
     if (colonIndex !== -1) {
       return { namespace: key.substring(0, colonIndex), key: key.substring(colonIndex + 1) };
     }
 
-    // . 구분자 확인 (첫 번째 점만 네임스페이스 구분자로 사용)
-    const dotIndex = key.indexOf('.');
-    if (dotIndex !== -1) {
-      return { namespace: key.substring(0, dotIndex), key: key.substring(dotIndex + 1) };
-    }
-
-    // 구분자가 없으면 common 네임스페이스로 간주
+    // 콜론이 없으면 common 네임스페이스로 간주
+    // 점(.)은 키 이름의 일부 (중첩 객체 접근은 getNestedValue에서 처리)
     return { namespace: 'common', key };
   }
 
@@ -1063,20 +1152,20 @@ function isStringValue(value: unknown): value is string {
   return typeof value === 'string' && value.length > 0;
 }
 
+/**
+ * 키 파싱 (네임스페이스:키 형식) - SSR용 standalone 함수
+ * 
+ * - 콜론(:)만 네임스페이스 구분자로 사용
+ * - 점(.)은 키 이름의 일부로 취급 (중첩 객체 접근용)
+ */
 function parseKey(key: string): { namespace: string; key: string } {
-  // : 구분자 우선 확인
+  // 콜론(:)만 네임스페이스 구분자로 사용
   const colonIndex = key.indexOf(':');
   if (colonIndex !== -1) {
     return { namespace: key.substring(0, colonIndex), key: key.substring(colonIndex + 1) };
   }
 
-  // . 구분자 확인 (첫 번째 점만 네임스페이스 구분자로 사용)
-  const dotIndex = key.indexOf('.');
-  if (dotIndex !== -1) {
-    return { namespace: key.substring(0, dotIndex), key: key.substring(dotIndex + 1) };
-  }
-
-  // 구분자가 없으면 common 네임스페이스로 간주
+  // 콜론이 없으면 common 네임스페이스로 간주
   return { namespace: 'common', key };
 }