@hua-labs/i18n-core 1.0.0

package/dist/core/translator.js

@@ -0,0 +1,912 @@
+import { isTranslationNamespace, validateI18nConfig, isRecoverableError } from '../types';
+export class Translator {
+    /**
+     * 번역 로드 완료 콜백 등록
+     */
+    onTranslationLoaded(callback) {
+        this.onTranslationLoadedCallbacks.add(callback);
+        return () => {
+            this.onTranslationLoadedCallbacks.delete(callback);
+        };
+    }
+    /**
+     * 언어 변경 콜백 등록
+     */
+    onLanguageChanged(callback) {
+        this.onLanguageChangedCallbacks.add(callback);
+        return () => {
+            this.onLanguageChangedCallbacks.delete(callback);
+        };
+    }
+    /**
+     * 언어 변경 이벤트 발생
+     */
+    notifyLanguageChanged(language) {
+        this.onLanguageChangedCallbacks.forEach(callback => {
+            try {
+                callback(language);
+            }
+            catch (error) {
+                if (this.config.debug) {
+                    console.error('Error in language changed callback:', error);
+                }
+            }
+        });
+    }
+    /**
+     * 번역 로드 완료 이벤트 발생 (디바운싱 적용)
+     */
+    notifyTranslationLoaded(language, namespace) {
+        const cacheKey = `${language}:${namespace}`;
+        // 최근에 알림한 네임스페이스는 스킵 (중복 알림 방지)
+        if (this.recentlyNotified.has(cacheKey)) {
+            return;
+        }
+        this.recentlyNotified.add(cacheKey);
+        // 디바운싱: 짧은 시간 내 여러 번역이 로드되면 한 번만 알림
+        if (this.notifyTimer) {
+            clearTimeout(this.notifyTimer);
+        }
+        this.notifyTimer = setTimeout(() => {
+            this.onTranslationLoadedCallbacks.forEach(callback => {
+                try {
+                    callback();
+                }
+                catch (error) {
+                    if (this.config.debug) {
+                        console.warn('Error in translation loaded callback:', error);
+                    }
+                }
+            });
+            // 100ms 후 recentlyNotified 초기화 (같은 네임스페이스도 다시 알림 가능하도록)
+            setTimeout(() => {
+                this.recentlyNotified.clear();
+            }, 100);
+            this.notifyTimer = null;
+        }, 50); // 50ms 디바운싱
+    }
+    constructor(config) {
+        this.cache = new Map();
+        this.loadedNamespaces = new Set();
+        this.loadingPromises = new Map();
+        this.allTranslations = {};
+        this.isInitialized = false;
+        this.initializationError = null;
+        this.currentLang = 'en';
+        this.cacheStats = {
+            hits: 0,
+            misses: 0,
+        };
+        // 번역 로드 완료 시 React 리렌더링을 위한 콜백
+        this.onTranslationLoadedCallbacks = new Set();
+        // 언어 변경 시 React 리렌더링을 위한 콜백
+        this.onLanguageChangedCallbacks = new Set();
+        // 디바운싱을 위한 타이머
+        this.notifyTimer = null;
+        // 최근 알림한 네임스페이스 (중복 알림 방지)
+        this.recentlyNotified = new Set();
+        if (!validateI18nConfig(config)) {
+            throw new Error('Invalid I18nConfig provided');
+        }
+        this.config = {
+            fallbackLanguage: 'en',
+            namespaces: ['common'],
+            debug: false,
+            missingKeyHandler: (key) => key,
+            errorHandler: (error) => {
+                // Silent by default, user can override
+            },
+            ...config
+        };
+        this.currentLang = config.defaultLanguage;
+        // SSR에서 전달된 초기 번역 데이터가 있으면 즉시 설정 (네트워크 요청 없음)
+        if (config.initialTranslations) {
+            this.allTranslations = config.initialTranslations;
+            // 로드된 네임스페이스 마킹
+            for (const [language, namespaces] of Object.entries(config.initialTranslations)) {
+                for (const namespace of Object.keys(namespaces)) {
+                    this.loadedNamespaces.add(`${language}:${namespace}`);
+                }
+            }
+            if (this.config.debug) {
+                console.log('✅ [TRANSLATOR] Initial translations loaded from SSR:', this.loadedNamespaces);
+            }
+        }
+    }
+    /**
+     * 모든 번역 데이터를 미리 로드 (hua-api 스타일)
+     */
+    async initialize() {
+        if (this.isInitialized) {
+            if (this.config.debug) {
+                console.log('🚫 [TRANSLATOR] Already initialized, skipping');
+            }
+            return;
+        }
+        if (this.config.debug) {
+            console.log('🚀 [TRANSLATOR] Starting initialization...');
+        }
+        try {
+            // Ensure allTranslations is initialized
+            if (!this.allTranslations) {
+                this.allTranslations = {};
+            }
+            const languages = [this.currentLang];
+            if (this.config.fallbackLanguage && this.config.fallbackLanguage !== this.currentLang) {
+                languages.push(this.config.fallbackLanguage);
+            }
+            // 초기 번역 데이터가 이미 있으면 해당 네임스페이스는 스킵
+            const skipNamespaces = new Set();
+            for (const language of languages) {
+                if (this.allTranslations[language]) {
+                    for (const namespace of Object.keys(this.allTranslations[language])) {
+                        skipNamespaces.add(`${language}:${namespace}`);
+                    }
+                }
+            }
+            if (this.config.debug) {
+                console.log('🌍 [TRANSLATOR] Initializing translator with languages:', languages);
+                console.log('📍 [TRANSLATOR] Current language:', this.currentLang);
+                console.log('📦 [TRANSLATOR] Config namespaces:', this.config.namespaces);
+            }
+            for (const language of languages) {
+                if (this.config.debug) {
+                    console.log('Processing language:', language);
+                }
+                if (!this.allTranslations[language]) {
+                    this.allTranslations[language] = {};
+                }
+                for (const namespace of this.config.namespaces || []) {
+                    const cacheKey = `${language}:${namespace}`;
+                    // 이미 초기 번역 데이터가 있으면 스킵 (네트워크 요청 없음)
+                    if (skipNamespaces.has(cacheKey)) {
+                        if (this.config.debug) {
+                            console.log('⏭️ [TRANSLATOR] Skipping', namespace, 'for', language, '(already loaded from SSR)');
+                        }
+                        continue;
+                    }
+                    if (this.config.debug) {
+                        console.log('Loading namespace:', namespace, 'for language:', language);
+                    }
+                    try {
+                        const data = await this.safeLoadTranslations(language, namespace);
+                        if (this.config.debug) {
+                            console.log('Loaded data for', language, namespace, ':', data);
+                        }
+                        this.allTranslations[language][namespace] = data;
+                        this.loadedNamespaces.add(`${language}:${namespace}`);
+                    }
+                    catch (error) {
+                        const translationError = this.createTranslationError('LOAD_FAILED', error, language, namespace);
+                        this.logError(translationError);
+                        // 복구 가능한 에러인지 확인
+                        if (isRecoverableError(translationError)) {
+                            // 폴백 언어로 시도
+                            if (language !== this.config.fallbackLanguage) {
+                                try {
+                                    const fallbackData = await this.safeLoadTranslations(this.config.fallbackLanguage || 'en', namespace);
+                                    this.allTranslations[language][namespace] = fallbackData;
+                                    this.loadedNamespaces.add(`${language}:${namespace}`);
+                                    if (this.config.debug) {
+                                        console.log('Using fallback data for', language, namespace);
+                                    }
+                                }
+                                catch (fallbackError) {
+                                    const fallbackTranslationError = this.createTranslationError('FALLBACK_LOAD_FAILED', fallbackError, this.config.fallbackLanguage, namespace);
+                                    this.logError(fallbackTranslationError);
+                                    // 기본 번역 데이터 사용
+                                    this.allTranslations[language][namespace] = {};
+                                }
+                            }
+                            else {
+                                // 기본 번역 데이터 사용
+                                this.allTranslations[language][namespace] = {};
+                            }
+                        }
+                        else {
+                            // 복구 불가능한 에러는 기본 번역 데이터 사용
+                            this.allTranslations[language][namespace] = {};
+                        }
+                    }
+                }
+            }
+            this.isInitialized = true;
+            if (this.config.debug) {
+                console.log('Translator initialized successfully');
+                console.log('Loaded translations:', this.allTranslations);
+            }
+        }
+        catch (error) {
+            this.initializationError = this.createTranslationError('INITIALIZATION_FAILED', error);
+            this.logError(this.initializationError);
+            // 에러가 발생해도 초기화 완료로 표시 (기본 번역 사용)
+            this.isInitialized = true;
+            if (this.config.debug) {
+                console.warn('Translator initialized with errors, using fallback translations');
+            }
+        }
+    }
+    /**
+     * 초기화되지 않은 상태에서 번역 시도
+     */
+    translateBeforeInitialized(key, targetLang) {
+        if (this.config.debug) {
+            console.warn('Translator not initialized. Call initialize() first.');
+        }
+        const { namespace, key: actualKey } = this.parseKey(key);
+        const translations = this.allTranslations[targetLang]?.[namespace];
+        if (this.config.debug) {
+            console.log(`🔍 [TRANSLATOR] Not initialized, trying fallback:`, {
+                namespace,
+                actualKey,
+                translations,
+                hasTranslation: translations && translations[actualKey]
+            });
+        }
+        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;
+    }
+    /**
+     * 다른 로드된 언어에서 번역 찾기 (언어 변경 중 깜빡임 방지)
+     */
+    findInOtherLanguages(namespace, key, targetLang) {
+        if (!this.allTranslations || Object.keys(this.allTranslations).length === 0) {
+            return null;
+        }
+        const loadedLanguages = Object.keys(this.allTranslations);
+        for (const lang of loadedLanguages) {
+            if (lang !== targetLang) {
+                const result = this.findInNamespace(namespace, key, lang);
+                if (result) {
+                    return result;
+                }
+            }
+        }
+        return null;
+    }
+    /**
+     * 폴백 언어에서 번역 찾기
+     */
+    findInFallbackLanguage(namespace, key, targetLang) {
+        const fallbackLang = this.config.fallbackLanguage || 'en';
+        if (targetLang === fallbackLang) {
+            return null;
+        }
+        const result = this.findInNamespace(namespace, key, fallbackLang);
+        if (result) {
+            this.cacheStats.hits++;
+            return result;
+        }
+        return null;
+    }
+    /**
+     * 번역 키를 번역된 텍스트로 변환
+     */
+    translate(key, language) {
+        const targetLang = language || this.currentLang;
+        // 초기화되지 않은 경우 처리
+        if (!this.isInitialized) {
+            return this.translateBeforeInitialized(key, targetLang);
+        }
+        const { namespace, key: actualKey } = this.parseKey(key);
+        // 1단계: 현재 언어에서 찾기
+        let result = this.findInNamespace(namespace, actualKey, targetLang);
+        if (result) {
+            this.cacheStats.hits++;
+            return result;
+        }
+        // 2단계: 다른 로드된 언어에서 찾기 (언어 변경 중 깜빡임 방지)
+        result = this.findInOtherLanguages(namespace, actualKey, targetLang);
+        if (result) {
+            return result;
+        }
+        // 3단계: 폴백 언어에서 찾기
+        result = this.findInFallbackLanguage(namespace, actualKey, targetLang);
+        if (result) {
+            return result;
+        }
+        // 모든 단계에서 찾지 못한 경우
+        this.cacheStats.misses++;
+        if (this.config.debug) {
+            return this.config.missingKeyHandler?.(key, targetLang, namespace) || key;
+        }
+        // 프로덕션에서는 빈 문자열 반환 (미싱 키 노출 방지)
+        return '';
+    }
+    /**
+     * 네임스페이스에서 키 찾기
+     */
+    findInNamespace(namespace, key, language) {
+        const translations = this.allTranslations[language]?.[namespace];
+        if (!translations) {
+            // 네임스페이스가 없으면 자동으로 로드 시도 (비동기, 백그라운드)
+            const cacheKey = `${language}:${namespace}`;
+            if (!this.loadedNamespaces.has(cacheKey) && !this.loadingPromises.has(cacheKey)) {
+                // 로딩 시작 (비동기, 즉시 반환하지 않음)
+                this.loadTranslationData(language, namespace).catch(error => {
+                    if (this.config.debug) {
+                        console.warn(`⚠️ [TRANSLATOR] Auto-load failed for ${language}/${namespace}:`, error);
+                    }
+                });
+                // 디버그 모드에서만 첫 시도 시에만 경고 출력 (중복 방지)
+                if (this.config.debug) {
+                    console.warn(`❌ [TRANSLATOR] No translations found for ${language}/${namespace}, attempting auto-load...`);
+                }
+            }
+            return '';
+        }
+        // 직접 키 매칭
+        const directValue = translations[key];
+        if (this.isStringValue(directValue)) {
+            return directValue;
+        }
+        // 중첩 키 매칭 (예: "user.profile.name")
+        const nestedValue = this.getNestedValue(translations, key);
+        if (this.isStringValue(nestedValue)) {
+            return nestedValue;
+        }
+        if (this.config.debug) {
+            console.warn(`❌ [TRANSLATOR] No match found for key: ${key} in ${language}/${namespace}`);
+        }
+        return '';
+    }
+    /**
+     * 중첩된 객체에서 값을 가져오기
+     */
+    getNestedValue(obj, path) {
+        if (typeof obj !== 'object' || obj === null || Array.isArray(obj)) {
+            return undefined;
+        }
+        return path.split('.').reduce((current, key) => {
+            if (current && typeof current === 'object' && !Array.isArray(current) && key in current) {
+                return current[key];
+            }
+            return undefined;
+        }, obj);
+    }
+    /**
+     * 문자열 값인지 확인하는 타입 가드
+     */
+    isStringValue(value) {
+        return typeof value === 'string' && value.length > 0;
+    }
+    /**
+     * 원시 값 가져오기 (배열, 객체 포함)
+     */
+    getRawValue(key, language) {
+        const targetLang = language || this.currentLang;
+        if (!this.isInitialized) {
+            if (this.config.debug) {
+                console.warn('Translator not initialized. Call initialize() first.');
+            }
+            return undefined;
+        }
+        const { namespace, key: actualKey } = this.parseKey(key);
+        const translations = this.allTranslations[targetLang]?.[namespace];
+        if (!translations) {
+            return undefined;
+        }
+        // 직접 키 매칭
+        if (actualKey in translations) {
+            return translations[actualKey];
+        }
+        // 중첩 키 매칭
+        const nestedValue = this.getNestedValue(translations, actualKey);
+        if (nestedValue !== undefined) {
+            return nestedValue;
+        }
+        // 폴백 언어에서 찾기
+        if (targetLang !== this.config.fallbackLanguage) {
+            const fallbackTranslations = this.allTranslations[this.config.fallbackLanguage || 'en']?.[namespace];
+            if (fallbackTranslations) {
+                if (actualKey in fallbackTranslations) {
+                    return fallbackTranslations[actualKey];
+                }
+                const fallbackNestedValue = this.getNestedValue(fallbackTranslations, actualKey);
+                if (fallbackNestedValue !== undefined) {
+                    return fallbackNestedValue;
+                }
+            }
+        }
+        return undefined;
+    }
+    /**
+     * 매개변수 보간
+     */
+    interpolate(text, params) {
+        return text.replace(/\{\{(\w+)\}\}/g, (match, key) => {
+            const value = params[key];
+            return value !== undefined ? String(value) : match;
+        });
+    }
+    /**
+     * 매개변수가 있는 번역
+     */
+    translateWithParams(key, params, language) {
+        const translated = this.translate(key, language);
+        if (!params) {
+            return translated;
+        }
+        return this.interpolate(translated, params);
+    }
+    /**
+     * 언어 설정
+     */
+    setLanguage(language) {
+        if (this.currentLang === language) {
+            return;
+        }
+        const previousLanguage = this.currentLang;
+        this.currentLang = language;
+        // 언어 변경 이벤트 발생
+        this.notifyLanguageChanged(language);
+        // 새로운 언어의 데이터가 로드되지 않았다면 로드
+        if (!this.allTranslations[language]) {
+            this.loadLanguageData(language).catch(error => {
+                if (this.config.debug) {
+                    console.warn('Failed to load language data:', error);
+                }
+            });
+        }
+        if (this.config.debug) {
+            console.log(`🌐 [TRANSLATOR] Language changed: ${previousLanguage} -> ${language}`);
+        }
+    }
+    /**
+     * 언어 데이터 로드
+     */
+    async loadLanguageData(language) {
+        if (!this.allTranslations[language]) {
+            this.allTranslations[language] = {};
+        }
+        for (const namespace of this.config.namespaces || []) {
+            try {
+                const data = await this.safeLoadTranslations(language, namespace);
+                this.allTranslations[language][namespace] = data;
+                this.loadedNamespaces.add(`${language}:${namespace}`);
+                // 언어 변경 시 번역 로드 완료 알림
+                this.notifyTranslationLoaded(language, namespace);
+            }
+            catch (error) {
+                const translationError = this.createTranslationError('LOAD_FAILED', error, language, namespace);
+                this.logError(translationError);
+                // 복구 가능한 에러인지 확인
+                if (isRecoverableError(translationError)) {
+                    // 재시도는 safeLoadTranslations 내부에서 처리되므로 여기서는 기본값 사용
+                    this.allTranslations[language][namespace] = {};
+                }
+                else {
+                    // 복구 불가능한 에러는 기본 번역 데이터 사용
+                    this.allTranslations[language][namespace] = {};
+                }
+            }
+        }
+    }
+    /**
+     * 현재 언어 가져오기
+     */
+    getCurrentLanguage() {
+        return this.currentLang;
+    }
+    /**
+     * 지원되는 언어 목록 가져오기
+     */
+    getSupportedLanguages() {
+        return this.config.supportedLanguages?.map(lang => lang.code) || [];
+    }
+    /**
+     * 초기화 완료 여부 확인
+     */
+    isReady() {
+        return this.isInitialized && !this.initializationError;
+    }
+    /**
+     * 초기화 오류 가져오기
+     */
+    getInitializationError() {
+        return this.initializationError;
+    }
+    /**
+     * 캐시 클리어
+     */
+    clearCache() {
+        this.cache.clear();
+        this.cacheStats = { hits: 0, misses: 0 };
+        if (this.config.debug) {
+            console.log('Cache cleared');
+        }
+    }
+    /**
+     * 캐시 엔트리 설정
+     */
+    setCacheEntry(key, data) {
+        this.cache.set(key, {
+            data,
+            timestamp: Date.now(),
+            ttl: 5 * 60 * 1000 // 5분
+        });
+    }
+    /**
+     * 캐시 엔트리 가져오기
+     */
+    getCacheEntry(key) {
+        const entry = this.cache.get(key);
+        if (!entry) {
+            return null;
+        }
+        // TTL 체크
+        if (Date.now() - entry.timestamp > entry.ttl) {
+            this.cache.delete(key);
+            return null;
+        }
+        return entry.data;
+    }
+    /**
+     * 번역 오류 생성
+     */
+    createTranslationError(code, originalError, language, namespace, key) {
+        return {
+            name: 'TranslationError',
+            code,
+            message: originalError.message,
+            originalError,
+            language,
+            namespace,
+            key,
+            timestamp: Date.now(),
+            stack: originalError.stack
+        };
+    }
+    /**
+     * 오류 로깅
+     */
+    logError(error) {
+        if (this.config.errorHandler) {
+            this.config.errorHandler(error, error.language || '', error.namespace || '');
+        }
+    }
+    /**
+     * 재시도 작업
+     */
+    async retryOperation(operation, error, context) {
+        const maxRetries = 3;
+        let lastError = error;
+        for (let attempt = 1; attempt <= maxRetries; attempt++) {
+            try {
+                return await operation();
+            }
+            catch (retryError) {
+                lastError = this.createTranslationError('RETRY_FAILED', retryError, context.language, context.namespace, context.key);
+                if (attempt === maxRetries) {
+                    break;
+                }
+                // 지수 백오프
+                await new Promise(resolve => setTimeout(resolve, Math.pow(2, attempt) * 1000));
+            }
+        }
+        throw lastError;
+    }
+    /**
+     * 안전한 번역 로드
+     */
+    async safeLoadTranslations(language, namespace) {
+        if (this.config.debug) {
+            console.log(`📥 [TRANSLATOR] safeLoadTranslations called:`, { language, namespace });
+        }
+        const loadOperation = async () => {
+            if (!this.config.loadTranslations) {
+                throw new Error('No translation loader configured');
+            }
+            if (this.config.debug) {
+                console.log(`🔄 [TRANSLATOR] Calling loadTranslations for:`, { language, namespace });
+            }
+            const data = await this.config.loadTranslations(language, namespace);
+            if (this.config.debug) {
+                console.log(`📦 [TRANSLATOR] loadTranslations returned:`, data);
+            }
+            if (!isTranslationNamespace(data)) {
+                throw new Error(`Invalid translation data for ${language}:${namespace}`);
+            }
+            return data;
+        };
+        try {
+            return await loadOperation();
+        }
+        catch (error) {
+            const translationError = this.createTranslationError('LOAD_FAILED', error, language, namespace);
+            return this.retryOperation(loadOperation, translationError, { language, namespace });
+        }
+    }
+    /**
+     * 디버그 정보
+     */
+    debug() {
+        return {
+            isInitialized: this.isInitialized,
+            currentLanguage: this.currentLang,
+            loadedNamespaces: Array.from(this.loadedNamespaces),
+            cacheStats: this.cacheStats,
+            cacheSize: this.cache.size,
+            allTranslations: this.allTranslations,
+            initializationError: this.initializationError,
+            config: this.config
+        };
+    }
+    /**
+     * SSR에서 하이드레이션
+     */
+    hydrateFromSSR(translations) {
+        this.allTranslations = translations;
+        this.isInitialized = true;
+        // 로드된 네임스페이스 업데이트
+        for (const [language, namespaces] of Object.entries(translations)) {
+            for (const namespace of Object.keys(namespaces)) {
+                this.loadedNamespaces.add(`${language}:${namespace}`);
+            }
+        }
+    }
+    /**
+     * 비동기 번역 (고급 기능)
+     */
+    async translateAsync(key, params) {
+        if (!this.isInitialized) {
+            await this.initialize();
+        }
+        const translated = this.translate(key);
+        if (!params) {
+            return translated;
+        }
+        return this.interpolate(translated, params);
+    }
+    /**
+     * 동기 번역 (고급 기능)
+     */
+    translateSync(key, params) {
+        if (!this.isInitialized) {
+            if (this.config.debug) {
+                console.warn('Translator not initialized for sync translation');
+            }
+            const { namespace } = this.parseKey(key);
+            return this.config.missingKeyHandler?.(key, this.currentLang, namespace) || key;
+        }
+        const translated = this.translate(key);
+        if (!params) {
+            return translated;
+        }
+        return this.interpolate(translated, params);
+    }
+    /**
+     * 키 파싱 (네임스페이스:키 또는 네임스페이스.키 형식 지원)
+     * 우선순위: : > . (첫 번째 구분자 사용)
+     */
+    parseKey(key) {
+        // : 구분자 우선 확인
+        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 네임스페이스로 간주
+        return { namespace: 'common', key };
+    }
+    /**
+     * 번역 데이터 로드 (고급 기능)
+     */
+    async loadTranslationData(language, namespace) {
+        const cacheKey = `${language}:${namespace}`;
+        // 이미 로드된 네임스페이스인지 확인
+        if (this.loadedNamespaces.has(cacheKey)) {
+            const existing = this.allTranslations[language]?.[namespace];
+            if (existing) {
+                return existing;
+            }
+        }
+        // 캐시에서 확인
+        const cached = this.getCacheEntry(cacheKey);
+        if (cached) {
+            // 캐시에 있으면 allTranslations에도 저장
+            if (!this.allTranslations[language]) {
+                this.allTranslations[language] = {};
+            }
+            this.allTranslations[language][namespace] = cached;
+            this.loadedNamespaces.add(cacheKey);
+            return cached;
+        }
+        // 로딩 중인지 확인
+        const loadingPromise = this.loadingPromises.get(cacheKey);
+        if (loadingPromise) {
+            return loadingPromise;
+        }
+        // 새로 로드
+        const loadPromise = this._loadTranslationData(language, namespace);
+        this.loadingPromises.set(cacheKey, loadPromise);
+        try {
+            const data = await loadPromise;
+            // allTranslations에 저장 (중요: 이렇게 해야 findInNamespace에서 찾을 수 있음)
+            if (!this.allTranslations[language]) {
+                this.allTranslations[language] = {};
+            }
+            this.allTranslations[language][namespace] = data;
+            this.loadedNamespaces.add(cacheKey);
+            // 캐시에도 저장
+            this.setCacheEntry(cacheKey, data);
+            if (this.config.debug) {
+                console.log(`✅ [TRANSLATOR] Auto-loaded and saved ${language}/${namespace}`);
+            }
+            // React 리렌더링 트리거 (디바운싱 적용)
+            this.notifyTranslationLoaded(language, namespace);
+            return data;
+        }
+        finally {
+            this.loadingPromises.delete(cacheKey);
+        }
+    }
+    /**
+     * 실제 번역 데이터 로드
+     */
+    async _loadTranslationData(language, namespace) {
+        if (!this.config.loadTranslations) {
+            throw new Error('No translation loader configured');
+        }
+        try {
+            const data = await this.config.loadTranslations(language, namespace);
+            if (!isTranslationNamespace(data)) {
+                throw new Error(`Invalid translation data for ${language}:${namespace}`);
+            }
+            return data;
+        }
+        catch (error) {
+            const translationError = this.createTranslationError('LOAD_FAILED', error, language, namespace);
+            this.logError(translationError);
+            // 기본 번역 데이터 반환
+            return {};
+        }
+    }
+}
+// SSR 번역 함수들
+export function ssrTranslate({ translations, key, language = 'ko', fallbackLanguage = 'en', missingKeyHandler = (key) => key }) {
+    const { namespace, key: actualKey } = parseKey(key);
+    // 현재 언어에서 찾기
+    let result = ssrFindInNamespace(translations, namespace, actualKey, language, fallbackLanguage, missingKeyHandler);
+    if (result) {
+        return result;
+    }
+    // 폴백 언어에서 찾기
+    if (language !== fallbackLanguage) {
+        result = ssrFindInNamespace(translations, namespace, actualKey, fallbackLanguage, fallbackLanguage, missingKeyHandler);
+        if (result) {
+            return result;
+        }
+    }
+    return missingKeyHandler(key);
+}
+function ssrFindInNamespace(translations, namespace, key, language, fallbackLanguage, missingKeyHandler) {
+    const namespaceData = translations[language]?.[namespace];
+    if (!namespaceData) {
+        return '';
+    }
+    // 직접 키 매칭
+    const directValue = namespaceData[key];
+    if (isStringValue(directValue)) {
+        return directValue;
+    }
+    // 중첩 키 매칭
+    const nestedValue = getNestedValue(namespaceData, key);
+    if (isStringValue(nestedValue)) {
+        return nestedValue;
+    }
+    return '';
+}
+function getNestedValue(obj, path) {
+    if (typeof obj !== 'object' || obj === null || Array.isArray(obj)) {
+        return undefined;
+    }
+    return path.split('.').reduce((current, key) => {
+        if (current && typeof current === 'object' && !Array.isArray(current) && key in current) {
+            return current[key];
+        }
+        return undefined;
+    }, obj);
+}
+/**
+ * 문자열 값인지 확인하는 타입 가드
+ */
+function isStringValue(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+function parseKey(key) {
+    // : 구분자 우선 확인
+    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 네임스페이스로 간주
+    return { namespace: 'common', key };
+}
+// 서버 번역 함수 (고급 기능 포함)
+export function serverTranslate({ translations, key, language = 'ko', fallbackLanguage = 'en', missingKeyHandler = (key) => key, options = {} }) {
+    const { cache, metrics, debug } = options;
+    // 캐시에서 확인
+    if (cache) {
+        const cacheKey = `${language}:${key}`;
+        const cached = cache.get(cacheKey);
+        if (cached) {
+            if (metrics)
+                metrics.hits++;
+            if (debug)
+                console.log(`[CACHE HIT] ${cacheKey}`);
+            return cached;
+        }
+    }
+    // 번역 찾기
+    const result = findInTranslations(translations, key, language, fallbackLanguage, missingKeyHandler);
+    // 캐시에 저장
+    if (cache && result) {
+        const cacheKey = `${language}:${key}`;
+        cache.set(cacheKey, result);
+    }
+    if (metrics)
+        metrics.misses++;
+    if (debug)
+        console.log(`[TRANSLATE] ${key} -> ${result}`);
+    return result;
+}
+function findInTranslations(translations, key, language, fallbackLanguage, missingKeyHandler) {
+    const { namespace, key: actualKey } = parseKey(key);
+    // 현재 언어에서 찾기
+    let result = findInNamespace(translations, namespace, actualKey, language);
+    if (result) {
+        return result;
+    }
+    // 폴백 언어에서 찾기
+    if (language !== fallbackLanguage) {
+        result = findInNamespace(translations, namespace, actualKey, fallbackLanguage);
+        if (result) {
+            return result;
+        }
+    }
+    return '';
+}
+function findInNamespace(translations, namespace, key, language) {
+    // 언어 데이터 가져오기
+    const languageData = translations[language];
+    // 언어 데이터가 객체인지 확인
+    if (!languageData || typeof languageData !== 'object' || Array.isArray(languageData)) {
+        return '';
+    }
+    // 네임스페이스 데이터 가져오기
+    const namespaceData = languageData[namespace];
+    if (!namespaceData || typeof namespaceData !== 'object' || Array.isArray(namespaceData)) {
+        return '';
+    }
+    // 타입 단언: namespaceData는 객체임을 확인했으므로 Record로 단언
+    const data = namespaceData;
+    // 직접 키 매칭
+    if (data[key] && typeof data[key] === 'string') {
+        return data[key];
+    }
+    // 중첩 키 매칭
+    const nestedValue = getNestedValue(namespaceData, key);
+    if (typeof nestedValue === 'string') {
+        return nestedValue;
+    }
+    return '';
+}
+//# sourceMappingURL=translator.js.map