@hua-labs/i18n-core 1.0.0

package/src/components/MissingKeyOverlay.tsx

@@ -0,0 +1,223 @@
+import React, { useEffect, useState } from 'react';
+
+interface MissingKeyOverlayProps {
+  enabled?: boolean;
+  position?: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left';
+  style?: React.CSSProperties;
+}
+
+interface MissingKey {
+  key: string;
+  namespace?: string;
+  language: string;
+  timestamp: number;
+  component?: string;
+}
+
+/**
+ * 개발 모드에서 누락된 번역 키를 화면에 표시하는 오버레이
+ * Lingui 스타일의 디버그 모드
+ */
+export const MissingKeyOverlay: React.FC<MissingKeyOverlayProps> = ({
+  enabled = process.env.NODE_ENV === 'development',
+  position = 'top-right',
+  style
+}) => {
+  const [missingKeys, setMissingKeys] = useState<MissingKey[]>([]);
+  const [isVisible, setIsVisible] = useState(false);
+
+  useEffect(() => {
+    if (!enabled) return;
+
+    // 누락된 키 이벤트 리스너
+    const handleMissingKey = (event: CustomEvent<MissingKey>) => {
+      setMissingKeys(prev => [...prev, event.detail]);
+      setIsVisible(true);
+    };
+
+    // 전역 이벤트 리스너 등록
+    window.addEventListener('i18n:missing-key', handleMissingKey as EventListener);
+
+    return () => {
+      window.removeEventListener('i18n:missing-key', handleMissingKey as EventListener);
+    };
+  }, [enabled]);
+
+  if (!enabled || !isVisible) return null;
+
+  const positionStyles = {
+    'top-right': { top: 20, right: 20 },
+    'top-left': { top: 20, left: 20 },
+    'bottom-right': { bottom: 20, right: 20 },
+    'bottom-left': { bottom: 20, left: 20 }
+  };
+
+  const overlayStyle: React.CSSProperties = {
+    position: 'fixed',
+    zIndex: 9999,
+    backgroundColor: 'rgba(255, 0, 0, 0.9)',
+    color: 'white',
+    padding: '12px 16px',
+    borderRadius: '8px',
+    fontFamily: 'monospace',
+    fontSize: '12px',
+    maxWidth: '400px',
+    maxHeight: '300px',
+    overflow: 'auto',
+    boxShadow: '0 4px 12px rgba(0, 0, 0, 0.3)',
+    border: '2px solid #ff4444',
+    ...positionStyles[position],
+    ...style
+  };
+
+  const keyStyle: React.CSSProperties = {
+    marginBottom: '8px',
+    padding: '4px 8px',
+    backgroundColor: 'rgba(255, 255, 255, 0.1)',
+    borderRadius: '4px',
+    borderLeft: '3px solid #ff8888'
+  };
+
+  const headerStyle: React.CSSProperties = {
+    display: 'flex',
+    justifyContent: 'space-between',
+    alignItems: 'center',
+    marginBottom: '12px',
+    paddingBottom: '8px',
+    borderBottom: '1px solid rgba(255, 255, 255, 0.3)'
+  };
+
+  const closeButtonStyle: React.CSSProperties = {
+    background: 'none',
+    border: 'none',
+    color: 'white',
+    cursor: 'pointer',
+    fontSize: '16px',
+    padding: '0',
+    width: '20px',
+    height: '20px',
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'center'
+  };
+
+  const clearButtonStyle: React.CSSProperties = {
+    background: 'rgba(255, 255, 255, 0.2)',
+    border: 'none',
+    color: 'white',
+    cursor: 'pointer',
+    padding: '4px 8px',
+    borderRadius: '4px',
+    fontSize: '10px',
+    marginLeft: '8px'
+  };
+
+  const handleClose = () => {
+    setIsVisible(false);
+  };
+
+  const handleClear = () => {
+    setMissingKeys([]);
+  };
+
+  const formatTime = (timestamp: number) => {
+    return new Date(timestamp).toLocaleTimeString();
+  };
+
+  return (
+    <div style={overlayStyle}>
+      <div style={headerStyle}>
+        <div>
+          <strong>🚨 Missing Translation Keys</strong>
+          <span style={{ fontSize: '10px', marginLeft: '8px' }}>
+            ({missingKeys.length})
+          </span>
+        </div>
+        <div>
+          <button style={clearButtonStyle} onClick={handleClear}>
+            Clear
+          </button>
+          <button style={closeButtonStyle} onClick={handleClose}>
+            ×
+          </button>
+        </div>
+      </div>
+      
+      <div>
+        {missingKeys.slice(-10).reverse().map((key, index) => (
+          <div key={`${key.key}-${key.timestamp}`} style={keyStyle}>
+            <div style={{ fontWeight: 'bold', color: '#ffcccc' }}>
+              {key.key}
+            </div>
+            <div style={{ fontSize: '10px', marginTop: '2px' }}>
+              <span>Lang: {key.language}</span>
+              {key.namespace && <span style={{ marginLeft: '8px' }}>NS: {key.namespace}</span>}
+              <span style={{ marginLeft: '8px' }}>Time: {formatTime(key.timestamp)}</span>
+            </div>
+            {key.component && (
+              <div style={{ fontSize: '10px', color: '#ffaaaa', marginTop: '2px' }}>
+                Component: {key.component}
+              </div>
+            )}
+          </div>
+        ))}
+        
+        {missingKeys.length > 10 && (
+          <div style={{ fontSize: '10px', textAlign: 'center', marginTop: '8px' }}>
+            ... and {missingKeys.length - 10} more
+          </div>
+        )}
+      </div>
+    </div>
+  );
+};
+
+/**
+ * 누락된 키를 오버레이에 표시하는 유틸리티 함수
+ */
+export const reportMissingKey = (key: string, options: {
+  namespace?: string;
+  language: string;
+  component?: string;
+}) => {
+  if (process.env.NODE_ENV === 'development') {
+    const missingKey: MissingKey = {
+      key,
+      namespace: options.namespace,
+      language: options.language,
+      timestamp: Date.now(),
+      component: options.component
+    };
+
+    // 커스텀 이벤트 발생
+    window.dispatchEvent(new CustomEvent('i18n:missing-key', {
+      detail: missingKey
+    }));
+
+    // 콘솔에도 로그
+    console.warn(`Missing translation key: ${key}`, {
+      namespace: options.namespace,
+      language: options.language,
+      component: options.component
+    });
+  }
+};
+
+/**
+ * 누락된 키 오버레이를 자동으로 활성화하는 훅
+ */
+export const useMissingKeyOverlay = (enabled = true) => {
+  const [showOverlay, setShowOverlay] = useState(enabled);
+
+  useEffect(() => {
+    if (enabled && process.env.NODE_ENV === 'development') {
+      setShowOverlay(true);
+    }
+  }, [enabled]);
+
+  return {
+    showOverlay,
+    setShowOverlay,
+    reportMissingKey
+  };
+}; 

