@gulibs/vgrove-ui/dist/client/i18n.d.ts

VGrove UI component library built with HeroUI and React

import { type I18nLoaderConfig, type I18nResourceLoader } from './i18n-loader';
import type { Localized, LocalizedOrNode, LocalizedType } from './types';
/**
 * 国际化上下文类型 - 优化版
 */
export interface I18nContextType<Keys extends string = string> {
    /** 当前语言 */
    locale: string;
    /** 切换语言 */
    setLocale: (locale: string) => Promise<void>;
    /** 翻译函数 */
    t: (key: LocalizedType<Keys>, params?: Record<string, unknown>) => string;
    /** 带默认值的翻译函数 */
    td: (key: LocalizedType<Keys>, defaultValue: string, params?: Record<string, unknown>) => string;
    /** 是否准备就绪 */
    isReady: boolean;
    /** 可用的语言列表 */
    availableLocales: string[];
    /** 所有可用的翻译键 */
    availableKeys: string[];
    /** 检查键是否存在 */
    hasKey: (key: string) => boolean;
    /** 获取命名空间资源 */
    getNamespaceResources: (namespace: string) => Record<string, unknown> | undefined;
    /** 是否使用虚拟模块 */
    isUsingVirtualModule: boolean;
}
export interface I18nInterpolation {
    /** 插值前缀，默认为 '{' */
    prefix?: string;
    /** 插值后缀，默认为 '}' */
    suffix?: string;
    /** 转义函数 */
    escape?: (value: unknown) => string;
}
export type I18nPersistenceStorage = 'localStorage' | 'sessionStorage';
export interface I18nPersistence {
    /** 是否启用持久化 */
    enabled?: boolean;
    /** 存储键名 */
    key?: string;
    /** 存储类型 */
    storage?: I18nPersistenceStorage;
}
/**
 * 增强的国际化客户端配置 - 对标 vite-plugin-i18n
 */
export interface I18nClientConfig extends I18nLoaderConfig {
    /** 默认语言 */
    defaultLocale?: string;
    /** 支持的语言列表 */
    supportedLocales?: string[];
    /** 静态资源（用于服务端渲染或初始化） */
    resources?: Record<string, Record<string, unknown>>;
    /** 命名空间配置 */
    namespace?: string;
    /** 资源键前缀 */
    keyPrefix?: string;
    /** 回退到默认语言 */
    fallbackToDefault?: boolean;
    /** 插值选项 */
    interpolation?: I18nInterpolation;
    /** 是否自动检测浏览器语言 */
    detectBrowserLanguage?: boolean;
    /** 持久化设置 */
    persistence?: I18nPersistence;
}
/**
 * 内部使用的完整配置类型
 */
type RequiredI18nClientConfig = I18nClientConfig & {
    defaultLocale: string;
};
/**
 * 增强的国际化客户端类
 */
export declare class I18nClient {
    config: RequiredI18nClientConfig;
    private loader;
    constructor(config: I18nClientConfig);
    /** 获取资源加载器 */
    getLoader(): I18nResourceLoader;
    /** 获取资源加载函数 */
    getLoadResources(): (locale: string) => Promise<Record<string, unknown>>;
    /** 预加载资源 */
    preloadResources(locales?: string[]): Promise<Record<string, Record<string, unknown>>>;
    /** 清除缓存 */
    clearCache(locale?: string): void;
    /** 获取所有可用的键 */
    getAvailableKeys(): string[];
    /** 检查键是否存在 */
    hasKey(key: string): boolean;
    /** 获取命名空间资源 */
    getNamespaceResources(locale: string, namespace: string): Record<string, unknown> | undefined;
    /** 检查是否使用虚拟模块 */
    isUsingVirtualModule(): boolean;
}
/**
 * 创建国际化客户端 - 支持从虚拟模块自动读取配置或直接传入配置
 */
export declare function createI18nClient(config?: Partial<I18nClientConfig>): I18nClient;
/**
 * 国际化提供者属性
 */
export interface I18nProviderProps {
    children: React.ReactNode;
    /** 客户端配置或客户端实例 */
    client?: I18nClient | I18nClientConfig;
    /** 传统配置属性（用于向后兼容） */
    defaultLocale?: string;
    locales?: string[];
    loadResources?: (locale: string) => Promise<Record<string, unknown>>;
    resources?: Record<string, Record<string, unknown>>;
}
/**
 * 国际化提供者组件 - 优化版
 */
export declare function I18nProvider({ children, client, defaultLocale, // 修复：与配置保持一致
locales, // 修复：支持中英文
loadResources, resources }: I18nProviderProps): import("react/jsx-runtime").JSX.Element;
/**
 * 使用国际化上下文的 Hook
 */
export declare function useI18n<Keys extends string = string>(): I18nContextType<Keys>;
/**
 * 用于翻译本地化对象的 Hook - 优化版
 */
export declare function useTranslateLocalized<Keys extends string = string>(): (localized: LocalizedOrNode<Keys> | undefined) => React.ReactNode;
/**
 * 转换本地化对象为字符串 - 优化版
 */
export declare function translateLocalized<Keys extends string = string>(localized: LocalizedOrNode<Keys> | undefined, translate: (key: string) => string): string | React.ReactNode;
/**
 * 创建本地化对象
 */
export declare function localize<Keys extends string = string>(key: LocalizedType<Keys>): Localized<Keys>;
/**
 * 使用国际化键验证 Hook
 */
export declare function useI18nKeyValidator<Keys extends string = string>(): {
    /** 检查键是否存在 */
    hasKey: (key: string) => boolean;
    /** 获取所有可用键 */
    getAvailableKeys: () => string[];
    /** 验证键并返回建议 */
    validateKey: (key: string) => {
        valid: boolean;
        suggestions: string[];
    };
};
/**
 * 使用命名空间 Hook
 */
export declare function useI18nNamespace<Keys extends string = string>(namespace: string): {
    /** 命名空间内的翻译函数 */
    t: (key: string, params?: Record<string, unknown>) => string;
    /** 获取命名空间资源 */
    resources: Record<string, unknown> | undefined;
    /** 当前语言 */
    locale: string;
    /** 检查命名空间是否存在 */
    exists: boolean;
};
/**
 * 使用复数形式 Hook
 */
export declare function usePlural<Keys extends string = string>(): (key: string, count: number, params?: Record<string, unknown>) => string;
/**
 * 导出重构后的主要接口
 */
export { createI18nLoader, ViteI18nLoader, type I18nLoaderConfig, type I18nResourceLoader } from './i18n-loader';
/**
 * 解析包含组件标记的文本
 * 支持 {Component}内容{/Component} 格式
 */
export declare function parseComponentText(text: string): React.ReactNode;
/**
 * 使用 I18nMessage 的调试 Hook
 */
export declare function useI18nMessageDebug<Keys extends string = string>(): {
    /** 当前状态 */
    isReady: boolean;
    locale: string;
    /** 调试信息 */
    debugInfo: {
        totalKeys: number;
        isUsingVirtualModule: boolean;
        hasKeys: boolean;
    };
    /** 验证翻译键 */
    validateKey: (key: string) => {
        exists: boolean;
        ready: boolean;
        locale: string;
    };
};
/**
 * I18nMessage 性能优化 Hook
 */
export declare function useI18nMessageMemo<Keys extends string = string>(id: LocalizedType<Keys>, params?: Record<string, any>, defaultValue?: string): string;
//# sourceMappingURL=i18n.d.ts.map