@hua-labs/i18n-core 2.1.0 → 2.2.0

package/dist/index.d.ts

@@ -0,0 +1,249 @@
+import React$1 from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { I as I18nConfig, a as I18nContextType, L as LanguageConfig, R as ResolveStringKey, T as TranslationParams, b as ResolvePluralKey, c as ResolveArrayKey, d as TranslationError } from './server-DgpyR0RE.js';
+export { e as I18nPlatformAdapter, P as PluralCategory, f as PluralValue, g as Translator, h as TypedTranslationKeys, i as headlessPlatformAdapter, s as serverTranslate, j as ssrTranslate, w as webPlatformAdapter } from './server-DgpyR0RE.js';
+
+/**
+ * I18n Provider 컴포넌트
+ */
+declare function I18nProvider({ config, children }: {
+    config: I18nConfig & {
+        autoLanguageSync?: boolean;
+    };
+    children: React.ReactNode;
+}): react_jsx_runtime.JSX.Element;
+/**
+ * I18n 훅
+ */
+declare function useI18n(): I18nContextType;
+
+/**
+ * 간단한 번역 훅 (원본 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>
+ *       <p>Current language: {currentLanguage}</p>
+ *       <button onClick={() => setLanguage('en')}>Switch to English</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useTranslation(): {
+    t: (key: ResolveStringKey, paramsOrLang?: TranslationParams | string, language?: string) => string;
+    tPlural: (key: ResolvePluralKey, count: number, params?: Record<string, unknown>, language?: string) => string;
+    tArray: (key: ResolveArrayKey, language?: string) => string[];
+    currentLanguage: string;
+    setLanguage: (language: string) => void | Promise<void>;
+    getRawValue: <T = unknown>(key: string, language?: string) => T | undefined;
+    isLoading: boolean;
+    error: TranslationError | null;
+    supportedLanguages: LanguageConfig[];
+    debug: {
+        getCurrentLanguage: () => string;
+        getSupportedLanguages: () => string[];
+        getLoadedNamespaces: () => string[];
+        getAllTranslations: () => Record<string, Record<string, unknown>>;
+        isReady: () => boolean;
+        getInitializationError: () => TranslationError | null;
+        clearCache: () => void;
+        reloadTranslations: () => Promise<void>;
+        getCacheStats: () => {
+            size: number;
+            hits: number;
+            misses: number;
+        };
+    };
+    isInitialized: boolean;
+};
+/**
+ * 언어 변경 전용 훅
+ */
+declare function useLanguageChange(): {
+    currentLanguage: string;
+    changeLanguage: (language: string) => void;
+    supportedLanguages: LanguageConfig[];
+};
+
+/**
+ * @hua-labs/i18n-core - 핵심 기능 전용 엔트리포인트
+ *
+ * 이 모듈은 기본적인 번역 기능만 필요한 경우 사용합니다.
+ * 플러그인, 고급 기능, 디버깅 도구 없이 순수한 번역 기능만 제공합니다.
+ */
+
+declare global {
+    interface Window {
+        __I18N_DEBUG_MODE__?: boolean;
+        __I18N_DEBUG_MISSING_KEYS__?: Record<string, string[]>;
+        __I18N_DEBUG_ERRORS__?: Array<{
+            timestamp: string;
+            language: string;
+            namespace: string;
+            error: string;
+            stack?: string;
+        }>;
+        __I18N_PERFORMANCE_DATA__?: Record<string, number[]>;
+        __I18N_PERFORMANCE_ALERTS__?: Array<{
+            id: string;
+            type: 'warning' | 'error' | 'info';
+            severity: 'low' | 'medium' | 'high' | 'critical';
+            message: string;
+            metric: string;
+            value: number;
+            threshold: number;
+            timestamp: number;
+            resolved: boolean;
+        }>;
+        __I18N_ANALYTICS_DATA__?: {
+            missingKeys?: Set<string> | string[];
+            performance?: {
+                totalTime: number;
+                averageTime: number;
+                calls: number;
+            };
+            usage?: {
+                keys?: Map<string, number> | Record<string, number>;
+                languages?: Map<string, number> | Record<string, number>;
+                namespaces?: Map<string, number> | Record<string, number>;
+            };
+            errors?: Array<{
+                timestamp: number;
+                error: string;
+                context: string;
+            }>;
+        };
+    }
+}
+/**
+ * 핵심 기능용 설정 함수
+ *
+ * @example
+ * ```tsx
+ * // app/layout.tsx (Next.js App Router)
+ * import { createCoreI18n } from '@hua-labs/i18n-core';
+ *
+ * export default function RootLayout({ children }) {
+ *   return (
+ *     <html>
+ *       <body>
+ *         {createCoreI18n({
+ *           defaultLanguage: 'ko',
+ *           fallbackLanguage: 'en',
+ *           namespaces: ['common', 'auth']
+ *         })({ children })}
+ *       </body>
+ *     </html>
+ *   );
+ * }
+ * ```
+ */
+declare function createCoreI18n(options?: {
+    defaultLanguage?: string;
+    fallbackLanguage?: string;
+    namespaces?: string[];
+    debug?: boolean;
+    loadTranslations?: (language: string, namespace: string) => Promise<Record<string, string>>;
+    /**
+     * 번역 파일 로딩 방식 설정
+     * - 'api': API route를 통해 동적 로드 (기본값, 권장)
+     * - 'static': 정적 파일 경로에서 로드
+     * - 'custom': loadTranslations 함수 사용
+     */
+    translationLoader?: 'api' | 'static' | 'custom';
+    /**
+     * API route 경로 (translationLoader가 'api'일 때 사용)
+     * 기본값: '/api/translations'
+     */
+    translationApiPath?: string;
+    /**
+     * SSR에서 전달된 초기 번역 데이터 (네트워크 요청 없이 사용)
+     * 형식: { [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;
+}): ({ children }: {
+    children: React$1.ReactNode;
+}) => React$1.FunctionComponentElement<{
+    config: I18nConfig & {
+        autoLanguageSync?: boolean;
+    };
+    children: React$1.ReactNode;
+}>;
+/**
+ * 가장 기본적인 Provider (최소한의 설정)
+ */
+declare function CoreProvider({ children }: {
+    children: React$1.ReactNode;
+}): React$1.FunctionComponentElement<{
+    config: I18nConfig & {
+        autoLanguageSync?: boolean;
+    };
+    children: React$1.ReactNode;
+}>;
+/**
+ * 언어별 Provider (언어만 지정)
+ */
+declare function createLanguageProvider(language: string): ({ children }: {
+    children: React$1.ReactNode;
+}) => React$1.FunctionComponentElement<{
+    config: I18nConfig & {
+        autoLanguageSync?: boolean;
+    };
+    children: React$1.ReactNode;
+}>;
+/**
+ * 네임스페이스별 Provider (네임스페이스만 지정)
+ */
+declare function createNamespaceProvider(namespaces: string[]): ({ children }: {
+    children: React$1.ReactNode;
+}) => React$1.FunctionComponentElement<{
+    config: I18nConfig & {
+        autoLanguageSync?: boolean;
+    };
+    children: React$1.ReactNode;
+}>;
+/**
+ * 커스텀 로더 Provider (사용자 정의 번역 로더 사용)
+ */
+declare function createCustomLoaderProvider(loadTranslations: (language: string, namespace: string) => Promise<Record<string, string>>): ({ children }: {
+    children: React$1.ReactNode;
+}) => React$1.FunctionComponentElement<{
+    config: I18nConfig & {
+        autoLanguageSync?: boolean;
+    };
+    children: React$1.ReactNode;
+}>;
+
+export { CoreProvider, I18nConfig, I18nContextType, I18nProvider, ResolveArrayKey, ResolvePluralKey, ResolveStringKey, TranslationParams, createCoreI18n, createCustomLoaderProvider, createLanguageProvider, createNamespaceProvider, useI18n, useLanguageChange, useTranslation };

package/dist/index.mjs

@@ -1,5 +1,5 @@
-import { validateI18nConfig, Translator } from './chunk-EZL5TNH5.mjs';
-export { Translator, serverTranslate, ssrTranslate } from './chunk-EZL5TNH5.mjs';
+import { validateI18nConfig, webPlatformAdapter, Translator } from './chunk-7ZYOSEMW.mjs';
+export { Translator, headlessPlatformAdapter, serverTranslate, ssrTranslate, webPlatformAdapter } from './chunk-7ZYOSEMW.mjs';
 import React, { createContext, useState, useEffect, useMemo, useCallback, useContext } from 'react';
 import { jsx } from 'react/jsx-runtime';
 
@@ -208,11 +208,12 @@ function resolveInitialLanguage(config) {
   if (config.defaultLanguage) {
     return config.defaultLanguage;
   }
-  if (typeof window !== "undefined" && navigator?.language) {
-    const browserLang = navigator.language.slice(0, 2).toLowerCase();
+  const adapter = config.platformAdapter ?? webPlatformAdapter;
+  const deviceLang = adapter.getDeviceLanguage();
+  if (deviceLang) {
     const supportedCodes = config.supportedLanguages?.map((l) => l.code) ?? [];
-    if (supportedCodes.includes(browserLang)) {
-      return browserLang;
+    if (supportedCodes.includes(deviceLang)) {
+      return deviceLang;
     }
   }
   return config.supportedLanguages?.[0]?.code ?? "ko";
@@ -310,25 +311,19 @@ function I18nProvider({
     return unsubscribe;
   }, [translator, isInitialized, currentLanguage, config.debug]);
   useEffect(() => {
-    if (!config.autoLanguageSync || typeof window === "undefined") {
+    if (!config.autoLanguageSync) {
       return;
     }
-    const handleLanguageChange = (event) => {
-      const newLanguage = event.detail;
-      if (typeof newLanguage === "string" && newLanguage !== currentLanguage) {
+    const adapter = config.platformAdapter ?? webPlatformAdapter;
+    return adapter.onLanguageChange((newLanguage) => {
+      if (newLanguage !== currentLanguage) {
         if (config.debug) {
           console.log("\u{1F310} Auto language sync:", newLanguage);
         }
         setLanguage(newLanguage);
       }
-    };
-    window.addEventListener("huaI18nLanguageChange", handleLanguageChange);
-    window.addEventListener("i18nLanguageChanged", handleLanguageChange);
-    return () => {
-      window.removeEventListener("huaI18nLanguageChange", handleLanguageChange);
-      window.removeEventListener("i18nLanguageChanged", handleLanguageChange);
-    };
-  }, [config.autoLanguageSync, currentLanguage]);
+    });
+  }, [config.autoLanguageSync, config.platformAdapter, currentLanguage]);
   const setLanguage = useCallback(async (language) => {
     if (!translator) {
       return;