package/src/core/debug-tools.ts

@@ -0,0 +1,298 @@
+/**
+ * 조건부 디버깅 도구 - 개발 환경에서만 로드
+ * 번들 크기 최적화를 위해 조건부 로딩
+ */
+
+export interface DebugTools {
+  // 번역 키 시각화
+  highlightMissingKeys: (container: HTMLElement) => void;
+  showTranslationKeys: (container: HTMLElement) => void;
+  
+  // 성능 모니터링
+  performanceMetrics: {
+    translationCount: number;
+    cacheHits: number;
+    cacheMisses: number;
+    loadTimes: number[];
+  };
+  
+  // 개발자 도구
+  devTools: {
+    open: () => void;
+    close: () => void;
+    isOpen: boolean;
+  };
+  
+  // 번역 데이터 검증
+  validateTranslations: (translations: Record<string, unknown>) => {
+    missingKeys: string[];
+    duplicateKeys: string[];
+    invalidKeys: string[];
+  };
+}
+
+/**
+ * 디버깅 도구 팩토리 - 조건부 로딩
+ */
+export function createDebugTools(): DebugTools | null {
+  // 프로덕션에서는 디버깅 도구 비활성화
+  if (process.env.NODE_ENV === 'production') {
+    return null;
+  }
+
+  // 개발 환경에서만 로드
+  return {
+    highlightMissingKeys: (container: HTMLElement) => {
+      const elements = container.querySelectorAll('[data-i18n-key]');
+      elements.forEach((element) => {
+        const key = element.getAttribute('data-i18n-key');
+        const text = element.textContent;
+        
+        // 번역 키가 텍스트와 다른 경우 하이라이트
+        if (key && text === key) {
+          (element as HTMLElement).style.backgroundColor = '#ffeb3b';
+          (element as HTMLElement).style.border = '2px solid #f57c00';
+          (element as HTMLElement).title = `Missing translation: ${key}`;
+        }
+      });
+    },
+
+    showTranslationKeys: (container: HTMLElement) => {
+      const elements = container.querySelectorAll('[data-i18n-key]');
+      elements.forEach((element) => {
+        const key = element.getAttribute('data-i18n-key');
+        if (key) {
+          const tooltip = document.createElement('div');
+          tooltip.style.cssText = `
+            position: absolute;
+            background: #333;
+            color: white;
+            padding: 4px 8px;
+            border-radius: 4px;
+            font-size: 12px;
+            z-index: 10000;
+            pointer-events: none;
+            opacity: 0;
+            transition: opacity 0.2s;
+          `;
+          tooltip.textContent = `Key: ${key}`;
+          
+          element.addEventListener('mouseenter', () => {
+            const rect = element.getBoundingClientRect();
+            tooltip.style.left = `${rect.left}px`;
+            tooltip.style.top = `${rect.bottom + 5}px`;
+            tooltip.style.opacity = '1';
+            document.body.appendChild(tooltip);
+          });
+          
+          element.addEventListener('mouseleave', () => {
+            tooltip.style.opacity = '0';
+            setTimeout(() => {
+              if (tooltip.parentNode) {
+                tooltip.parentNode.removeChild(tooltip);
+              }
+            }, 200);
+          });
+        }
+      });
+    },
+
+    performanceMetrics: {
+      translationCount: 0,
+      cacheHits: 0,
+      cacheMisses: 0,
+      loadTimes: [],
+    },
+
+    devTools: {
+      isOpen: false,
+      open: () => {
+        const devTools = createDevToolsPanel();
+        document.body.appendChild(devTools);
+        (devTools as HTMLElement & { isOpen?: boolean }).isOpen = true;
+      },
+      close: () => {
+        const existingPanel = document.getElementById('hua-i18n-devtools');
+        if (existingPanel) {
+          existingPanel.remove();
+        }
+        // devTools 변수는 이 스코프에서 접근할 수 없으므로 전역에서 관리
+        const globalDebugTools = (window as Window & { __HUA_I18N_DEBUG__?: DebugTools }).__HUA_I18N_DEBUG__;
+        if (globalDebugTools) {
+          globalDebugTools.devTools.isOpen = false;
+        }
+      },
+    },
+
+    validateTranslations: (translations: Record<string, unknown>) => {
+      const missingKeys: string[] = [];
+      const duplicateKeys: string[] = [];
+      const invalidKeys: string[] = [];
+      const seenKeys = new Set<string>();
+
+      const traverse = (obj: unknown, path: string = '') => {
+        if (typeof obj !== 'object' || obj === null || Array.isArray(obj)) {
+          return;
+        }
+        for (const [key, value] of Object.entries(obj)) {
+          const currentPath = path ? `${path}.${key}` : key;
+          
+          // 키 유효성 검사
+          if (typeof key !== 'string' || key.trim() === '') {
+            invalidKeys.push(currentPath);
+          }
+          
+          // 중복 키 검사
+          if (seenKeys.has(currentPath)) {
+            duplicateKeys.push(currentPath);
+          } else {
+            seenKeys.add(currentPath);
+          }
+          
+          // 값 검사
+          if (value === null || value === undefined) {
+            missingKeys.push(currentPath);
+          } else if (typeof value === 'object' && !Array.isArray(value)) {
+            traverse(value, currentPath);
+          }
+        }
+      };
+
+      traverse(translations);
+      
+      return { missingKeys, duplicateKeys, invalidKeys };
+    },
+  };
+}
+
+/**
+ * 개발자 도구 패널 생성
+ */
+function createDevToolsPanel(): HTMLElement {
+  const panel = document.createElement('div');
+  panel.id = 'hua-i18n-devtools';
+  panel.style.cssText = `
+    position: fixed;
+    top: 20px;
+    right: 20px;
+    width: 300px;
+    max-height: 500px;
+    background: #1e1e1e;
+    color: #fff;
+    border-radius: 8px;
+    box-shadow: 0 4px 20px rgba(0,0,0,0.3);
+    z-index: 10000;
+    font-family: 'Monaco', 'Menlo', monospace;
+    font-size: 12px;
+    overflow: hidden;
+  `;
+
+  const header = document.createElement('div');
+  header.style.cssText = `
+    background: #2d2d2d;
+    padding: 12px;
+    border-bottom: 1px solid #444;
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+  `;
+  header.innerHTML = `
+    <span style="font-weight: bold;">HUA i18n Debug</span>
+    <button id="close-devtools" style="background: none; border: none; color: #fff; cursor: pointer; font-size: 16px;">×</button>
+  `;
+
+  const content = document.createElement('div');
+  content.style.cssText = `
+    padding: 12px;
+    max-height: 400px;
+    overflow-y: auto;
+  `;
+
+  // 성능 메트릭
+  const metricsSection = document.createElement('div');
+  metricsSection.innerHTML = `
+    <h4 style="margin: 0 0 8px 0; color: #4fc3f7;">Performance</h4>
+    <div>Translations: <span id="translation-count">0</span></div>
+    <div>Cache Hits: <span id="cache-hits">0</span></div>
+    <div>Cache Misses: <span id="cache-misses">0</span></div>
+    <div>Hit Rate: <span id="hit-rate">0%</span></div>
+  `;
+
+  // 현재 언어 정보
+  const languageSection = document.createElement('div');
+  languageSection.style.marginTop = '16px';
+  languageSection.innerHTML = `
+    <h4 style="margin: 0 0 8px 0; color: #4fc3f7;">Current Language</h4>
+    <div>Language: <span id="current-language">ko</span></div>
+    <div>Fallback: <span id="fallback-language">en</span></div>
+  `;
+
+  // 액션 버튼들
+  const actionsSection = document.createElement('div');
+  actionsSection.style.marginTop = '16px';
+  actionsSection.innerHTML = `
+    <h4 style="margin: 0 0 8px 0; color: #4fc3f7;">Actions</h4>
+    <button id="highlight-missing" style="background: #4fc3f7; border: none; color: #000; padding: 4px 8px; border-radius: 4px; cursor: pointer; margin-right: 8px;">Highlight Missing</button>
+    <button id="show-keys" style="background: #4fc3f7; border: none; color: #000; padding: 4px 8px; border-radius: 4px; cursor: pointer;">Show Keys</button>
+  `;
+
+  content.appendChild(metricsSection);
+  content.appendChild(languageSection);
+  content.appendChild(actionsSection);
+
+  panel.appendChild(header);
+  panel.appendChild(content);
+
+  // 이벤트 리스너
+  panel.querySelector('#close-devtools')?.addEventListener('click', () => {
+    panel.remove();
+  });
+
+  panel.querySelector('#highlight-missing')?.addEventListener('click', () => {
+    const debugTools = createDebugTools();
+    if (debugTools) {
+      debugTools.highlightMissingKeys(document.body);
+    }
+  });
+
+  panel.querySelector('#show-keys')?.addEventListener('click', () => {
+    const debugTools = createDebugTools();
+    if (debugTools) {
+      debugTools.showTranslationKeys(document.body);
+    }
+  });
+
+  return panel;
+}
+
+/**
+ * 디버깅 도구 활성화 (전역 함수)
+ */
+export function enableDebugTools(): void {
+  if (process.env.NODE_ENV === 'production') {
+    console.warn('Debug tools are not available in production');
+    return;
+  }
+
+  const debugTools = createDebugTools();
+  if (!debugTools) return;
+
+  // 전역 객체에 추가
+  (window as Window & { __HUA_I18N_DEBUG__?: DebugTools }).__HUA_I18N_DEBUG__ = debugTools;
+
+  // 개발자 도구 열기
+  debugTools.devTools.open();
+
+  console.log('HUA i18n debug tools enabled. Use window.__HUA_I18N_DEBUG__ to access.');
+}
+
+/**
+ * 디버깅 도구 비활성화
+ */
+export function disableDebugTools(): void {
+  const debugTools = (window as Window & { __HUA_I18N_DEBUG__?: DebugTools }).__HUA_I18N_DEBUG__;
+  if (debugTools) {
+    debugTools.devTools.close();
+    delete (window as Window & { __HUA_I18N_DEBUG__?: DebugTools }).__HUA_I18N_DEBUG__;
+  }
+} 

