@voerkai18n/utils/dist/index.d.ts

utils for voerkai18n

import { VoerkaI18nSettings, VoerkaI18nNamespaces } from '@voerkai18n/runtime';

declare function getIdMap(idMapFile?: string): Record<string, string> | undefined;

interface VoerkaI18nPackageJsonSettings {
    entry?: string;
}

/**
 *
 * 从当前文件的package.json读取voerkai18n配置
 *
 */
declare function getSettingsFromPackageJson(entry?: string): VoerkaI18nPackageJsonSettings;

/**
 *
 * 获取VoerkaI18n语言文件夹
 *
 */
type LanguagesDirOptions = {
    location?: string;
    autoCreate?: boolean;
    absolute?: boolean;
};
/**
 *
 * 获取语言工作文件夹
 *
 * - 读取package.json中的voerkai18n字段
 * - 如果没有，则在当前文件夹下查找
 *      - <src/languages>
 *      - <languages>
 *
 * 如果目录不存在，则自动创建
 *
 *
 * @returns
 * @param location 指定入口文件夹
 * @param created 是否创建
 */
declare function getLanguageDir(options?: LanguagesDirOptions): string;

/**
 *
 * 检查当前工程是否已经安装了voerkai18n支持
 *
 * @returns
 */
declare function isVoerkaI18nInstalled(): boolean;

/**
 * 将idMap应用到翻译结果中
 *
 */
type ApplyIdMapOptions = {
    tFuncNames?: string[];
    tComponentNames?: string[];
};
declare function applyIdMap(code: string, idMap: Record<string, string>, options?: ApplyIdMapOptions): string;

declare function getVoerkaI18nSettings(): VoerkaI18nSettings;

/**
 *
 * 获取VoerkaI18n语言文件夹
 *
 */
/**
 *
 * 获取语言文件夹
 *
 * - 读取package.json中的voerkai18n字段
 * - 如果没有，则在当前文件夹下查找
 *      - <src/languages>
 *      - <languages>
 *
 * 如果目录不存在，则自动创建
 *
 *
 * @returns
 * @param location 指定入口文件夹
 * @param created 是否创建
 */
declare function getDefaultLanguageDir(): string;

declare function getBcp47LanguageApi(osLocale?: string): any;

/**
 *
 * 输入一个namespaces配置，
 * const namespaces = {
 *   "a":"src/a",
 *   "b":["src/b","src/c"],
 *   "c":(file)=>file.startsWith("src/c")
 * }
 *
 * 如果输入的文件在namespace指定的路径内，则返回namespace的名称
 *
 *
 * @param {*} file
 * @param {*} options.namespaces  名称空间配置 {<name>:[path,...,path],<name>:path,<name>:(file)=>{}}
 */
declare function getFileNamespace(file: string, namespaces?: VoerkaI18nNamespaces): string;

/**
 * 在languages/.apikey.json中获取对应的API Key
 *
 * .apikey.json文件格式如下：
 * {
 *  "baidu": {
 *
 *   },
 *   "deepseek": {
 *     "appid": "xxxx",
 *   }
 * }
 *
 *
 * 之所有api key放在单独的文件中，是因为api key是敏感信息，不应该放在代码中
 * 所以应该在.gitignore中忽略这个文件
 *
 */
declare function getApi<T extends Record<string, any> = Record<string, any>>(name: string, defaultValue?: Partial<T>): T | undefined;

type AiRole = {
    role: string;
    content: string;
};
interface AiQuestionOptions {
    model?: string;
    temperature?: number;
    apiUrl: string;
    apiKey: string;
    roles?: AiRole[];
}
interface AiResponse {
    choices: {
        message: {
            content: string;
        };
    }[];
}
type AiError = Error & {
    response?: Response;
    data?: any;
};
/**
 *
 * 向AI提问并返回结果
 *
 * 目标AI大模型的API是OpenAI兼容的接口，可以使用OpenAI的API Key
 *
 * 如:
 *
 * ```ts
 * const answer = await aiQuestion("今天天气如何",{
 *    apiUrl:"https://api.deepseek.ai",
 *    model:"gpt-3.5-turbo",
 *    apiKey:"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
 * })
 *
 *
 * @param prompt
 * @param options
 */
declare function aiQuestion<T = string>(prompt: string, options?: AiQuestionOptions): Promise<T>;

type VoerkaI18nProjectContext = VoerkaI18nSettings & {
    rootDir: string;
    langDir: string;
    langRelDir: string;
    settingFile: string;
    settingRelFile: string;
    typescript: boolean;
    moduleType: "esm" | "cjs" | undefined;
    promptDir: string;
    getTranslateMessagesDir: (autoCreate?: boolean) => string;
    getTranslateParagraphsDir: (autoCreate?: boolean) => string;
    getMessagesDir: (autoCreate?: boolean) => string;
    getParagraphsDir: (autoCreate?: boolean) => string;
    getPrompt: (name: string) => Promise<string>;
    getApi: (name: string, defaultValue?: Record<string, any>) => Record<string, any> | undefined;
    api: Record<string, any> | undefined;
};
/**
 *
 * @param options
 * @returns
 */
declare function getProjectContext(options?: Record<string, any>): Promise<VoerkaI18nProjectContext>;

declare function getBackupFile(file: string): string;

