@hua-labs/i18n-core 2.0.0 → 2.0.4

package/src/__tests__/debug-tools.test.ts

@@ -0,0 +1,359 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { createDebugTools, enableDebugTools, disableDebugTools, DebugTools } from '../core/debug-tools';
+
+describe('debug-tools', () => {
+  const originalEnv = process.env.NODE_ENV;
+  const originalWindow = global.window;
+
+  beforeEach(() => {
+    // Mock window object
+    global.window = {
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+      dispatchEvent: vi.fn(),
+      __HUA_I18N_DEBUG__: undefined,
+    } as any;
+
+    // Mock document object
+    global.document = {
+      body: {
+        appendChild: vi.fn(),
+      },
+      createElement: vi.fn((tag: string) => {
+        const element: any = {
+          tagName: tag,
+          style: {},
+          innerHTML: '',
+          textContent: '',
+          id: '',
+          appendChild: vi.fn(),
+          addEventListener: vi.fn(),
+          removeEventListener: vi.fn(),
+          setAttribute: vi.fn(),
+          getAttribute: vi.fn(),
+          querySelectorAll: vi.fn().mockReturnValue([]),
+          querySelector: vi.fn(),
+          remove: vi.fn(),
+          getBoundingClientRect: vi.fn().mockReturnValue({
+            left: 0,
+            top: 0,
+            bottom: 0,
+            right: 0,
+          }),
+        };
+        return element;
+      }),
+      getElementById: vi.fn(),
+      querySelectorAll: vi.fn().mockReturnValue([]),
+    } as any;
+  });
+
+  afterEach(() => {
+    process.env.NODE_ENV = originalEnv;
+    global.window = originalWindow;
+    vi.clearAllMocks();
+  });
+
+  describe('createDebugTools', () => {
+    it('should return null in production', () => {
+      process.env.NODE_ENV = 'production';
+      const tools = createDebugTools();
+      expect(tools).toBeNull();
+    });
+
+    it('should return DebugTools object in development', () => {
+      process.env.NODE_ENV = 'development';
+      const tools = createDebugTools();
+      expect(tools).not.toBeNull();
+      expect(tools).toHaveProperty('highlightMissingKeys');
+      expect(tools).toHaveProperty('showTranslationKeys');
+      expect(tools).toHaveProperty('performanceMetrics');
+      expect(tools).toHaveProperty('devTools');
+      expect(tools).toHaveProperty('validateTranslations');
+    });
+
+    it('should return DebugTools object in test environment', () => {
+      process.env.NODE_ENV = 'test';
+      const tools = createDebugTools();
+      expect(tools).not.toBeNull();
+    });
+
+    it('should have performanceMetrics with initial values', () => {
+      process.env.NODE_ENV = 'development';
+      const tools = createDebugTools();
+      expect(tools?.performanceMetrics).toEqual({
+        translationCount: 0,
+        cacheHits: 0,
+        cacheMisses: 0,
+        loadTimes: [],
+      });
+    });
+
+    it('should have devTools with correct properties', () => {
+      process.env.NODE_ENV = 'development';
+      const tools = createDebugTools();
+      expect(tools?.devTools).toHaveProperty('open');
+      expect(tools?.devTools).toHaveProperty('close');
+      expect(tools?.devTools).toHaveProperty('isOpen');
+      expect(tools?.devTools.isOpen).toBe(false);
+    });
+  });
+
+  describe('highlightMissingKeys', () => {
+    it('should highlight elements with missing translations', () => {
+      process.env.NODE_ENV = 'development';
+      const tools = createDebugTools();
+
+      const mockElement = {
+        getAttribute: vi.fn((attr: string) => (attr === 'data-i18n-key' ? 'test.key' : null)),
+        textContent: 'test.key',
+        style: {},
+        title: '',
+      };
+
+      const container = {
+        querySelectorAll: vi.fn().mockReturnValue([mockElement]),
+      } as any;
+
+      tools?.highlightMissingKeys(container);
+
+      expect(container.querySelectorAll).toHaveBeenCalledWith('[data-i18n-key]');
+      expect(mockElement.style.backgroundColor).toBe('#ffeb3b');
+      expect(mockElement.style.border).toBe('2px solid #f57c00');
+      expect(mockElement.title).toBe('Missing translation: test.key');
+    });
+
+    it('should not highlight elements with translated text', () => {
+      process.env.NODE_ENV = 'development';
+      const tools = createDebugTools();
+
+      const mockElement = {
+        getAttribute: vi.fn((attr: string) => (attr === 'data-i18n-key' ? 'test.key' : null)),
+        textContent: 'Translated Text',
+        style: {},
+        title: '',
+      };
+
+      const container = {
+        querySelectorAll: vi.fn().mockReturnValue([mockElement]),
+      } as any;
+
+      tools?.highlightMissingKeys(container);
+
+      expect(mockElement.style.backgroundColor).toBeUndefined();
+      expect(mockElement.style.border).toBeUndefined();
+    });
+  });
+
+  describe('showTranslationKeys', () => {
+    it('should attach mouseenter and mouseleave event listeners', () => {
+      process.env.NODE_ENV = 'development';
+      const tools = createDebugTools();
+
+      const mockElement = {
+        getAttribute: vi.fn((attr: string) => (attr === 'data-i18n-key' ? 'test.key' : null)),
+        addEventListener: vi.fn(),
+        getBoundingClientRect: vi.fn().mockReturnValue({
+          left: 100,
+          top: 50,
+          bottom: 70,
+          right: 200,
+        }),
+      };
+
+      const container = {
+        querySelectorAll: vi.fn().mockReturnValue([mockElement]),
+      } as any;
+
+      tools?.showTranslationKeys(container);
+
+      expect(mockElement.addEventListener).toHaveBeenCalledWith('mouseenter', expect.any(Function));
+      expect(mockElement.addEventListener).toHaveBeenCalledWith('mouseleave', expect.any(Function));
+    });
+  });
+
+  describe('validateTranslations', () => {
+    it('should identify missing keys (null/undefined values)', () => {
+      process.env.NODE_ENV = 'development';
+      const tools = createDebugTools();
+
+      const translations = {
+        key1: 'value1',
+        key2: null,
+        key3: undefined,
+      };
+
+      const result = tools?.validateTranslations(translations);
+      expect(result?.missingKeys).toContain('key2');
+      expect(result?.missingKeys).toContain('key3');
+    });
+
+    it('should identify invalid keys (empty strings)', () => {
+      process.env.NODE_ENV = 'development';
+      const tools = createDebugTools();
+
+      const translations = {
+        '': 'value',
+        ' ': 'value',
+      };
+
+      const result = tools?.validateTranslations(translations);
+      expect(result?.invalidKeys.length).toBeGreaterThan(0);
+    });
+
+    it('should validate nested translations', () => {
+      process.env.NODE_ENV = 'development';
+      const tools = createDebugTools();
+
+      const translations = {
+        level1: {
+          level2: {
+            key1: 'value1',
+            key2: null,
+          },
+        },
+      };
+
+      const result = tools?.validateTranslations(translations);
+      expect(result?.missingKeys).toContain('level1.level2.key2');
+    });
+
+    it('should return empty arrays for valid translations', () => {
+      process.env.NODE_ENV = 'development';
+      const tools = createDebugTools();
+
+      const translations = {
+        key1: 'value1',
+        key2: 'value2',
+        nested: {
+          key3: 'value3',
+        },
+      };
+
+      const result = tools?.validateTranslations(translations);
+      expect(result?.missingKeys).toHaveLength(0);
+      expect(result?.duplicateKeys).toHaveLength(0);
+    });
+
+    it('should handle arrays in translations (ignore them)', () => {
+      process.env.NODE_ENV = 'development';
+      const tools = createDebugTools();
+
+      const translations = {
+        items: ['item1', 'item2', 'item3'],
+        key: 'value',
+      };
+
+      const result = tools?.validateTranslations(translations);
+      expect(result?.invalidKeys).not.toContain('items');
+    });
+  });
+
+  describe('devTools', () => {
+    it('should open devTools panel', () => {
+      process.env.NODE_ENV = 'development';
+      const tools = createDebugTools();
+
+      const mockButton = {
+        addEventListener: vi.fn(),
+      };
+
+      const mockPanel = {
+        id: '',
+        style: {},
+        appendChild: vi.fn(),
+        querySelector: vi.fn().mockReturnValue(mockButton),
+      };
+
+      (document.createElement as any).mockReturnValue(mockPanel);
+
+      tools?.devTools.open();
+
+      expect(document.body.appendChild).toHaveBeenCalled();
+    });
+
+    it('should close devTools panel', () => {
+      process.env.NODE_ENV = 'development';
+      const tools = createDebugTools();
+
+      const mockPanel = {
+        remove: vi.fn(),
+      };
+
+      (document.getElementById as any).mockReturnValue(mockPanel);
+
+      tools?.devTools.close();
+
+      expect(document.getElementById).toHaveBeenCalledWith('hua-i18n-devtools');
+      expect(mockPanel.remove).toHaveBeenCalled();
+    });
+  });
+
+  describe('enableDebugTools', () => {
+    it('should warn in production', () => {
+      process.env.NODE_ENV = 'production';
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+      enableDebugTools();
+
+      expect(warnSpy).toHaveBeenCalledWith('Debug tools are not available in production');
+      warnSpy.mockRestore();
+    });
+
+    it('should set global __HUA_I18N_DEBUG__ in development', () => {
+      process.env.NODE_ENV = 'development';
+      const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+
+      enableDebugTools();
+
+      expect((window as any).__HUA_I18N_DEBUG__).toBeDefined();
+      expect(logSpy).toHaveBeenCalledWith(
+        expect.stringContaining('HUA i18n debug tools enabled')
+      );
+      logSpy.mockRestore();
+    });
+
+    it('should open devTools panel automatically', () => {
+      process.env.NODE_ENV = 'development';
+      vi.spyOn(console, 'log').mockImplementation(() => {});
+
+      enableDebugTools();
+
+      expect(document.body.appendChild).toHaveBeenCalled();
+    });
+  });
+
+  describe('disableDebugTools', () => {
+    it('should remove global __HUA_I18N_DEBUG__', () => {
+      process.env.NODE_ENV = 'development';
+      vi.spyOn(console, 'log').mockImplementation(() => {});
+
+      enableDebugTools();
+      expect((window as any).__HUA_I18N_DEBUG__).toBeDefined();
+
+      disableDebugTools();
+      expect((window as any).__HUA_I18N_DEBUG__).toBeUndefined();
+    });
+
+    it('should close devTools panel', () => {
+      process.env.NODE_ENV = 'development';
+      vi.spyOn(console, 'log').mockImplementation(() => {});
+
+      const mockPanel = {
+        remove: vi.fn(),
+      };
+      (document.getElementById as any).mockReturnValue(mockPanel);
+
+      enableDebugTools();
+      disableDebugTools();
+
+      expect(document.getElementById).toHaveBeenCalledWith('hua-i18n-devtools');
+    });
+
+    it('should handle case when debug tools not enabled', () => {
+      process.env.NODE_ENV = 'development';
+
+      expect(() => disableDebugTools()).not.toThrow();
+    });
+  });
+});