package/src/core/i18n-resource.ts

@@ -0,0 +1,180 @@
+import { TranslationNamespace, TranslationData } from '../types';
+
+/**
+ * i18n 리소스 관리자
+ * SSR 환경에서 동일 번역 요청 중복 방지 및 전역 캐시 관리
+ */
+export class I18nResourceManager {
+  private static instance: I18nResourceManager;
+  private globalCache = new Map<string, TranslationNamespace>();
+  private loadingPromises = new Map<string, Promise<TranslationNamespace>>();
+  private cacheStats = {
+    hits: 0,
+    misses: 0,
+    size: 0
+  };
+
+  private constructor() {}
+
+  static getInstance(): I18nResourceManager {
+    if (!I18nResourceManager.instance) {
+      I18nResourceManager.instance = new I18nResourceManager();
+    }
+    return I18nResourceManager.instance;
+  }
+
+  /**
+   * 전역 캐시에서 번역 데이터 가져오기
+   */
+  async getCachedTranslations(
+    language: string, 
+    namespace: string, 
+    loader: (lang: string, ns: string) => Promise<TranslationNamespace>
+  ): Promise<TranslationNamespace> {
+    const cacheKey = `${language}:${namespace}`;
+    
+    // 캐시에 있으면 반환
+    if (this.globalCache.has(cacheKey)) {
+      this.cacheStats.hits++;
+      return this.globalCache.get(cacheKey)!;
+    }
+
+    // 이미 로딩 중이면 기존 Promise 반환
+    if (this.loadingPromises.has(cacheKey)) {
+      return this.loadingPromises.get(cacheKey)!;
+    }
+
+    // 새로 로딩
+    this.cacheStats.misses++;
+    const loadPromise = loader(language, namespace).then(data => {
+      this.globalCache.set(cacheKey, data);
+      this.cacheStats.size = this.globalCache.size;
+      this.loadingPromises.delete(cacheKey);
+      return data;
+    });
+
+    this.loadingPromises.set(cacheKey, loadPromise);
+    return loadPromise;
+  }
+
+  /**
+   * 캐시된 번역 데이터 직접 접근
+   */
+  getCachedTranslationsSync(language: string, namespace: string): TranslationNamespace | null {
+    const cacheKey = `${language}:${namespace}`;
+    return this.globalCache.get(cacheKey) || null;
+  }
+
+  /**
+   * 특정 언어의 모든 네임스페이스 가져오기
+   */
+  getAllTranslationsForLanguage(language: string): Record<string, TranslationNamespace> {
+    const result: Record<string, TranslationNamespace> = {};
+    
+    for (const [key, data] of this.globalCache.entries()) {
+      if (key.startsWith(`${language}:`)) {
+        const namespace = key.split(':')[1];
+        result[namespace] = data;
+      }
+    }
+    
+    return result;
+  }
+
+  /**
+   * 모든 캐시된 번역 데이터 가져오기
+   */
+  getAllCachedTranslations(): Record<string, Record<string, TranslationNamespace>> {
+    const result: Record<string, Record<string, TranslationNamespace>> = {};
+    
+    for (const [key, data] of this.globalCache.entries()) {
+      const [language, namespace] = key.split(':');
+      if (!result[language]) {
+        result[language] = {};
+      }
+      result[language][namespace] = data;
+    }
+    
+    return result;
+  }
+
+  /**
+   * 캐시 통계 가져오기
+   */
+  getCacheStats() {
+    return {
+      ...this.cacheStats,
+      hitRate: this.cacheStats.hits / (this.cacheStats.hits + this.cacheStats.misses)
+    };
+  }
+
+  /**
+   * 캐시 무효화
+   */
+  invalidateCache(language?: string, namespace?: string): void {
+    if (language && namespace) {
+      // 특정 언어/네임스페이스만 무효화
+      const cacheKey = `${language}:${namespace}`;
+      this.globalCache.delete(cacheKey);
+      this.loadingPromises.delete(cacheKey);
+    } else if (language) {
+      // 특정 언어의 모든 네임스페이스 무효화
+      for (const key of this.globalCache.keys()) {
+        if (key.startsWith(`${language}:`)) {
+          this.globalCache.delete(key);
+          this.loadingPromises.delete(key);
+        }
+      }
+    } else {
+      // 전체 캐시 무효화
+      this.globalCache.clear();
+      this.loadingPromises.clear();
+    }
+    
+    this.cacheStats.size = this.globalCache.size;
+  }
+
+  /**
+   * 캐시 크기 제한 설정
+   */
+  setCacheLimit(maxSize: number): void {
+    if (this.globalCache.size > maxSize) {
+      // LRU 방식으로 오래된 항목 제거
+      const entries = Array.from(this.globalCache.entries());
+      const toRemove = entries.slice(0, this.globalCache.size - maxSize);
+      
+      for (const [key] of toRemove) {
+        this.globalCache.delete(key);
+      }
+      
+      this.cacheStats.size = this.globalCache.size;
+    }
+  }
+
+  /**
+   * SSR 환경에서 하이드레이션
+   */
+  hydrateFromSSR(translations: Record<string, Record<string, TranslationNamespace>>): void {
+    for (const [language, namespaces] of Object.entries(translations)) {
+      for (const [namespace, data] of Object.entries(namespaces)) {
+        const cacheKey = `${language}:${namespace}`;
+        this.globalCache.set(cacheKey, data);
+      }
+    }
+    
+    this.cacheStats.size = this.globalCache.size;
+  }
+
+  /**
+   * 메모리 사용량 최적화
+   */
+  optimizeMemory(): void {
+    // 사용되지 않는 번역 데이터 정리
+    // 실제 구현에서는 사용 통계를 기반으로 정리
+  }
+}
+
+/**
+ * 전역 리소스 매니저 인스턴스
+ */
+export const i18nResourceManager = I18nResourceManager.getInstance();