@hua-labs/i18n-core 2.0.0 → 2.0.4

package/dist/server-4TeBq6hp.d.ts

@@ -0,0 +1,367 @@
+type PluralCategory = 'zero' | 'one' | 'two' | 'few' | 'many' | 'other';
+interface PluralValue {
+    zero?: string;
+    one?: string;
+    two?: string;
+    few?: string;
+    many?: string;
+    other: string;
+}
+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;
+}
+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;
+    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[];
+    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;
+        };
+    };
+}
+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(key: string, language?: string): unknown;
+    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(key: string, language?: string): unknown;
+    /**
+     * 배열 번역 값 가져오기 (타입 안전)
+     */
+    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 PluralValue as e, Translator as f, type TypedTranslationKeys as g, ssrTranslate as h, serverTranslate as s };

package/dist/server.d.mts

@@ -0,0 +1 @@
+export { I as I18nConfig, f as Translator, s as serverTranslate, h as ssrTranslate } from './server-4TeBq6hp.mjs';

package/dist/server.d.ts

@@ -0,0 +1 @@
+export { I as I18nConfig, f as Translator, s as serverTranslate, h as ssrTranslate } from './server-4TeBq6hp.js';