@hua-labs/i18n-core 2.1.0 → 2.2.1

package/dist/server-CQztOmd-.d.ts

@@ -0,0 +1,404 @@
+type PluralCategory = "zero" | "one" | "two" | "few" | "many" | "other";
+interface PluralValue {
+    zero?: string;
+    one?: string;
+    two?: string;
+    few?: string;
+    many?: string;
+    other: string;
+}
+/**
+ * 플랫폼별 i18n 어댑터 인터페이스.
+ *
+ * Web(기본), React Native, Flutter 브릿지 등 환경에 맞는 구현체를 주입.
+ * I18nConfig.platformAdapter로 전달하면 useI18n이 자동으로 사용한다.
+ */
+interface I18nPlatformAdapter {
+    /** 디바이스/브라우저 언어 코드 (e.g. 'ko', 'en'). 감지 불가 시 undefined */
+    getDeviceLanguage(): string | undefined;
+    /** 시스템 언어 변경 이벤트 구독. 해제 함수 반환 */
+    onLanguageChange(cb: (lang: string) => void): () => void;
+}
+/**
+ * Web 기본 어댑터.
+ * navigator.language + CustomEvent 기반. SSR에서는 안전하게 no-op.
+ */
+declare const webPlatformAdapter: I18nPlatformAdapter;
+/**
+ * Headless 어댑터 (SSR / 테스트 / Flutter 브릿지용).
+ * 언어 감지·이벤트 없이 config.defaultLanguage만 사용.
+ */
+declare const headlessPlatformAdapter: I18nPlatformAdapter;
+interface TranslationNamespace {
+    [key: string]: string | string[] | PluralValue | TranslationNamespace;
+}
+interface LanguageConfig {
+    code: string;
+    name: string;
+    nativeName: string;
+    tone?: "emotional" | "encouraging" | "calm" | "gentle" | "formal" | "technical" | "informal";
+    formality?: "informal" | "casual" | "formal" | "polite";
+}
+interface I18nConfig {
+    defaultLanguage: string;
+    fallbackLanguage?: string;
+    supportedLanguages: LanguageConfig[];
+    namespaces?: string[];
+    loadTranslations: (language: string, namespace: string) => Promise<TranslationNamespace>;
+    initialTranslations?: Record<string, Record<string, TranslationNamespace>>;
+    debug?: boolean;
+    missingKeyHandler?: (key: string, language: string, namespace: string) => string;
+    errorHandler?: (error: Error, language: string, namespace: string) => void;
+    cacheOptions?: {
+        maxSize?: number;
+        ttl?: number;
+    };
+    performanceOptions?: {
+        preloadAll?: boolean;
+        lazyLoad?: boolean;
+    };
+    errorHandling?: {
+        recoveryStrategy?: ErrorRecoveryStrategy;
+        logging?: ErrorLoggingConfig;
+        userFriendlyMessages?: boolean;
+        suppressErrors?: boolean;
+    };
+    autoLanguageSync?: boolean;
+    platformAdapter?: I18nPlatformAdapter;
+}
+interface TranslationError extends Error {
+    code: "MISSING_KEY" | "LOAD_FAILED" | "INVALID_KEY" | "NETWORK_ERROR" | "INITIALIZATION_ERROR" | "VALIDATION_ERROR" | "CACHE_ERROR" | "FALLBACK_LOAD_FAILED" | "INITIALIZATION_FAILED" | "RETRY_FAILED";
+    language?: string;
+    namespace?: string;
+    key?: string;
+    originalError?: Error;
+    retryCount?: number;
+    maxRetries?: number;
+    timestamp: number;
+    context?: Record<string, unknown>;
+}
+interface ErrorRecoveryStrategy {
+    maxRetries: number;
+    retryDelay: number;
+    backoffMultiplier: number;
+    shouldRetry: (error: TranslationError) => boolean;
+    onRetry: (error: TranslationError, attempt: number) => void;
+    onMaxRetriesExceeded: (error: TranslationError) => void;
+}
+interface ErrorLoggingConfig {
+    enabled: boolean;
+    level: "error" | "warn" | "info" | "debug";
+    includeStack: boolean;
+    includeContext: boolean;
+    customLogger?: (error: TranslationError) => void;
+}
+interface I18nContextType {
+    currentLanguage: string;
+    setLanguage: (language: string) => void | Promise<void>;
+    t: (key: ResolveStringKey, paramsOrLang?: TranslationParams | string, language?: string) => string;
+    tPlural: (key: ResolvePluralKey, count: number, params?: Record<string, unknown>, language?: string) => string;
+    /** @deprecated Use `t()` instead. Will be removed in a future major version. */
+    tAsync: (key: string, params?: TranslationParams) => Promise<string>;
+    /** @deprecated Use `t()` instead. Will be removed in a future major version. */
+    tSync: (key: string, namespace?: string, params?: TranslationParams) => string;
+    getRawValue: <T = unknown>(key: string, language?: string) => T | undefined;
+    tArray: (key: ResolveArrayKey, language?: string) => string[];
+    isLoading: boolean;
+    error: TranslationError | null;
+    supportedLanguages: LanguageConfig[];
+    isInitialized: boolean;
+    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;
+        };
+    };
+}
+/**
+ * Parameters for the `t()` function.
+ *
+ * `defaultValue` is a reserved key: when translation lookup fails entirely,
+ * the string provided here is returned instead of empty string (production)
+ * or the raw key (debug). Interpolation variables still work:
+ *
+ * ```ts
+ * t('missing:key', { defaultValue: 'Hello {{name}}', name: 'World' })
+ * // → 'Hello World'
+ * ```
+ */
+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 없음).
+ */
+interface TypedTranslationKeys {
+}
+/** augmentation 시 좁혀진 타입, 미설정 시 string */
+type ResolveStringKey = TypedTranslationKeys extends {
+    stringKey: infer K;
+} ? K & string : string;
+type ResolveArrayKey = TypedTranslationKeys extends {
+    arrayKey: infer K;
+} ? K & string : string;
+type ResolvePluralKey = TypedTranslationKeys extends {
+    pluralKey: infer K;
+} ? K & string : string;
+
+interface TranslatorInterface {
+    translate(key: string, paramsOrLang?: Record<string, unknown> | string, language?: string): string;
+    tPlural(key: string, count: number, params?: Record<string, unknown>, language?: string): string;
+    setLanguage(lang: string): void;
+    getCurrentLanguage(): string;
+    initialize(): Promise<void>;
+    isReady(): boolean;
+    debug(): unknown;
+    getRawValue<T = unknown>(key: string, language?: string): T | undefined;
+    tArray(key: string, language?: string): string[];
+}
+declare class Translator implements TranslatorInterface {
+    private cache;
+    private pluralRulesCache;
+    private loadedNamespaces;
+    private loadingPromises;
+    private allTranslations;
+    private isInitialized;
+    private initializationError;
+    private config;
+    private currentLang;
+    private cacheStats;
+    private onTranslationLoadedCallbacks;
+    private onLanguageChangedCallbacks;
+    private notifyTimer;
+    private recentlyNotified;
+    /**
+     * 번역 로드 완료 콜백 등록
+     */
+    onTranslationLoaded(callback: () => void): () => void;
+    /**
+     * 언어 변경 콜백 등록
+     */
+    onLanguageChanged(callback: (language: string) => void): () => void;
+    /**
+     * 언어 변경 이벤트 발생
+     */
+    private notifyLanguageChanged;
+    /**
+     * 번역 로드 완료 이벤트 발생 (디바운싱 적용)
+     */
+    private notifyTranslationLoaded;
+    constructor(config: I18nConfig);
+    /**
+     * 모든 번역 데이터를 미리 로드 (hua-api 스타일)
+     */
+    initialize(): Promise<void>;
+    /**
+     * 초기화되지 않은 상태에서 번역 시도
+     */
+    private translateBeforeInitialized;
+    /**
+     * 다른 로드된 언어에서 번역 찾기 (언어 변경 중 깜빡임 방지)
+     */
+    private findInOtherLanguages;
+    /**
+     * 폴백 언어에서 번역 찾기
+     */
+    private findInFallbackLanguage;
+    /**
+     * 번역 키를 번역된 텍스트로 변환
+     */
+    translate(key: string, paramsOrLang?: Record<string, unknown> | string, language?: string): string;
+    /**
+     * 네임스페이스에서 키 찾기
+     */
+    private findInNamespace;
+    /**
+     * 중첩된 객체에서 값을 가져오기
+     * 배열도 지원: 최종 값이 string[]이면 그대로 반환
+     */
+    private getNestedValue;
+    /**
+     * 문자열 값인지 확인하는 타입 가드
+     */
+    private isStringValue;
+    /**
+     * string[] 배열인지 확인하는 타입 가드
+     * 배열 값이 t()에 전달되면 랜덤으로 하나를 선택하여 반환
+     */
+    private isStringArray;
+    /**
+     * 원시 값 가져오기 (배열, 객체 포함)
+     */
+    getRawValue<T = unknown>(key: string, language?: string): T | undefined;
+    /**
+     * 배열 번역 값 가져오기 (타입 안전)
+     */
+    tArray(key: string, language?: string): string[];
+    /**
+     * Intl.PluralRules 인스턴스 (언어별 캐시)
+     */
+    private getPluralRules;
+    /**
+     * 복수형 번역 (ICU / Intl.PluralRules 기반)
+     *
+     * JSON: { "other": "총 {count}개" }  (ko)
+     *       { "one": "{count} item", "other": "{count} items" }  (en)
+     *
+     * tPlural('common:total_count', 1) → en: "1 item" / ko: "총 1개"
+     * tPlural('common:total_count', 5) → en: "5 items" / ko: "총 5개"
+     */
+    tPlural(key: string, count: number, params?: Record<string, unknown>, language?: string): string;
+    /**
+     * 매개변수 보간
+     *
+     * 지원 형식:
+     * - {key} - 단일 중괄호 (일반적인 i18n 형식)
+     * - {{key}} - 이중 중괄호 (하위 호환성)
+     */
+    private interpolate;
+    /**
+     * 언어 설정
+     */
+    setLanguage(language: string): void;
+    /**
+     * 언어 데이터 로드
+     */
+    private loadLanguageData;
+    /**
+     * 현재 언어 가져오기
+     */
+    getCurrentLanguage(): string;
+    /**
+     * 지원되는 언어 목록 가져오기
+     */
+    getSupportedLanguages(): string[];
+    /**
+     * 초기화 완료 여부 확인
+     */
+    isReady(): boolean;
+    /**
+     * 초기화 오류 가져오기
+     */
+    getInitializationError(): TranslationError | null;
+    /**
+     * 캐시 클리어
+     */
+    clearCache(): void;
+    /**
+     * 캐시 엔트리 설정
+     */
+    private setCacheEntry;
+    /**
+     * 캐시 엔트리 가져오기
+     */
+    private getCacheEntry;
+    /**
+     * 번역 오류 생성
+     */
+    private createTranslationError;
+    /**
+     * 오류 로깅
+     */
+    private logError;
+    /**
+     * 재시도 작업
+     */
+    private retryOperation;
+    /**
+     * 안전한 번역 로드
+     */
+    private safeLoadTranslations;
+    /**
+     * 디버그 정보
+     */
+    debug(): {
+        isInitialized: boolean;
+        currentLanguage: string;
+        loadedNamespaces: string[];
+        cacheStats: {
+            hits: number;
+            misses: number;
+        };
+        cacheSize: number;
+        allTranslations: Record<string, Record<string, TranslationNamespace>>;
+        initializationError: TranslationError | null;
+        config: I18nConfig;
+    };
+    /**
+     * SSR에서 하이드레이션
+     */
+    hydrateFromSSR(translations: Record<string, Record<string, TranslationNamespace>>): void;
+    /**
+     * 비동기 번역 (고급 기능)
+     */
+    translateAsync(key: string, params?: Record<string, unknown>): Promise<string>;
+    /**
+     * 동기 번역 (고급 기능)
+     */
+    translateSync(key: string, params?: Record<string, unknown>): string;
+    /**
+     * 키 파싱 (네임스페이스:키 형식)
+     *
+     * - 콜론(:)만 네임스페이스 구분자로 사용
+     * - 점(.)은 키 이름의 일부로 취급 (중첩 객체 접근용)
+     *
+     * @example
+     * parseKey("home:hero.badge") → { namespace: "home", key: "hero.badge" }
+     * parseKey("hero.badge") → { namespace: "common", key: "hero.badge" }
+     * parseKey("save") → { namespace: "common", key: "save" }
+     */
+    private parseKey;
+    /**
+     * 번역 데이터 로드 (고급 기능)
+     */
+    private loadTranslationData;
+    /**
+     * 실제 번역 데이터 로드
+     */
+    private _loadTranslationData;
+}
+declare function ssrTranslate({ translations, key, language, fallbackLanguage, missingKeyHandler, }: {
+    translations: Record<string, Record<string, TranslationNamespace>>;
+    key: string;
+    language?: string;
+    fallbackLanguage?: string;
+    missingKeyHandler?: (key: string) => string;
+}): string;
+declare function serverTranslate({ translations, key, language, fallbackLanguage, missingKeyHandler, options, }: {
+    translations: Record<string, unknown>;
+    key: string;
+    language?: string;
+    fallbackLanguage?: string;
+    missingKeyHandler?: (key: string) => string;
+    options?: {
+        cache?: Map<string, string>;
+        metrics?: {
+            hits: number;
+            misses: number;
+        };
+        debug?: boolean;
+    };
+}): string;
+
+export { type I18nConfig as I, type LanguageConfig as L, type PluralCategory as P, type ResolveStringKey as R, type TranslationParams as T, type I18nContextType as a, type ResolvePluralKey as b, type ResolveArrayKey as c, type TranslationError as d, type I18nPlatformAdapter as e, type PluralValue as f, Translator as g, type TypedTranslationKeys as h, headlessPlatformAdapter as i, ssrTranslate as j, serverTranslate as s, webPlatformAdapter as w };