package/src/__tests__/default-translations.test.ts

@@ -0,0 +1,179 @@
+import { describe, it, expect } from 'vitest';
+import { getDefaultTranslations, getAllDefaultTranslations } from '../utils/default-translations';
+
+describe('default-translations', () => {
+  describe('getDefaultTranslations', () => {
+    it('should return translations for valid language and namespace', () => {
+      const koCommon = getDefaultTranslations('ko', 'common');
+      expect(koCommon).toBeDefined();
+      expect(koCommon.welcome).toBe('환영합니다');
+      expect(koCommon.greeting).toBe('안녕하세요');
+      expect(koCommon.goodbye).toBe('안녕히 가세요');
+    });
+
+    it('should return Korean common translations', () => {
+      const translations = getDefaultTranslations('ko', 'common');
+      expect(translations.loading).toBe('로딩 중...');
+      expect(translations.error).toBe('오류가 발생했습니다');
+      expect(translations.success).toBe('성공했습니다');
+      expect(translations.cancel).toBe('취소');
+      expect(translations.confirm).toBe('확인');
+    });
+
+    it('should return Korean auth translations', () => {
+      const translations = getDefaultTranslations('ko', 'auth');
+      expect(translations.login).toBe('로그인');
+      expect(translations.logout).toBe('로그아웃');
+      expect(translations.register).toBe('회원가입');
+      expect(translations.email).toBe('이메일');
+      expect(translations.password).toBe('비밀번호');
+      expect(translations.forgot_password).toBe('비밀번호 찾기');
+      expect(translations.remember_me).toBe('로그인 상태 유지');
+    });
+
+    it('should return Korean errors translations', () => {
+      const translations = getDefaultTranslations('ko', 'errors');
+      expect(translations.not_found).toBe('페이지를 찾을 수 없습니다');
+      expect(translations.server_error).toBe('서버 오류가 발생했습니다');
+      expect(translations.network_error).toBe('네트워크 오류가 발생했습니다');
+      expect(translations.unauthorized).toBe('인증이 필요합니다');
+      expect(translations.forbidden).toBe('접근이 거부되었습니다');
+    });
+
+    it('should return English common translations', () => {
+      const translations = getDefaultTranslations('en', 'common');
+      expect(translations.welcome).toBe('Welcome');
+      expect(translations.greeting).toBe('Hello');
+      expect(translations.goodbye).toBe('Goodbye');
+      expect(translations.loading).toBe('Loading...');
+      expect(translations.error).toBe('An error occurred');
+      expect(translations.success).toBe('Success');
+    });
+
+    it('should return English auth translations', () => {
+      const translations = getDefaultTranslations('en', 'auth');
+      expect(translations.login).toBe('Login');
+      expect(translations.logout).toBe('Logout');
+      expect(translations.register).toBe('Register');
+      expect(translations.email).toBe('Email');
+      expect(translations.password).toBe('Password');
+      expect(translations.forgot_password).toBe('Forgot Password');
+      expect(translations.remember_me).toBe('Remember Me');
+    });
+
+    it('should return English errors translations', () => {
+      const translations = getDefaultTranslations('en', 'errors');
+      expect(translations.not_found).toBe('Page not found');
+      expect(translations.server_error).toBe('Server error occurred');
+      expect(translations.network_error).toBe('Network error occurred');
+      expect(translations.unauthorized).toBe('Authentication required');
+      expect(translations.forbidden).toBe('Access denied');
+    });
+
+    it('should return empty object for invalid language', () => {
+      const translations = getDefaultTranslations('fr', 'common');
+      expect(translations).toEqual({});
+    });
+
+    it('should return empty object for invalid namespace', () => {
+      const translations = getDefaultTranslations('ko', 'invalid');
+      expect(translations).toEqual({});
+    });
+
+    it('should return empty object for both invalid language and namespace', () => {
+      const translations = getDefaultTranslations('fr', 'invalid');
+      expect(translations).toEqual({});
+    });
+
+    it('should return empty object for undefined language', () => {
+      const translations = getDefaultTranslations('', 'common');
+      expect(translations).toEqual({});
+    });
+
+    it('should return empty object for undefined namespace', () => {
+      const translations = getDefaultTranslations('ko', '');
+      expect(translations).toEqual({});
+    });
+  });
+
+  describe('getAllDefaultTranslations', () => {
+    it('should return complete translations structure', () => {
+      const all = getAllDefaultTranslations();
+      expect(all).toBeDefined();
+      expect(all.ko).toBeDefined();
+      expect(all.en).toBeDefined();
+    });
+
+    it('should include all Korean namespaces', () => {
+      const all = getAllDefaultTranslations();
+      expect(all.ko.common).toBeDefined();
+      expect(all.ko.auth).toBeDefined();
+      expect(all.ko.errors).toBeDefined();
+    });
+
+    it('should include all English namespaces', () => {
+      const all = getAllDefaultTranslations();
+      expect(all.en.common).toBeDefined();
+      expect(all.en.auth).toBeDefined();
+      expect(all.en.errors).toBeDefined();
+    });
+
+    it('should have matching keys across languages', () => {
+      const all = getAllDefaultTranslations();
+      const koCommonKeys = Object.keys(all.ko.common);
+      const enCommonKeys = Object.keys(all.en.common);
+      expect(koCommonKeys).toEqual(enCommonKeys);
+    });
+
+    it('should have matching keys for auth namespace', () => {
+      const all = getAllDefaultTranslations();
+      const koAuthKeys = Object.keys(all.ko.auth);
+      const enAuthKeys = Object.keys(all.en.auth);
+      expect(koAuthKeys).toEqual(enAuthKeys);
+    });
+
+    it('should have matching keys for errors namespace', () => {
+      const all = getAllDefaultTranslations();
+      const koErrorsKeys = Object.keys(all.ko.errors);
+      const enErrorsKeys = Object.keys(all.en.errors);
+      expect(koErrorsKeys).toEqual(enErrorsKeys);
+    });
+
+    it('should return same reference on multiple calls', () => {
+      const all1 = getAllDefaultTranslations();
+      const all2 = getAllDefaultTranslations();
+      expect(all1).toBe(all2);
+    });
+
+    it('should contain expected number of common keys', () => {
+      const all = getAllDefaultTranslations();
+      const commonKeys = Object.keys(all.ko.common);
+      expect(commonKeys.length).toBeGreaterThan(15);
+      expect(commonKeys).toContain('welcome');
+      expect(commonKeys).toContain('greeting');
+      expect(commonKeys).toContain('loading');
+      expect(commonKeys).toContain('error');
+      expect(commonKeys).toContain('success');
+    });
+
+    it('should contain expected auth keys', () => {
+      const all = getAllDefaultTranslations();
+      const authKeys = Object.keys(all.ko.auth);
+      expect(authKeys).toContain('login');
+      expect(authKeys).toContain('logout');
+      expect(authKeys).toContain('register');
+      expect(authKeys).toContain('email');
+      expect(authKeys).toContain('password');
+    });
+
+    it('should contain expected error keys', () => {
+      const all = getAllDefaultTranslations();
+      const errorKeys = Object.keys(all.ko.errors);
+      expect(errorKeys).toContain('not_found');
+      expect(errorKeys).toContain('server_error');
+      expect(errorKeys).toContain('network_error');
+      expect(errorKeys).toContain('unauthorized');
+      expect(errorKeys).toContain('forbidden');
+    });
+  });
+});

