@hua-labs/i18n-core 2.0.0 → 2.0.4

package/src/hooks/useI18n.tsx

@@ -160,7 +160,7 @@ export function I18nProvider({
       }
     };
 
-    // hua-i18n-sdk 언어 전환 이벤트 감지
+    // HUA i18n 언어 전환 이벤트 감지
     window.addEventListener('huaI18nLanguageChange', handleLanguageChange as EventListener);
     
     // 일반적인 언어 변경 이벤트도 감지
@@ -226,6 +226,26 @@ export function I18nProvider({
     return { namespace: 'common', key };
   }, []);
 
+  // 네스티드 키 해석 (예: "nav.docs" → obj.nav.docs)
+  const resolveNestedKey = useCallback((obj: Record<string, unknown>, key: string): string | null => {
+    // 1차: flat 접근 시도 (키에 점이 없거나 flat 구조인 경우)
+    if (key in obj && typeof obj[key] === 'string') {
+      return obj[key] as string;
+    }
+
+    // 2차: 네스티드 접근 (점 경로 탐색)
+    const parts = key.split('.');
+    let current: unknown = obj;
+    for (const part of parts) {
+      if (current && typeof current === 'object' && current !== null && part in (current as Record<string, unknown>)) {
+        current = (current as Record<string, unknown>)[part];
+      } else {
+        return null;
+      }
+    }
+    return typeof current === 'string' ? current : null;
+  }, []);
+
   // SSR 번역에서 찾기
   const findInSSRTranslations = useCallback((key: string, targetLang: string): string | null => {
     if (!config.initialTranslations) {
@@ -233,90 +253,102 @@ export function I18nProvider({
     }
 
     const { namespace, key: actualKey } = parseKey(key);
-    
+
     // 현재 언어의 SSR 번역 확인
     const ssrTranslations = config.initialTranslations[targetLang]?.[namespace];
-    if (ssrTranslations && ssrTranslations[actualKey]) {
-      const value = ssrTranslations[actualKey];
-      if (typeof value === 'string') {
+    if (ssrTranslations) {
+      const value = resolveNestedKey(ssrTranslations as Record<string, unknown>, actualKey);
+      if (value !== null) {
         return value;
       }
     }
-    
+
     // 폴백 언어의 SSR 번역 확인
     const fallbackLang = config.fallbackLanguage || 'en';
     if (targetLang !== fallbackLang) {
       const fallbackTranslations = config.initialTranslations[fallbackLang]?.[namespace];
-      if (fallbackTranslations && fallbackTranslations[actualKey]) {
-        const value = fallbackTranslations[actualKey];
-        if (typeof value === 'string') {
+      if (fallbackTranslations) {
+        const value = resolveNestedKey(fallbackTranslations as Record<string, unknown>, actualKey);
+        if (value !== null) {
           return value;
         }
       }
     }
-    
+
     return null;
-  }, [config.initialTranslations, config.fallbackLanguage, parseKey]);
+  }, [config.initialTranslations, config.fallbackLanguage, parseKey, resolveNestedKey]);
 
   // 기본 번역에서 찾기
   const findInDefaultTranslations = useCallback((key: string, targetLang: string): string | null => {
     const { namespace, key: actualKey } = parseKey(key);
     const defaultTranslations = getDefaultTranslations(targetLang, namespace);
     const fallbackTranslations = getDefaultTranslations(config.fallbackLanguage || 'en', namespace);
-    
-    return defaultTranslations[actualKey] || fallbackTranslations[actualKey] || null;
-  }, [config.fallbackLanguage, parseKey]);
+
+    return resolveNestedKey(defaultTranslations as Record<string, unknown>, actualKey)
+      || resolveNestedKey(fallbackTranslations as Record<string, unknown>, actualKey)
+      || null;
+  }, [config.fallbackLanguage, parseKey, resolveNestedKey]);
 
   // hua-api 스타일의 간단한 번역 함수 (메모이제이션)
   // translationVersion과 currentLanguage에 의존하여 번역 로드 및 언어 변경 시 리렌더링 트리거
-  const t = useCallback((key: string, language?: string) => {
+  const t = useCallback((key: string, paramsOrLang?: TranslationParams | string, language?: string) => {
     // translationVersion과 currentLanguage를 참조하여 번역 로드 및 언어 변경 시 리렌더링 트리거
-    // 의존성 배열에 포함되어 있어서 값이 변경되면 함수가 재생성됨
     void translationVersion;
     void currentLanguage;
-    
+
     if (!translator) {
       return key;
     }
-    
-    const targetLang = language || currentLanguage;
-    
-    // 1단계: translator.translate() 시도
+
+    // 두 번째 인자 타입으로 분기
+    let params: TranslationParams | undefined;
+    let lang: string | undefined;
+    if (typeof paramsOrLang === 'string') {
+      lang = paramsOrLang;
+    } else if (typeof paramsOrLang === 'object' && paramsOrLang !== null) {
+      params = paramsOrLang;
+      lang = language;
+    }
+
+    const targetLang = lang || currentLanguage;
+
+    // 1단계: translator.translate() 시도 (params가 있으면 translate에 위임)
     try {
-      const result = translator.translate(key, language);
+      const result = translator.translate(key, params || lang, params ? lang : undefined);
       if (result && result !== key && result !== '') {
         return result;
       }
     } catch (error) {
       // translator.translate() 실패 시 다음 단계로 진행
     }
-    
+
+    // interpolate 헬퍼
+    const interpolate = (text: string) => {
+      if (!params) return text;
+      return text.replace(/\{\{(\w+)\}\}/g, (match, k) => {
+        const value = params![k];
+        return value !== undefined ? String(value) : match;
+      });
+    };
+
     // 2단계: SSR 번역 데이터에서 찾기
     const ssrResult = findInSSRTranslations(key, targetLang);
     if (ssrResult) {
-      return ssrResult;
+      return interpolate(ssrResult);
     }
-    
+
     // 3단계: 기본 번역 데이터에서 찾기
     const defaultResult = findInDefaultTranslations(key, targetLang);
     if (defaultResult) {
-      return defaultResult;
+      return interpolate(defaultResult);
     }
-    
+
     // 모든 단계에서 번역을 찾지 못한 경우
     if (config.debug) {
-      return key; // 개발 환경에서는 키를 표시하여 디버깅 가능
+      return interpolate(key); // 개발 환경에서는 키를 표시하여 디버깅 가능
     }
     return ''; // 프로덕션에서는 빈 문자열 반환하여 미싱 키 노출 방지
-  }, [translator, config.debug, currentLanguage, config.fallbackLanguage, translationVersion, findInSSRTranslations, findInDefaultTranslations]) as (key: string, language?: string) => string;
-
-  // 파라미터가 있는 번역 함수 (메모이제이션)
-  const tWithParams = useCallback((key: string, params?: TranslationParams, language?: string) => {
-    if (!translator || !isInitialized) {
-      return key;
-    }
-    return translator.translateWithParams(key, params, language);
-  }, [translator, isInitialized]);
+  }, [translator, config.debug, currentLanguage, config.fallbackLanguage, translationVersion, findInSSRTranslations, findInDefaultTranslations]) as (key: string, paramsOrLang?: TranslationParams | string, language?: string) => string;
 
   // 기존 비동기 번역 함수 (하위 호환성)
   const tAsync = useCallback(async (key: string, params?: TranslationParams) => {
@@ -361,6 +393,26 @@ export function I18nProvider({
     return translator.getRawValue(key, language);
   }, [translator, isInitialized]);
 
+  // 배열 번역 값 가져오기 (타입 안전)
+  const tArray = useCallback((key: string, language?: string): string[] => {
+    void translationVersion;
+    void currentLanguage;
+    if (!translator || !isInitialized) {
+      return [];
+    }
+    return translator.tArray(key, language);
+  }, [translator, isInitialized, translationVersion, currentLanguage]);
+
+  // 복수형 번역 (ICU / Intl.PluralRules 기반)
+  const tPlural = useCallback((key: string, count: number, params?: Record<string, unknown>, language?: string): string => {
+    void translationVersion;
+    void currentLanguage;
+    if (!translator || !isInitialized) {
+      return key;
+    }
+    return translator.tPlural(key, count, params, language);
+  }, [translator, isInitialized, translationVersion, currentLanguage]);
+
   // 개발자 도구 (메모이제이션)
   const debug = useMemo(() => ({
     getCurrentLanguage: () => {
@@ -462,7 +514,8 @@ export function I18nProvider({
     currentLanguage,
     setLanguage,
     t,
-    tWithParams,
+    tPlural,
+    tArray,
     tAsync,
     tSync,
     getRawValue,
@@ -470,12 +523,9 @@ export function I18nProvider({
     error,
     supportedLanguages: config.supportedLanguages,
     debug,
-    isInitialized, // 추가: 초기화 상태 직접 노출
-    translationVersion, // 번역 로드 완료 시 리렌더링 트리거
-  }), [currentLanguage, setLanguage, t, tWithParams, tAsync, tSync, getRawValue, isLoading, error, config.supportedLanguages, debug, isInitialized, translationVersion]);
-  
-  // 의존성 배열은 이미 최적화되어 있음
-  // t, tWithParams, tAsync, tSync, getRawValue는 모두 useCallback으로 메모이제이션됨
+    isInitialized,
+    translationVersion,
+  }), [currentLanguage, setLanguage, t, tPlural, tArray, tAsync, tSync, getRawValue, isLoading, error, config.supportedLanguages, debug, isInitialized, translationVersion]);
 
   return (
     <I18nContext.Provider value={value}>
@@ -495,10 +545,11 @@ export function useI18n(): I18nContextType {
       currentLanguage: 'ko',
       setLanguage: () => {},
       t: (key: string) => key,
-      tWithParams: (key: string) => key,
+      tPlural: (key: string) => key,
       tAsync: async (key: string) => key,
       tSync: (key: string) => key,
       getRawValue: () => undefined,
+      tArray: () => [],
       isLoading: false,
       error: null,
       supportedLanguages: [
@@ -522,74 +573,4 @@ export function useI18n(): I18nContextType {
   return context;
 }
 
-/**
- * 간단한 번역 훅 (hua-api 스타일)
- */
-export function useTranslation() {
-  const { t, tWithParams, currentLanguage, setLanguage, isLoading, error, supportedLanguages } = useI18n();
-  
-  return {
-    t,
-    tWithParams,
-    currentLanguage,
-    setLanguage,
-    isLoading,
-    error,
-    supportedLanguages,
-  };
-}
-
-/**
- * 언어 변경 훅
- */
-export function useLanguageChange() {
-  const context = useContext(I18nContext);
-  
-  // Provider 밖에서 호출되면 기본값 반환
-  if (!context) {
-    return {
-      currentLanguage: 'ko',
-      changeLanguage: () => {},
-      supportedLanguages: [
-        { code: 'ko', name: 'Korean', nativeName: '한국어' },
-        { code: 'en', name: 'English', nativeName: 'English' },
-      ],
-    };
-  }
-  
-  const { currentLanguage, setLanguage, supportedLanguages } = context;
-  
-  const changeLanguage = useCallback((language: string) => {
-    const supported = supportedLanguages.find(lang => lang.code === language);
-    if (supported) {
-      setLanguage(language);
-    } else {
-      console.warn(`Language ${language} is not supported`);
-    }
-  }, [setLanguage, supportedLanguages]);
-
-  return {
-    currentLanguage,
-    changeLanguage,
-    supportedLanguages,
-  };
-}
-
-// 기존 훅들 (하위 호환성을 위해 유지)
-export function usePreloadTranslations() {
-  const context = useContext(I18nContext);
-  
-  const preload = useCallback(async (namespaces: string[]) => {
-    if (!context) return;
-    
-    // 이미 초기화되어 있으므로 별도 로딩 불필요
-    console.warn('usePreloadTranslations is deprecated. Translations are now preloaded automatically.');
-  }, [context]);
-
-  return { preload };
-}
 
-export function useAutoLoadNamespace(namespace: string) {
-  // 이미 초기화되어 있으므로 별도 로딩 불필요
-  console.warn('useAutoLoadNamespace is deprecated. All namespaces are now loaded automatically.');
-} 

package/src/hooks/useTranslation.tsx

@@ -1,17 +1,18 @@
 "use client";
 
+import { useCallback } from 'react';
 import { useI18n } from './useI18n';
 
 /**
  * 간단한 번역 훅 (원본 SDK와 호환)
- * 
+ *
  * @example
  * ```tsx
  * import { useTranslation } from '@hua-labs/i18n-core';
- * 
+ *
  * function MyComponent() {
  *   const { t, currentLanguage, setLanguage, isLoading, error } = useTranslation();
- *   
+ *
  *   return (
  *     <div>
  *       <h1>{t('welcome')}</h1>
@@ -23,11 +24,12 @@ import { useI18n } from './useI18n';
  * ```
  */
 export function useTranslation() {
-  const { t, tWithParams, currentLanguage, setLanguage, getRawValue, isLoading, error, supportedLanguages, debug, isInitialized } = useI18n();
-  
+  const { t, tPlural, tArray, currentLanguage, setLanguage, getRawValue, isLoading, error, supportedLanguages, debug, isInitialized } = useI18n();
+
   return {
     t,
-    tWithParams,
+    tPlural,
+    tArray,
     currentLanguage,
     setLanguage,
     getRawValue,
@@ -44,15 +46,15 @@ export function useTranslation() {
  */
 export function useLanguageChange() {
   const { currentLanguage, setLanguage, supportedLanguages } = useI18n();
-  
-  const changeLanguage = (language: string) => {
+
+  const changeLanguage = useCallback((language: string) => {
     const supported = supportedLanguages.find(lang => lang.code === language);
     if (supported) {
       setLanguage(language);
     } else {
-      console.warn(`Language ${language} is not supported`);
+      if (process.env.NODE_ENV !== 'production') console.warn(`Language ${language} is not supported`);
     }
-  };
+  }, [setLanguage, supportedLanguages]);
 
   return {
     currentLanguage,

package/src/index.ts

@@ -9,7 +9,7 @@ import React from 'react';
 import { I18nProvider, useI18n } from './hooks/useI18n';
 import { useTranslation, useLanguageChange } from './hooks/useTranslation';
 import { Translator, ssrTranslate, serverTranslate } from './core/translator';
-import { I18nConfig } from './types';
+import { I18nConfig, I18nContextType, TranslationParams, TypedTranslationKeys, ResolveStringKey, ResolveArrayKey, ResolvePluralKey, PluralValue, PluralCategory } from './types';
 
 // Window 객체 타입 확장
 declare global {
@@ -56,10 +56,18 @@ declare global {
   }
 }
 
-// 기본 언어 설정
+// 기본 언어 설정 (10개 언어 지원)
 const defaultLanguages = [
   { code: 'ko', name: 'Korean', nativeName: '한국어' },
   { code: 'en', name: 'English', nativeName: 'English' },
+  { code: 'en-IN', name: 'English (India)', nativeName: 'English (India)' },
+  { code: 'ja', name: 'Japanese', nativeName: '日本語' },
+  { code: 'zh', name: 'Chinese (Simplified)', nativeName: '简体中文' },
+  { code: 'zh-TW', name: 'Chinese (Traditional)', nativeName: '繁體中文' },
+  { code: 'es', name: 'Spanish', nativeName: 'Español' },
+  { code: 'ru', name: 'Russian', nativeName: 'Русский' },
+  { code: 'de', name: 'German', nativeName: 'Deutsch' },
+  { code: 'fr', name: 'French', nativeName: 'Français' },
 ];
 
 /**
@@ -108,11 +116,26 @@ export function createCoreI18n(options?: {
    * 형식: { [language]: { [namespace]: { [key]: value } } }
    */
   initialTranslations?: Record<string, Record<string, Record<string, string>>>;
+  /**
+   * 지원 언어 목록 (LanguageConfig 배열 또는 언어 코드 문자열 배열)
+   * 기본값: ['ko', 'en']
+   */
+  supportedLanguages?: Array<{ code: string; name: string; nativeName: string }> | string[];
   /**
    * 자동 언어 동기화 활성화 여부
    * 기본값: false (Zustand 어댑터 등 외부에서 직접 처리하는 경우)
    */
   autoLanguageSync?: boolean;
+  /**
+   * 서버사이드 렌더링 시 사용할 기본 URL
+   * 환경 변수보다 우선 적용됨
+   */
+  baseUrl?: string;
+  /**
+   * 로컬 개발 환경 fallback URL
+   * 기본값: 'http://localhost:3010'
+   */
+  localFallbackBaseUrl?: string;
 }) {
   const {
     defaultLanguage = 'ko',
@@ -123,9 +146,83 @@ export function createCoreI18n(options?: {
     translationLoader = 'api',
     translationApiPath = '/api/translations',
     initialTranslations,
-    autoLanguageSync = false // 기본값 false (Zustand 어댑터 등 외부에서 직접 처리)
+    supportedLanguages: providedSupportedLanguages,
+    autoLanguageSync = false, // 기본값 false (Zustand 어댑터 등 외부에서 직접 처리)
+    baseUrl,
+    localFallbackBaseUrl,
   } = options || {};
 
+  // supportedLanguages 처리: string[] 또는 LanguageConfig[] 모두 지원
+  let supportedLanguagesConfig: Array<{ code: string; name: string; nativeName: string }>;
+  if (providedSupportedLanguages) {
+    if (Array.isArray(providedSupportedLanguages) && providedSupportedLanguages.length > 0) {
+      // string[]인지 LanguageConfig[]인지 확인
+      if (typeof providedSupportedLanguages[0] === 'string') {
+        // string[]를 LanguageConfig[]로 변환
+        const languageMap: Record<string, { name: string; nativeName: string }> = {
+          ko: { name: 'Korean', nativeName: '한국어' },
+          en: { name: 'English', nativeName: 'English' },
+          ja: { name: 'Japanese', nativeName: '日本語' },
+          zh: { name: 'Chinese', nativeName: '中文' },
+          es: { name: 'Spanish', nativeName: 'Español' },
+          fr: { name: 'French', nativeName: 'Français' },
+          de: { name: 'German', nativeName: 'Deutsch' },
+          pt: { name: 'Portuguese', nativeName: 'Português' },
+          it: { name: 'Italian', nativeName: 'Italiano' },
+          ru: { name: 'Russian', nativeName: 'Русский' },
+        };
+        supportedLanguagesConfig = (providedSupportedLanguages as string[]).map(code => ({
+          code,
+          name: languageMap[code]?.name || code,
+          nativeName: languageMap[code]?.nativeName || code,
+        }));
+      } else {
+        // LanguageConfig[]인 경우 그대로 사용
+        supportedLanguagesConfig = providedSupportedLanguages as Array<{ code: string; name: string; nativeName: string }>;
+      }
+    } else {
+      supportedLanguagesConfig = defaultLanguages;
+    }
+  } else {
+    supportedLanguagesConfig = defaultLanguages;
+  }
+
+  /**
+   * 서버사이드/클라이언트사이드 URL 빌드 함수
+   * createApiTranslationLoader의 로직을 참고하여 구현
+   */
+  const buildUrl = (language: string, namespace: string): string => {
+    const safeNamespace = namespace.replace(/[^a-zA-Z0-9-_]/g, '');
+    const path = `${translationApiPath}/${language}/${safeNamespace}`;
+    
+    // 클라이언트 사이드: 상대 경로 사용
+    if (typeof window !== 'undefined') {
+      return path;
+    }
+    
+    // 서버사이드: 절대 URL 필요
+    // 1. baseUrl 옵션이 있으면 우선 사용
+    if (baseUrl) {
+      return `${baseUrl}${path}`;
+    }
+    
+    // 2. NEXT_PUBLIC_SITE_URL 환경 변수 확인
+    if (process.env.NEXT_PUBLIC_SITE_URL) {
+      return `${process.env.NEXT_PUBLIC_SITE_URL}${path}`;
+    }
+    
+    // 3. VERCEL_URL 환경 변수 확인
+    if (process.env.VERCEL_URL) {
+      const vercelUrl = process.env.VERCEL_URL.startsWith('http')
+        ? process.env.VERCEL_URL
+        : `https://${process.env.VERCEL_URL}`;
+      return `${vercelUrl}${path}`;
+    }
+    
+    // 4. 로컬 개발 환경 fallback
+    const fallbackBase = localFallbackBaseUrl ?? 'http://localhost:3010';
+    return `${fallbackBase}${path}`;
+  };
   // API route 기반 로더 (기본값, 권장)
   const apiRouteLoader = async (language: string, namespace: string) => {
     try {
@@ -211,7 +308,7 @@ export function createCoreI18n(options?: {
   const config: I18nConfig = {
     defaultLanguage,
     fallbackLanguage,
-    supportedLanguages: defaultLanguages,
+    supportedLanguages: supportedLanguagesConfig,
     namespaces,
     loadTranslations: translationLoader === 'custom' && loadTranslations 
       ? loadTranslations 
@@ -295,4 +392,4 @@ export { I18nProvider };
 export { Translator, ssrTranslate, serverTranslate };
 
 // 타입 export
-export type { I18nConfig }; 
+export type { I18nConfig, I18nContextType, TranslationParams, TypedTranslationKeys, ResolveStringKey, ResolveArrayKey, ResolvePluralKey, PluralValue, PluralCategory };

package/src/server.ts

@@ -0,0 +1,9 @@
+/**
+ * @hua-labs/i18n-core/server
+ *
+ * Server-only entry point — no React hooks, no "use client" directives.
+ * Safe to use in Next.js Server Components, API routes, and middleware.
+ */
+
+export { Translator, ssrTranslate, serverTranslate } from './core/translator';
+export type { I18nConfig } from './types';

package/src/types/index.ts

@@ -1,5 +1,36 @@
+// ---------------------------------------------------------------------------
+// Plural (ICU / Intl.PluralRules)
+// ---------------------------------------------------------------------------
+export type PluralCategory = 'zero' | 'one' | 'two' | 'few' | 'many' | 'other';
+
+export interface PluralValue {
+  zero?: string;
+  one?: string;
+  two?: string;
+  few?: string;
+  many?: string;
+  other: string; // 필수
+}
+
+const PLURAL_CATEGORIES = new Set<string>(['zero', 'one', 'two', 'few', 'many', 'other']);
+
+export function isPluralValue(value: unknown): value is PluralValue {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false;
+  const obj = value as Record<string, unknown>;
+  const keys = Object.keys(obj);
+  return (
+    keys.length > 0 &&
+    keys.every(k => PLURAL_CATEGORIES.has(k)) &&
+    Object.values(obj).every(v => typeof v === 'string') &&
+    typeof obj.other === 'string'
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Translation namespace
+// ---------------------------------------------------------------------------
 export interface TranslationNamespace {
-  [key: string]: string | TranslationNamespace;
+  [key: string]: string | string[] | PluralValue | TranslationNamespace;
 }
 
 export interface TranslationData {
@@ -120,17 +151,19 @@ export interface TranslationResult {
 
 export interface I18nContextType {
   currentLanguage: string;
-  setLanguage: (language: string) => void;
-  // hua-api 스타일의 간단한 번역 함수
-  t: (key: string, language?: string) => string;
-  // 파라미터가 있는 번역 함수
-  tWithParams: (key: string, params?: TranslationParams, language?: string) => string;
+  setLanguage: (language: string) => void | Promise<void>;
+  // 통합 번역 함수: t(key), t(key, language), t(key, params), t(key, params, language)
+  t: (key: ResolveStringKey, paramsOrLang?: TranslationParams | string, language?: string) => string;
+  // 복수형 번역 함수: tPlural(key, count), tPlural(key, count, params), tPlural(key, count, params, language)
+  tPlural: (key: ResolvePluralKey, count: number, params?: Record<string, unknown>, language?: string) => string;
   // 기존 비동기 번역 함수 (하위 호환성)
   tAsync: (key: string, params?: TranslationParams) => Promise<string>;
   // 기존 동기 번역 함수 (하위 호환성)
   tSync: (key: string, namespace?: string, params?: TranslationParams) => string;
   // 원시 값 가져오기 (배열, 객체 포함)
   getRawValue: (key: string, language?: string) => unknown;
+  // 배열 번역 값 가져오기 (타입 안전)
+  tArray: (key: ResolveArrayKey, language?: string) => string[];
   isLoading: boolean;
   error: TranslationError | null;
   supportedLanguages: LanguageConfig[];
@@ -156,7 +189,30 @@ export interface I18nContextType {
 
 export interface TranslationParams {
   [key: string]: string | number;
-} 
+}
+
+/**
+ * 타입 안전한 번역 키를 위한 augmentation point.
+ *
+ * 앱에서 declaration merging으로 좁힐 수 있음:
+ * ```ts
+ * declare module '@hua-labs/i18n-core' {
+ *   interface TypedTranslationKeys {
+ *     stringKey: TranslationStringKey;
+ *     arrayKey: TranslationArrayKey;
+ *   }
+ * }
+ * ```
+ *
+ * augmentation이 없으면 string으로 fallback (breaking 없음).
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+export interface TypedTranslationKeys {}
+
+/** augmentation 시 좁혀진 타입, 미설정 시 string */
+export type ResolveStringKey = TypedTranslationKeys extends { stringKey: infer K } ? K & string : string;
+export type ResolveArrayKey = TypedTranslationKeys extends { arrayKey: infer K } ? K & string : string;
+export type ResolvePluralKey = TypedTranslationKeys extends { pluralKey: infer K } ? K & string : string;
 
 // 타입 안전한 번역 키 시스템 (단순화된 버전)
 export type TranslationKey<T> = T extends Record<string, unknown>
@@ -170,10 +226,9 @@ export type TranslationKey<T> = T extends Record<string, unknown>
   : never;
 
 // 타입 안전한 번역 함수들
-export interface TypedI18nContextType<T extends TranslationData> extends Omit<I18nContextType, 't' | 'tWithParams' | 'tSync'> {
+export interface TypedI18nContextType<T extends TranslationData> extends Omit<I18nContextType, 't' | 'tSync'> {
   // 타입 안전한 번역 함수
-  t: <K extends TranslationKey<T>>(key: K, language?: string) => string;
-  tWithParams: <K extends TranslationKey<T>>(key: K, params?: TranslationParams, language?: string) => string;
+  t: <K extends TranslationKey<T>>(key: K, paramsOrLang?: TranslationParams | string, language?: string) => string;
   tSync: <K extends TranslationKey<T>>(key: K, namespace?: string, params?: TranslationParams) => string;
 }
 
@@ -380,7 +435,7 @@ export const defaultErrorRecoveryStrategy: ErrorRecoveryStrategy = {
   backoffMultiplier: 2,
   shouldRetry: isRecoverableError,
   onRetry: (error: TranslationError, attempt: number) => {
-    console.warn(`Retrying translation operation (attempt ${attempt}/${error.maxRetries}):`, error.message);
+    if (process.env.NODE_ENV !== 'production') console.warn(`Retrying translation operation (attempt ${attempt}/${error.maxRetries}):`, error.message);
   },
   onMaxRetriesExceeded: (error: TranslationError) => {
     console.error('Max retries exceeded for translation operation:', error.message);
@@ -430,7 +485,7 @@ export function logTranslationError(
         console.error('Translation Error:', logData);
         break;
       case 'warn':
-        console.warn('Translation Warning:', logData);
+        if (process.env.NODE_ENV !== 'production') console.warn('Translation Warning:', logData);
         break;
       case 'info':
         console.info('Translation Info:', logData);