/**
 * 将指定的文件或文件模式添加到项目的.gitignore文件中
 * 如果.gitignore文件不存在，会先创建一个空的.gitignore文件
 *
 * @param files 要添加到.gitignore中的文件或文件模式，可以是单个字符串或字符串数组
 */
declare function addToGitIgnore(files: string | string[]): void;

/**
 * 移除字符串前后的字符
 *
 * trimChars(" hello world  ") => "hello world"
 * trimChars(" \nhello world\n ") => "hello world"
 *
 * @param {*} str
 * @param {*} chars
 * @returns
 */
declare function trimChars(str: string, chars?: string[]): string;

type HasImportOptions = {
    moduleType: 'ts' | 'esm' | 'cjs' | 'auto';
};
/**
 * 判断代码中是否有导入某个模块的
 *
 *
 * hasImport(code,"t")
 *
 *
 *
 *
 * @param code
 * @param importName
 * @param moduleType
 * @returns
 */
declare function hasImport(code: string, importName: string, options?: HasImportOptions): boolean;

type AddImportOptions = HasImportOptions & {
    scriptSection?: RegExp;
};
declare function addImport(code: string, fromModule: string, importName: string, options?: AddImportOptions): string;

/**
 * 文本id必须是一个数字
 * @param {*} content
 * @returns
 */
declare function isMessageId(content: string): boolean;

/**
 * 确保指定的目录存在。如果目录不存在，将会创建该目录。
 *
 * @param spath - 目录的路径。如果路径不是绝对路径，将会相对于当前工作目录进行解析。
 */
declare function getDir(spath: string): string;

/**
 * 为多行字符串移除空格缩进，如果中tab按4个空格计算
 * @param str
 * @param indent
 */
declare function indentString(str: string, indent?: number): string;

declare function fetchJson<T = any>(urls: string | string[], defaultValue?: T): Promise<T | undefined>;

/**
 *
 * 解析源码中的t("xxxx")的内容
 *
 */

type MessageNode = {
    message: string;
    rang: {
        start: number;
        end: number;
    };
    vars?: string;
    options?: string;
    namespace?: string;
    file?: string;
};
type ExtractMessagesOptions = {
    language?: "js" | "ts" | "jsx" | "tsx" | "vue" | "react" | "svelte" | "astro" | "mdx";
    namespaces: VoerkaI18nNamespaces;
    file: string;
    tFuncNames?: string[];
    tComponentNames?: string[];
};
/**
 * 使用正则表达式提取翻译文本
 *
 * parseTranslateFunction("t('hello')") => [{text:"hello"}]
 * parseTranslateFunction("t('a') t('ns::b')") => [{text:"a"},{text:"b",namespace:"ns"}]
 *
 * @param {*} content
 * @returns
 */
declare function parseTranslateMessagesByRegex(code: string, options: ExtractMessagesOptions): MessageNode[];
declare function extractMessagesUseRegex(code: string, options: ExtractMessagesOptions): MessageNode[];
/**
 * 提取要翻译的文本信息
 *
 * @param code
 * @returns
 * [
 *   {text:"xxxx",rang,vars:[],options:{}},
 * ]
 */
declare function extractMessages(code: string, options?: ExtractMessagesOptions): MessageNode[];

type ParagraphNode = {
    id?: string;
    message: string;
    vars?: string;
    scope?: string;
    options?: string;
    rang: {
        start: number;
        end: number;
    };
    file?: string;
    [key: string]: any;
};
type ExtractParagraphsOptions = {
    language?: string;
    namespaces?: Record<string, string>;
    file?: string;
    tComponentNames?: string[];
};
/**
 * 解释段落
 */
declare function parseParagraphsByRegex(code: string, options: ExtractParagraphsOptions): ParagraphNode[];
/**
 *
 * 提取段落
 *
 * <Translate>
 *   段落内容
 * </Translate>
 *
 * @param code
 */
declare function extractParagraphs(code: string, options?: ExtractParagraphsOptions): ParagraphNode[];

declare function escapeRegex(input: string): string;

/**
 *
 * 将一个正则表达式转换为字符串形式
 *
 * 如果提供了vars参数，将会替换掉正则表达式字符串中的变量
 *
 * encodeRegExp(/a\bc/i) => "a\\bc"
 * encodeRegExp(/<__TAG__ a\bc/i,{'__TAG__':'div'}) => "<div a\\bc"
 *
 *
 * @param regex
 * @returns
 */
declare function encodeRegExp(regex: RegExp, vars?: Record<string, string>): string;

export { type AddImportOptions, type AiError, type AiQuestionOptions, type AiResponse, type AiRole, type ApplyIdMapOptions, type ExtractMessagesOptions, type ExtractParagraphsOptions, type HasImportOptions, type LanguagesDirOptions, type MessageNode, type ParagraphNode, type VoerkaI18nPackageJsonSettings, type VoerkaI18nProjectContext, addImport, addToGitIgnore, aiQuestion, applyIdMap, encodeRegExp, escapeRegex, extractMessages, extractMessagesUseRegex, extractParagraphs, fetchJson, getApi, getBackupFile, getBcp47LanguageApi, getDefaultLanguageDir, getDir, getFileNamespace, getIdMap, getLanguageDir, getProjectContext, getSettingsFromPackageJson, getVoerkaI18nSettings, hasImport, indentString, isMessageId, isVoerkaI18nInstalled, parseParagraphsByRegex, parseTranslateMessagesByRegex, trimChars };