package/src/__tests__/i18n-resource.test.ts

@@ -0,0 +1,137 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { I18nResourceManager } from '../core/i18n-resource';
+
+describe('I18nResourceManager', () => {
+  let manager: I18nResourceManager;
+
+  beforeEach(() => {
+    // Get singleton and reset it
+    manager = I18nResourceManager.getInstance();
+    manager.invalidateCache();
+  });
+
+  describe('getInstance', () => {
+    it('should return singleton instance', () => {
+      const a = I18nResourceManager.getInstance();
+      const b = I18nResourceManager.getInstance();
+      expect(a).toBe(b);
+    });
+  });
+
+  describe('getCachedTranslations', () => {
+    it('should call loader and cache result', async () => {
+      const loader = vi.fn().mockResolvedValue({ greeting: '안녕하세요' });
+      const result = await manager.getCachedTranslations('ko', 'common', loader);
+      expect(result).toEqual({ greeting: '안녕하세요' });
+      expect(loader).toHaveBeenCalledWith('ko', 'common');
+    });
+
+    it('should return cached result on second call', async () => {
+      const loader = vi.fn().mockResolvedValue({ greeting: '안녕하세요' });
+      await manager.getCachedTranslations('ko', 'common', loader);
+      const result = await manager.getCachedTranslations('ko', 'common', loader);
+      expect(result).toEqual({ greeting: '안녕하세요' });
+      expect(loader).toHaveBeenCalledTimes(1);
+    });
+
+    it('should deduplicate concurrent requests', async () => {
+      let resolvePromise: (value: any) => void;
+      const loader = vi.fn().mockImplementation(() => new Promise(resolve => { resolvePromise = resolve; }));
+
+      const p1 = manager.getCachedTranslations('ko', 'auth', loader);
+      const p2 = manager.getCachedTranslations('ko', 'auth', loader);
+
+      resolvePromise!({ login: '로그인' });
+
+      const [r1, r2] = await Promise.all([p1, p2]);
+      expect(r1).toEqual({ login: '로그인' });
+      expect(r2).toEqual({ login: '로그인' });
+      expect(loader).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe('getCachedTranslationsSync', () => {
+    it('should return null for uncached', () => {
+      expect(manager.getCachedTranslationsSync('fr', 'common')).toBeNull();
+    });
+
+    it('should return cached data', async () => {
+      const loader = vi.fn().mockResolvedValue({ key: 'value' });
+      await manager.getCachedTranslations('ko', 'test', loader);
+      expect(manager.getCachedTranslationsSync('ko', 'test')).toEqual({ key: 'value' });
+    });
+  });
+
+  describe('getAllTranslationsForLanguage', () => {
+    it('should return all namespaces for a language', async () => {
+      const loader = vi.fn().mockImplementation(async (lang: string, ns: string) => ({ [`${ns}_key`]: 'value' }));
+      await manager.getCachedTranslations('ko', 'common', loader);
+      await manager.getCachedTranslations('ko', 'auth', loader);
+
+      const all = manager.getAllTranslationsForLanguage('ko');
+      expect(Object.keys(all)).toContain('common');
+      expect(Object.keys(all)).toContain('auth');
+    });
+  });
+
+  describe('invalidateCache', () => {
+    it('should invalidate specific language/namespace', async () => {
+      const loader = vi.fn().mockResolvedValue({ key: 'value' });
+      await manager.getCachedTranslations('ko', 'common', loader);
+      manager.invalidateCache('ko', 'common');
+      expect(manager.getCachedTranslationsSync('ko', 'common')).toBeNull();
+    });
+
+    it('should invalidate all namespaces for a language', async () => {
+      const loader = vi.fn().mockResolvedValue({ key: 'value' });
+      await manager.getCachedTranslations('ko', 'common', loader);
+      await manager.getCachedTranslations('ko', 'auth', loader);
+      manager.invalidateCache('ko');
+      expect(manager.getCachedTranslationsSync('ko', 'common')).toBeNull();
+      expect(manager.getCachedTranslationsSync('ko', 'auth')).toBeNull();
+    });
+
+    it('should invalidate all cache when no args', async () => {
+      const loader = vi.fn().mockResolvedValue({ key: 'value' });
+      await manager.getCachedTranslations('ko', 'common', loader);
+      await manager.getCachedTranslations('en', 'common', loader);
+      manager.invalidateCache();
+      expect(manager.getCachedTranslationsSync('ko', 'common')).toBeNull();
+      expect(manager.getCachedTranslationsSync('en', 'common')).toBeNull();
+    });
+  });
+
+  describe('hydrateFromSSR', () => {
+    it('should populate cache from SSR data', () => {
+      manager.hydrateFromSSR({
+        ko: { common: { title: '제목' } },
+        en: { common: { title: 'Title' } },
+      });
+      expect(manager.getCachedTranslationsSync('ko', 'common')).toEqual({ title: '제목' });
+      expect(manager.getCachedTranslationsSync('en', 'common')).toEqual({ title: 'Title' });
+    });
+  });
+
+  describe('getCacheStats', () => {
+    it('should track hits and misses', async () => {
+      const loader = vi.fn().mockResolvedValue({ key: 'value' });
+      await manager.getCachedTranslations('ko', 'stats', loader); // miss
+      await manager.getCachedTranslations('ko', 'stats', loader); // hit
+      const stats = manager.getCacheStats();
+      expect(stats.misses).toBeGreaterThanOrEqual(1);
+      expect(stats.hits).toBeGreaterThanOrEqual(1);
+    });
+  });
+
+  describe('setCacheLimit', () => {
+    it('should evict entries when over limit', async () => {
+      const loader = vi.fn().mockImplementation(async (lang: string, ns: string) => ({ key: ns }));
+      await manager.getCachedTranslations('ko', 'ns1', loader);
+      await manager.getCachedTranslations('ko', 'ns2', loader);
+      await manager.getCachedTranslations('ko', 'ns3', loader);
+      manager.setCacheLimit(1);
+      const stats = manager.getCacheStats();
+      expect(stats.size).toBe(1);
+    });
+  });
+});