@hua-labs/i18n-core 2.0.0 → 2.0.4

package/src/__tests__/lazy-loader.test.ts

@@ -0,0 +1,109 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { LazyLoader } from '../core/lazy-loader';
+import { I18nResourceManager } from '../core/i18n-resource';
+
+describe('LazyLoader', () => {
+  let loader: LazyLoader;
+
+  beforeEach(() => {
+    loader = LazyLoader.getInstance();
+    // Reset the resource manager cache
+    I18nResourceManager.getInstance().invalidateCache();
+    loader.invalidateCache();
+  });
+
+  describe('getInstance', () => {
+    it('should return singleton', () => {
+      expect(LazyLoader.getInstance()).toBe(LazyLoader.getInstance());
+    });
+  });
+
+  describe('loadOnDemand', () => {
+    it('should load and return translations', async () => {
+      const mockLoader = vi.fn().mockResolvedValue({ key: 'value' });
+      const result = await loader.loadOnDemand('ko', 'common', mockLoader);
+      expect(result).toEqual({ key: 'value' });
+    });
+
+    it('should deduplicate concurrent loads', async () => {
+      const mockLoader = vi.fn().mockResolvedValue({ key: 'value' });
+      const [r1, r2] = await Promise.all([
+        loader.loadOnDemand('ko', 'dedup', mockLoader),
+        loader.loadOnDemand('ko', 'dedup', mockLoader),
+      ]);
+      expect(r1).toEqual({ key: 'value' });
+      expect(r2).toEqual({ key: 'value' });
+      // Should only call loader once (via resource manager dedup)
+      expect(mockLoader).toHaveBeenCalledTimes(1);
+    });
+
+    it('should return cached data on subsequent calls', async () => {
+      const mockLoader = vi.fn().mockResolvedValue({ cached: true });
+      await loader.loadOnDemand('ko', 'cached', mockLoader);
+      const result = await loader.loadOnDemand('ko', 'cached', mockLoader);
+      expect(result).toEqual({ cached: true });
+      expect(mockLoader).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe('preloadNamespace', () => {
+    it('should preload a namespace', async () => {
+      const mockLoader = vi.fn().mockResolvedValue({ preloaded: true });
+      await loader.preloadNamespace('ko', 'preload', mockLoader);
+      // Should be available immediately
+      const result = await loader.loadOnDemand('ko', 'preload', mockLoader);
+      expect(result).toEqual({ preloaded: true });
+    });
+
+    it('should skip already preloaded namespaces', async () => {
+      const mockLoader = vi.fn().mockResolvedValue({ data: true });
+      await loader.preloadNamespace('ko', 'skip', mockLoader);
+      await loader.preloadNamespace('ko', 'skip', mockLoader);
+      // Loader should be called only once
+      expect(mockLoader).toHaveBeenCalledTimes(1);
+    });
+
+    it('should silently fail on error', async () => {
+      const mockLoader = vi.fn().mockRejectedValue(new Error('fail'));
+      await expect(loader.preloadNamespace('ko', 'error', mockLoader)).resolves.toBeUndefined();
+    });
+  });
+
+  describe('preloadMultipleNamespaces', () => {
+    it('should preload multiple namespaces concurrently', async () => {
+      const mockLoader = vi.fn().mockResolvedValue({ multi: true });
+      await loader.preloadMultipleNamespaces('ko', ['ns1', 'ns2', 'ns3'], mockLoader);
+      expect(mockLoader).toHaveBeenCalledTimes(3);
+    });
+  });
+
+  describe('getLoadStats', () => {
+    it('should return loading statistics', async () => {
+      const mockLoader = vi.fn().mockResolvedValue({ stat: true });
+      await loader.loadOnDemand('ko', 'stats', mockLoader);
+      const stats = loader.getLoadStats();
+      expect(stats.loadHistorySize).toBeGreaterThanOrEqual(1);
+    });
+  });
+
+  describe('invalidateCache', () => {
+    it('should invalidate specific namespace', async () => {
+      const mockLoader = vi.fn().mockResolvedValue({ data: 'v1' });
+      await loader.loadOnDemand('ko', 'inv', mockLoader);
+      loader.invalidateCache('ko', 'inv');
+      // After invalidation, should call loader again
+      mockLoader.mockResolvedValue({ data: 'v2' });
+      const result = await loader.loadOnDemand('ko', 'inv', mockLoader);
+      expect(result).toEqual({ data: 'v2' });
+    });
+
+    it('should invalidate all cache when no args', async () => {
+      const mockLoader = vi.fn().mockResolvedValue({ data: true });
+      await loader.loadOnDemand('ko', 'all1', mockLoader);
+      await loader.loadOnDemand('ko', 'all2', mockLoader);
+      loader.invalidateCache();
+      const stats = loader.getLoadStats();
+      expect(stats.preloadedCount).toBe(0);
+    });
+  });
+});

package/src/__tests__/missing-key-overlay.test.tsx

@@ -0,0 +1,339 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { render, screen, waitFor, fireEvent } from '@testing-library/react';
+import React from 'react';
+import { MissingKeyOverlay, reportMissingKey, useMissingKeyOverlay } from '../components/MissingKeyOverlay';
+
+describe('MissingKeyOverlay', () => {
+  const originalEnv = process.env.NODE_ENV;
+
+  beforeEach(() => {
+    process.env.NODE_ENV = 'development';
+  });
+
+  afterEach(() => {
+    process.env.NODE_ENV = originalEnv;
+    vi.clearAllMocks();
+  });
+
+  describe('MissingKeyOverlay component', () => {
+    it('should not render when disabled', () => {
+      const { container } = render(<MissingKeyOverlay enabled={false} />);
+      expect(container.firstChild).toBeNull();
+    });
+
+    it('should not render in production by default', () => {
+      process.env.NODE_ENV = 'production';
+      const { container } = render(<MissingKeyOverlay />);
+      expect(container.firstChild).toBeNull();
+    });
+
+    it('should render when enabled and has missing keys', async () => {
+      render(<MissingKeyOverlay enabled={true} />);
+
+      reportMissingKey('test.key', { language: 'ko' });
+
+      await waitFor(() => {
+        expect(screen.getByText(/Missing Translation Keys/i)).toBeInTheDocument();
+      });
+    });
+
+    it('should display missing key details', async () => {
+      render(<MissingKeyOverlay enabled={true} />);
+
+      reportMissingKey('user.greeting', {
+        language: 'ko',
+        namespace: 'common',
+        component: 'Header',
+      });
+
+      await waitFor(() => {
+        expect(screen.getByText('user.greeting')).toBeInTheDocument();
+        expect(screen.getByText(/Lang: ko/)).toBeInTheDocument();
+        expect(screen.getByText(/NS: common/)).toBeInTheDocument();
+        expect(screen.getByText(/Component: Header/)).toBeInTheDocument();
+      });
+    });
+
+    it('should show count of missing keys', async () => {
+      render(<MissingKeyOverlay enabled={true} />);
+
+      reportMissingKey('key1', { language: 'ko' });
+      reportMissingKey('key2', { language: 'ko' });
+      reportMissingKey('key3', { language: 'en' });
+
+      await waitFor(() => {
+        expect(screen.getByText(/\(3\)/)).toBeInTheDocument();
+      });
+    });
+
+    it('should close when close button clicked', async () => {
+      const { container } = render(<MissingKeyOverlay enabled={true} />);
+
+      reportMissingKey('test.key', { language: 'ko' });
+
+      await waitFor(() => {
+        expect(screen.getByText(/Missing Translation Keys/i)).toBeInTheDocument();
+      });
+
+      const closeButton = screen.getByText('×');
+      fireEvent.click(closeButton);
+
+      await waitFor(() => {
+        expect(container.firstChild).toBeNull();
+      });
+    });
+
+    it('should clear keys when clear button clicked', async () => {
+      render(<MissingKeyOverlay enabled={true} />);
+
+      reportMissingKey('key1', { language: 'ko' });
+      reportMissingKey('key2', { language: 'ko' });
+
+      await waitFor(() => {
+        expect(screen.getByText(/\(2\)/)).toBeInTheDocument();
+      });
+
+      const clearButton = screen.getByText('Clear');
+      fireEvent.click(clearButton);
+
+      await waitFor(() => {
+        expect(screen.getByText(/\(0\)/)).toBeInTheDocument();
+      });
+    });
+
+    it('should show only last 10 keys', async () => {
+      render(<MissingKeyOverlay enabled={true} />);
+
+      for (let i = 0; i < 15; i++) {
+        reportMissingKey(`key${i}`, { language: 'ko' });
+      }
+
+      await waitFor(() => {
+        expect(screen.getByText(/... and 5 more/)).toBeInTheDocument();
+      });
+    });
+
+    it('should display timestamp for each key', async () => {
+      render(<MissingKeyOverlay enabled={true} />);
+
+      reportMissingKey('test.key', { language: 'ko' });
+
+      await waitFor(() => {
+        expect(screen.getByText(/Time:/)).toBeInTheDocument();
+      });
+    });
+
+    it('should respect position prop', () => {
+      const { container } = render(
+        <MissingKeyOverlay enabled={true} position="bottom-left" />
+      );
+
+      reportMissingKey('test.key', { language: 'ko' });
+
+      waitFor(() => {
+        const overlay = container.firstChild as HTMLElement;
+        expect(overlay?.style.bottom).toBe('20px');
+        expect(overlay?.style.left).toBe('20px');
+      });
+    });
+
+    it('should apply custom styles', async () => {
+      const customStyle = { backgroundColor: 'blue', zIndex: 5000 };
+      const { container } = render(
+        <MissingKeyOverlay enabled={true} style={customStyle} />
+      );
+
+      reportMissingKey('test.key', { language: 'ko' });
+
+      await waitFor(() => {
+        const overlay = container.firstChild as HTMLElement;
+        expect(overlay?.style.backgroundColor).toBeTruthy();
+        expect(overlay?.style.zIndex).toBeTruthy();
+      });
+    });
+
+    it('should handle keys without namespace', async () => {
+      render(<MissingKeyOverlay enabled={true} />);
+
+      reportMissingKey('simple.key', { language: 'en' });
+
+      await waitFor(() => {
+        expect(screen.getByText('simple.key')).toBeInTheDocument();
+        expect(screen.getByText(/Lang: en/)).toBeInTheDocument();
+      });
+    });
+
+    it('should handle keys without component', async () => {
+      render(<MissingKeyOverlay enabled={true} />);
+
+      reportMissingKey('test.key', {
+        language: 'ko',
+        namespace: 'common',
+      });
+
+      await waitFor(() => {
+        expect(screen.getByText('test.key')).toBeInTheDocument();
+        expect(screen.queryByText(/Component:/)).not.toBeInTheDocument();
+      });
+    });
+  });
+
+  describe('reportMissingKey', () => {
+    it('should dispatch custom event with key details', () => {
+      const eventSpy = vi.spyOn(window, 'dispatchEvent');
+
+      reportMissingKey('test.key', {
+        language: 'ko',
+        namespace: 'common',
+        component: 'TestComponent',
+      });
+
+      expect(eventSpy).toHaveBeenCalledWith(
+        expect.objectContaining({
+          type: 'i18n:missing-key',
+          detail: expect.objectContaining({
+            key: 'test.key',
+            language: 'ko',
+            namespace: 'common',
+            component: 'TestComponent',
+            timestamp: expect.any(Number),
+          }),
+        })
+      );
+
+      eventSpy.mockRestore();
+    });
+
+    it('should log warning to console in development', () => {
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+      reportMissingKey('test.key', { language: 'ko' });
+
+      expect(warnSpy).toHaveBeenCalledWith(
+        expect.stringContaining('Missing translation key: test.key'),
+        expect.objectContaining({
+          language: 'ko',
+        })
+      );
+
+      warnSpy.mockRestore();
+    });
+
+    it('should not dispatch event in production', () => {
+      process.env.NODE_ENV = 'production';
+      const eventSpy = vi.spyOn(window, 'dispatchEvent');
+
+      reportMissingKey('test.key', { language: 'ko' });
+
+      expect(eventSpy).not.toHaveBeenCalled();
+      eventSpy.mockRestore();
+    });
+
+    it('should handle missing namespace', () => {
+      const eventSpy = vi.spyOn(window, 'dispatchEvent');
+
+      reportMissingKey('test.key', { language: 'ko' });
+
+      expect(eventSpy).toHaveBeenCalledWith(
+        expect.objectContaining({
+          detail: expect.objectContaining({
+            key: 'test.key',
+            namespace: undefined,
+          }),
+        })
+      );
+
+      eventSpy.mockRestore();
+    });
+
+    it('should handle missing component', () => {
+      const eventSpy = vi.spyOn(window, 'dispatchEvent');
+
+      reportMissingKey('test.key', {
+        language: 'en',
+        namespace: 'auth',
+      });
+
+      expect(eventSpy).toHaveBeenCalledWith(
+        expect.objectContaining({
+          detail: expect.objectContaining({
+            key: 'test.key',
+            component: undefined,
+          }),
+        })
+      );
+
+      eventSpy.mockRestore();
+    });
+  });
+
+  describe('useMissingKeyOverlay', () => {
+    function TestComponent({ enabled }: { enabled?: boolean }) {
+      const { showOverlay, setShowOverlay, reportMissingKey: report } = useMissingKeyOverlay(enabled);
+
+      return (
+        <div>
+          <div data-testid="show-overlay">{showOverlay ? 'true' : 'false'}</div>
+          <button onClick={() => setShowOverlay(false)}>Hide</button>
+          <button onClick={() => report('test.key', { language: 'ko' })}>Report</button>
+        </div>
+      );
+    }
+
+    it('should return showOverlay true by default in development', () => {
+      render(<TestComponent />);
+      expect(screen.getByTestId('show-overlay')).toHaveTextContent('true');
+    });
+
+    it('should return showOverlay false when disabled', () => {
+      render(<TestComponent enabled={false} />);
+      expect(screen.getByTestId('show-overlay')).toHaveTextContent('false');
+    });
+
+    it('should return setShowOverlay function', () => {
+      render(<TestComponent />);
+      const hideButton = screen.getByText('Hide');
+
+      expect(screen.getByTestId('show-overlay')).toHaveTextContent('true');
+
+      fireEvent.click(hideButton);
+
+      expect(screen.getByTestId('show-overlay')).toHaveTextContent('false');
+    });
+
+    it('should return reportMissingKey function', () => {
+      const eventSpy = vi.spyOn(window, 'dispatchEvent');
+      render(<TestComponent />);
+
+      const reportButton = screen.getByText('Report');
+      fireEvent.click(reportButton);
+
+      expect(eventSpy).toHaveBeenCalledWith(
+        expect.objectContaining({
+          type: 'i18n:missing-key',
+        })
+      );
+
+      eventSpy.mockRestore();
+    });
+
+    it('should respect enabled prop on mount', async () => {
+      // When enabled changes from true to false via rerender, the hook's useEffect
+      // only sets showOverlay to true, it doesn't set it to false
+      // So changing the prop won't change the state after initial render
+      const { unmount } = render(<TestComponent enabled={true} />);
+      expect(screen.getByTestId('show-overlay')).toHaveTextContent('true');
+      unmount();
+
+      // Re-mount with enabled=false should show false
+      render(<TestComponent enabled={false} />);
+      expect(screen.getByTestId('show-overlay')).toHaveTextContent('false');
+    });
+
+    it('should respect initial enabled=false', () => {
+      // When initially rendered with enabled=false, showOverlay should be false
+      render(<TestComponent enabled={false} />);
+      expect(screen.getByTestId('show-overlay')).toHaveTextContent('false');
+    });
+  });
+});

package/src/__tests__/translator-factory.test.ts

@@ -0,0 +1,120 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+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().mockResolvedValue({}),
+    ...overrides,
+  };
+}
+
+describe('TranslatorFactory', () => {
+  beforeEach(() => {
+    TranslatorFactory.clear();
+  });
+
+  describe('create', () => {
+    it('should create a new translator instance', () => {
+      const config = createMockConfig();
+      const translator = TranslatorFactory.create(config);
+      expect(translator).toBeDefined();
+      expect(TranslatorFactory.getInstanceCount()).toBe(1);
+    });
+
+    it('should return same instance for same config', () => {
+      const config = createMockConfig();
+      const t1 = TranslatorFactory.create(config);
+      const t2 = TranslatorFactory.create(config);
+      expect(t1).toBe(t2);
+      expect(TranslatorFactory.getInstanceCount()).toBe(1);
+    });
+
+    it('should create different instances for different configs', () => {
+      const config1 = createMockConfig({ defaultLanguage: 'ko' });
+      const config2 = createMockConfig({ defaultLanguage: 'en' });
+      const t1 = TranslatorFactory.create(config1);
+      const t2 = TranslatorFactory.create(config2);
+      expect(t1).not.toBe(t2);
+      expect(TranslatorFactory.getInstanceCount()).toBe(2);
+    });
+
+    it('should evict oldest instance when max reached', () => {
+      // MAX_INSTANCES is 10
+      for (let i = 0; i < 10; i++) {
+        TranslatorFactory.create(createMockConfig({
+          defaultLanguage: `lang-${i}`,
+          fallbackLanguage: 'en',
+        }));
+      }
+      expect(TranslatorFactory.getInstanceCount()).toBe(10);
+
+      // Adding 11th should evict the first
+      TranslatorFactory.create(createMockConfig({
+        defaultLanguage: 'lang-10',
+        fallbackLanguage: 'en',
+      }));
+      expect(TranslatorFactory.getInstanceCount()).toBe(10);
+    });
+
+    it('should recreate instance when config changes', () => {
+      const config1 = createMockConfig({ debug: false });
+      const t1 = TranslatorFactory.create(config1);
+      const config2 = createMockConfig({ debug: true });
+      const t2 = TranslatorFactory.create(config2);
+      // Different debug means different config key, so different instance
+      expect(t1).not.toBe(t2);
+    });
+  });
+
+  describe('get', () => {
+    it('should return existing instance', () => {
+      const config = createMockConfig();
+      const created = TranslatorFactory.create(config);
+      const retrieved = TranslatorFactory.get(config);
+      expect(retrieved).toBe(created);
+    });
+
+    it('should return null for non-existing config', () => {
+      const config = createMockConfig({ defaultLanguage: 'fr' });
+      expect(TranslatorFactory.get(config)).toBeNull();
+    });
+  });
+
+  describe('clear', () => {
+    it('should clear all instances', () => {
+      TranslatorFactory.create(createMockConfig());
+      expect(TranslatorFactory.getInstanceCount()).toBe(1);
+      TranslatorFactory.clear();
+      expect(TranslatorFactory.getInstanceCount()).toBe(0);
+    });
+  });
+
+  describe('clearConfig', () => {
+    it('should clear specific config instance', () => {
+      const config1 = createMockConfig({ defaultLanguage: 'ko' });
+      const config2 = createMockConfig({ defaultLanguage: 'en' });
+      TranslatorFactory.create(config1);
+      TranslatorFactory.create(config2);
+      expect(TranslatorFactory.getInstanceCount()).toBe(2);
+      TranslatorFactory.clearConfig(config1);
+      expect(TranslatorFactory.getInstanceCount()).toBe(1);
+    });
+  });
+
+  describe('debug', () => {
+    it('should return debug info', () => {
+      TranslatorFactory.create(createMockConfig());
+      const info = TranslatorFactory.debug();
+      expect(info.instanceCount).toBe(1);
+      expect(info.configKeys).toHaveLength(1);
+    });
+  });
+});