Hi.Ltd.LocalResource 2026.6.10.1602

Hi.Ltd.LocalResource

Language 类（多语言翻译与本地化）

类说明

Language 类（位于 Hi.Ltd.LocalResource 命名空间）是一个功能强大的多语言翻译与本地化管理类，支持：

• 多语言翻译（支持多种翻译引擎：百度、谷歌、微软、腾讯、阿里、华为、火山、Argos等）
• 本地化资源管理（基于 SQLite 数据库）
• RESX 文件本地化处理
• 文档翻译（支持 Word、PDF、Excel 等格式）
• 智能缓存机制
• API 密钥验证

属性

ApiKey

public static string ApiKey { get; set; }

功能说明: 获取或设置 API 接入公钥。

使用示例:

Language.ApiKey = "your-api-key";

---

SecretKey

public static string SecretKey { get; set; }

功能说明: 获取或设置密钥。

使用示例:

Language.SecretKey = "your-secret-key";

---

AllowUpdateExistingTranslation

public static bool AllowUpdateExistingTranslation { get; set; }

功能说明: 是否允许更新已有翻译（默认 false，严格模式，不覆盖已有内容）。
设置为 true 时，如果新翻译与缓存中的翻译不同，会更新数据库中的翻译。
适用于：翻译不准确需要修正、更换翻译引擎后效果更好等情况。

使用示例:

Language.AllowUpdateExistingTranslation = true;

---

MultipleLanguages

public static IReadOnlyList<string> MultipleLanguages { get; }

功能说明: 获取已设置的多语言列表（只读）。

使用示例:

var languages = Language.MultipleLanguages;
foreach (var lang in languages)
{
    Console.WriteLine(lang);
}

---

EngineType

public static TranslateEngineType EngineType { get; set; }

功能说明: 获取或设置翻译引擎类型（默认 Volcengine）。
设置引擎类型会自动重新创建翻译引擎实例，并清除文档翻译接口缓存。

使用示例:

// 获取当前引擎类型
TranslateEngineType currentEngine = Language.EngineType;

// 切换翻译引擎
Language.EngineType = TranslateEngineType.Baidu;

---

初始化方法

Initialize

public static Result Initialize(TranslateEngineType engineType, string apiKey, string secretKey, params string[] multiLanguage)

功能说明: 初始化翻译源和多语言列表。

参数:

• engineType: 翻译引擎类型
• apiKey: API 密钥
• secretKey: 密钥
• multiLanguage: 多语言列表（如 "en-US", "ja-JP", "ko-KR"）

返回值: Result 类型，表示操作结果

使用示例:

var result = Language.Initialize(
    TranslateEngineType.Baidu, 
    "your-api-key", 
    "your-secret-key", 
    "en-US", "ja-JP", "ko-KR"
);
if (result.Successed)
{
    Console.WriteLine("初始化成功");
}

---

InitializeTranslateSource

public static Result InitializeTranslateSource(TranslateEngineType engineType, string apiKey = "", string secretKey = "")
public static Result InitializeTranslateSource(ITranslate translate)

功能说明: 初始化翻译源（两种重载方式）。

参数:

• engineType: 翻译引擎类型
• apiKey: API 密钥（可选）
• secretKey: 密钥（可选）
• translate: 翻译接口实例

返回值: Result 类型，表示操作结果

使用示例:

// 方式1：使用引擎类型和密钥
var result1 = Language.InitializeTranslateSource(
    TranslateEngineType.Baidu, 
    "your-api-key", 
    "your-secret-key"
);

// 方式2：使用自定义翻译接口实例
ITranslate customTranslate = new CustomTranslate();
var result2 = Language.InitializeTranslateSource(customTranslate);

---

InitializeLanguage

public static Result<int> InitializeLanguage()
public static Result<(int loadedCount, int languageCount)> InitializeLanguage(params string[] currentLanguage)

功能说明: 初始化语言资源（从数据库加载）。

参数:

• currentLanguage: 当前语言列表（可选）

返回值:

• 无参版本：返回 Result<int>，表示加载的记录数
• 有参版本：返回 Result<(int loadedCount, int languageCount)>，包含加载记录数和语言数

使用示例:

// 加载所有语言
var result1 = Language.InitializeLanguage();

// 加载指定语言
var result2 = Language.InitializeLanguage("en-US", "ja-JP");
if (result2.Successed)
{
    Console.WriteLine($"加载了 {result2.Content.loadedCount} 条记录，{result2.Content.languageCount} 种语言");
}

---

验证方法

ValidateApiKey

public static Result<bool> ValidateApiKey()

功能说明: 快速验证 API 密钥配置是否有效（仅检查配置，不执行实际翻译）。
此方法只进行快速检查，不会执行网络请求，适合在初始化时快速验证配置。

返回值: Result<bool> 类型

• Successed = true 且 Content = true：密钥配置有效
• Successed = false：配置无效，Message 包含错误信息

使用示例:

// 快速验证密钥配置
Result<bool> result = Language.ValidateApiKey();
if (result.Successed && result.Content)
{
    Console.WriteLine("密钥配置有效");
}
else
{
    Console.WriteLine($"配置无效：{result.Message}");
}

注意事项:

• 此方法只验证配置是否有效（能否创建引擎），不验证密钥是否真的有效（需要实际翻译才能验证）
• 如果密钥为空或配置错误，可以快速返回，不会影响整个流程

---

翻译方法

I18n（扩展方法）

public static string I18n(this string code)
public static string I18n(this string code, CultureInfo cultureInfo)
public static string[] I18n(this ICollection<string> code)
public static Dictionary<string, string[]> I18ns(this string code)
public static Dictionary<string, string[]> I18ns(this ICollection<string> code)

功能说明: 国际化翻译扩展方法，根据当前语言自动翻译文本（五种重载方式）。

参数:

• code: 待翻译的文本（单条或多条）
• cultureInfo: 指定的 CultureInfo，用于指定目标语言（可选）

返回值:

• 单条文本：返回翻译后的字符串
• 多条文本：返回翻译后的字符串数组
• 多语言版本：返回语言到翻译结果的字典

使用示例:

// 单条文本翻译（使用当前语言）
string chineseText = "你好";
string translated = chineseText.I18n(); // 根据当前语言自动翻译

// 指定 CultureInfo 翻译（不修改全局语言设置）
string translated2 = chineseText.I18n(new CultureInfo("ja-JP")); // 翻译为日语

// 批量文本翻译
var texts = new[] { "你好", "世界", "测试" };
string[] translatedArray = texts.I18n(); // 返回翻译后的数组

// 单条文本多语言翻译
Dictionary<string, string[]> multiResult = "你好".I18ns();
// 返回: { "en": ["Hello"], "ja": ["こんにちは"], "ko": ["안녕하세요"] }

// 批量文本多语言翻译
Dictionary<string, string[]> multiResults = texts.I18ns();
// 返回所有语言的翻译结果字典

注意事项:

• 如果 API 密钥为空，只从数据库缓存中获取，没有则返回原文
• 如果 API 密钥不为空，会尝试在线翻译并缓存结果
• I18n(code, CultureInfo) 方法不会修改全局的当前语言设置，只影响本次调用的翻译结果
• I18ns 方法会返回所有已设置语言的翻译结果

---

Get（获取翻译）

public static string Get(string currentLanguage, string code, bool allowUpdate = false)
public static string[] Get(string currentLanguage, bool allowUpdate, params string[] code)
public static Dictionary<string, string[]> Get(ICollection<string> currentLanguage, int semaphore, bool allowUpdate, params string[] code)

功能说明: 从语言资源中获取翻译（三种重载方式）。

参数:

• currentLanguage: 目标语言
• code: 待翻译的文本（单条或多条）
• allowUpdate: 是否允许更新已有翻译（仅本次调用有效）
• semaphore: 并发控制数量（多语言版本）

返回值:

• 单条文本：返回翻译后的字符串
• 多条文本：返回翻译后的字符串数组
• 多语言版本：返回语言到翻译结果的字典

使用示例:

// 单条文本翻译
string result1 = Language.Get("en", "你好");

// 多条文本翻译
string[] results = Language.Get("en", true, "你好", "世界", "测试");

// 多语言批量翻译
var languages = new[] { "en", "ja", "ko" };
Dictionary<string, string[]> multiResults = Language.Get(languages, 5, false, "你好", "世界");

---

Translate（翻译方法）

public static async Task<string[]> Translate(this string currentLanguage, params string[] code)
public static async Task<Dictionary<string, string[]>> Translate(this ICollection<string> currentLanguage, int semaphore = 5, bool allowUpdate = false, params string[] code)

功能说明: 翻译文本（异步方法，两种重载方式）。

参数:

• currentLanguage: 目标语言（单语言或多语言集合）
• code: 待翻译的文本数组
• semaphore: 并发控制数量（多语言版本）
• allowUpdate: 是否允许更新已有翻译

返回值:

• 单语言版本：返回翻译后的字符串数组
• 多语言版本：返回语言到翻译结果的字典

使用示例:

// 单语言翻译
string[] results = await "en".Translate("你好", "世界");

// 多语言翻译
var languages = new[] { "en", "ja", "ko" };
Dictionary<string, string[]> multiResults = await languages.Translate(5, false, "你好", "世界");

---

翻译管理方法

Add（添加翻译）

public static Result Add(string currentLanguage, string code, string translation)
public static Result Add(string currentLanguage, string code, string translation, bool allowUpdate)
public static Result AddBatch(string currentLanguage, Dictionary<string, string> translations)
public static Result AddBatch(string currentLanguage, Dictionary<string, string> translations, bool allowUpdate)
public static Result<(int added, int updated)> Add(string currentLanguage, Dictionary<string, string> code)

功能说明: 手动添加指定语言的翻译内容（五种重载方式）。

参数:

• currentLanguage: 目标语言代码
• code: 待翻译的原文
• translation: 翻译内容
• allowUpdate: 是否允许更新已有翻译（仅本次调用有效，不影响全局设置）
• translations: 翻译内容字典，键为原文，值为翻译

返回值:

• 单条添加：返回 Result，表示操作结果
• 批量添加（AddBatch）：返回 Result，表示操作结果
• 批量添加（Add 字典版本）：返回 Result<(int added, int updated)>，包含添加和更新的记录数量

使用示例:

// 单条添加翻译
var result1 = Language.Add("en", "你好", "Hello");
if (result1.Successed)
{
    Console.WriteLine("添加成功");
}

// 单条添加翻译（允许更新）
var result2 = Language.Add("en", "你好", "Hello (Updated)", allowUpdate: true);

// 批量添加翻译
var translations = new Dictionary<string, string>
{
    { "你好", "Hello" },
    { "世界", "World" },
    { "测试", "Test" }
};
var result3 = Language.AddBatch("en", translations);
if (result3.Successed)
{
    Console.WriteLine("批量添加成功");
}

// 批量添加翻译（允许更新）
var result4 = Language.AddBatch("en", translations, allowUpdate: true);

// 批量添加并获取统计信息
var result5 = Language.Add("en", translations);
if (result5.Successed)
{
    Console.WriteLine($"添加了 {result5.Content.added} 条新记录，更新了 {result5.Content.updated} 条记录");
}

注意事项:

• 默认语言（zh）不需要翻译，如果传入默认语言会返回错误
• allowUpdate 参数仅影响本次调用，不会修改全局的 AllowUpdateExistingTranslation 设置
• 翻译内容会自动更新到缓存和数据库

---

语言管理方法

UpdateLanguage

public static Result UpdateLanguage(this LanguageCode code)
public static Result UpdateLanguage(this string currentLanguage)
public static Result UpdateLanguage(this string currentLanguage, int index)

功能说明: 更新当前语言（三种重载方式）。

参数:

• code: 语言代码枚举
• currentLanguage: 语言字符串
• index: 语言在列表中的索引

返回值: Result 类型，表示操作结果

使用示例:

// 使用枚举
LanguageCode.English.UpdateLanguage();

// 使用字符串
"en-US".UpdateLanguage();

// 使用索引
"en-US".UpdateLanguage(0);

---

AddLanguage

public static Result AddLanguage(this string language)
public static Result<int> AddLanguage(params string[] language)

功能说明: 添加语言到多语言列表。

参数:

• language: 语言代码（单条或多条）

返回值:

• 单条版本：返回 Result
• 多条版本：返回 Result<int>，表示成功添加的语言数量

使用示例:

// 添加单条语言
"en-US".AddLanguage();

// 添加多条语言
var result = Language.AddLanguage("en-US", "ja-JP", "ko-KR");
if (result.Successed)
{
    Console.WriteLine($"成功添加 {result.Content} 种语言");
}

---

ClearLanguage

public static Result ClearLanguage()

功能说明: 清除多语言列表。

返回值: Result 类型，表示操作结果

使用示例:

var result = Language.ClearLanguage();

---

文档翻译方法

TranslateDocumentAsync

public static async Task<Result<string>> TranslateDocumentAsync(string sourceLanguage, string targetLanguage, string documentFilePath, string? outputFilePath = null, CancellationToken cancellationToken = default)
public static async Task<Result<byte[]>> TranslateDocumentAsync(string sourceLanguage, string targetLanguage, byte[] documentBytes, string fileName, CancellationToken cancellationToken = default)

功能说明: 异步翻译文档（支持 Word、PDF、Excel 等格式）。

参数:

• sourceLanguage: 源语言代码（如 "zh", "en"）
• targetLanguage: 目标语言代码（如 "en", "ja"）
• documentFilePath: 源文件路径
• outputFilePath: 输出文件路径（可选，默认覆盖原文件）
• documentBytes: 文档字节数组
• fileName: 文件名（用于识别文件类型，如 "document.docx"）
• cancellationToken: 取消令牌（可选）

返回值:

• 文件路径版本：返回 Result<string>，包含输出文件路径
• 字节数组版本：返回 Result<byte[]>，包含翻译后的文档字节

使用示例:

// 翻译文件
var result1 = await Language.TranslateDocumentAsync(
    "zh",           // 源语言：中文
    "en",            // 目标语言：英文
    "document.docx", // 源文件路径
    "document_en.docx" // 输出文件路径（可选）
);

if (result1.Successed)
{
    Console.WriteLine($"翻译完成，输出文件: {result1.Content}");
}

// 翻译字节数组
byte[] documentBytes = File.ReadAllBytes("document.pdf");
var result2 = await Language.TranslateDocumentAsync(
    "zh",              // 源语言：中文
    "en",              // 目标语言：英文
    documentBytes,     // 文档字节数组
    "document.pdf"     // 文件名
);
if (result2.Successed)
{
    File.WriteAllBytes("document_en.pdf", result2.Content);
}

注意事项:

• 当前仅支持 MicrosoftEngine 和 GoogleEngine 引擎的文档翻译功能
• 如果当前引擎不支持文档翻译，会返回错误信息

---

IsDocumentTranslationSupported

public static bool IsDocumentTranslationSupported()

功能说明: 检查是否支持文档翻译。

返回值: bool，true 表示支持，false 表示不支持

---

GetSupportedDocumentFormats

public static string[] GetSupportedDocumentFormats()

功能说明: 获取支持的文档格式列表。

返回值: 支持的文档格式数组（如 [".docx", ".pdf", ".xlsx"]）

---

IsSupportedDocumentFormat

public static bool IsSupportedDocumentFormat(string fileExtension)

功能说明: 检查文件扩展名是否支持文档翻译。

参数:

• fileExtension: 文件扩展名（如 ".docx"）

返回值: bool，true 表示支持，false 表示不支持

---

事件

LanguageChanged

public static event Action<string> LanguageChanged;

功能说明: 语言切换事件，当语言改变时触发。

使用示例:

Language.LanguageChanged += (newLanguage) =>
{
    Console.WriteLine($"语言已切换为: {newLanguage}");
};

---

系统文化同步

EnableSystemCultureSync

public static bool EnableSystemCultureSync { get; set; }

功能说明: 是否启用系统文化同步（默认 false）。

---

EnableSystemCultureAutoSync

public static void EnableSystemCultureAutoSync(int checkIntervalMs = 1000)

功能说明: 启用系统文化自动同步。

参数:

• checkIntervalMs: 检查间隔（毫秒），默认 1000 毫秒

使用示例:

Language.EnableSystemCultureAutoSync(2000); // 每2秒检查一次

---

DisableSystemCultureAutoSync

public static void DisableSystemCultureAutoSync()

功能说明: 禁用系统文化自动同步。

使用示例:

// 启用自动同步
Language.EnableSystemCultureAutoSync(1000);

// 后续禁用自动同步
Language.DisableSystemCultureAutoSync();

---

使用示例

完整初始化示例

using Hi.Ltd.LocalResource;

// 1. 初始化翻译引擎和多语言
var initResult = Language.Initialize(
    TranslateEngineType.Baidu,
    "your-api-key",
    "your-secret-key",
    "en-US", "ja-JP", "ko-KR"
);

if (!initResult.Successed)
{
    Console.WriteLine($"初始化失败: {initResult.Message}");
    return;
}

// 2. 验证 API 密钥配置
var validateResult = Language.ValidateApiKey();
if (!validateResult.Successed || !validateResult.Content)
{
    Console.WriteLine($"密钥配置无效: {validateResult.Message}");
    return;
}

// 3. 加载语言资源
var loadResult = Language.InitializeLanguage("en-US", "ja-JP");
if (loadResult.Successed)
{
    Console.WriteLine($"加载了 {loadResult.Content.loadedCount} 条翻译记录");
}

// 4. 设置当前语言
"en-US".UpdateLanguage();

// 5. 使用翻译
string translated = "你好".I18n();
Console.WriteLine(translated); // 输出: Hello

---

RESX 文件本地化示例

using Hi.Ltd.LocalResource;

// 初始化本地化文件（自动翻译并创建多语言 resx 文件）
string projectPath = @"C:\MyProject";
var result = projectPath.InitializeLocateFiles(
    isOverWrite: false,  // 不覆盖已有翻译
    isUpdate: false,
    "en-US", "ja-JP", "ko-KR"
);

if (result.Successed)
{
    Console.WriteLine($"成功处理 {result.Content} 个文件");
}

---

数据库操作方法

查询方法

QueryByLanguage - 根据语言代码查询翻译记录

public static Result<List<LocateSource>> QueryByLanguage(string language, int limit = -1)

功能说明: 根据语言代码查询翻译记录。

参数:

• language: 语言代码
• limit: 查询数量限制，-1 表示不限制

返回值: Result<List<LocateSource>>，成功时包含翻译记录列表

使用示例:

var result = Language.QueryByLanguage("en", limit: 100);
if (result.Successed)
{
    foreach (var item in result.Content)
    {
        Console.WriteLine($"{item.Code}: {item.Translation}");
    }
}

---

QueryByCode - 根据原文代码查询翻译记录

public static Result<List<LocateSource>> QueryByCode(string code)

功能说明: 根据原文代码查询所有语言的翻译记录。

参数:

• code: 原文代码

返回值: Result<List<LocateSource>>，成功时包含所有语言的翻译记录列表

使用示例:

var result = Language.QueryByCode("你好");
if (result.Successed)
{
    foreach (var item in result.Content)
    {
        Console.WriteLine($"{item.Language}: {item.Translation}");
    }
}

---

QueryByCodeAndLanguage - 根据原文代码和语言代码查询翻译记录

public static Result<LocateSource> QueryByCodeAndLanguage(string code, string language)

功能说明: 根据原文代码和语言代码查询单条翻译记录。

参数:

• code: 原文代码
• language: 语言代码

返回值: Result<LocateSource>，成功时包含翻译记录（如果不存在则为 null）

使用示例:

var result = Language.QueryByCodeAndLanguage("你好", "en");
if (result.Successed && result.Content != null)
{
    Console.WriteLine($"翻译: {result.Content.Translation}");
}

---

QueryByCodeAndLanguageBatch - 批量查询翻译记录

public static Result<Dictionary<(string code, string language), LocateSource>> QueryByCodeAndLanguageBatch(List<(string code, string language)> codeLanguagePairs)

功能说明: 批量根据原文代码和语言代码查询翻译记录。

参数:

• codeLanguagePairs: 原文代码和语言代码的元组列表

返回值: Result<Dictionary<(string code, string language), LocateSource>>，成功时包含查询结果字典

使用示例:

var pairs = new List<(string, string)>
{
    ("你好", "en"),
    ("世界", "en"),
    ("测试", "ja")
};
var result = Language.QueryByCodeAndLanguageBatch(pairs);
if (result.Successed)
{
    foreach (var kvp in result.Content)
    {
        Console.WriteLine($"{kvp.Key.code} ({kvp.Key.language}): {kvp.Value.Translation}");
    }
}

---

Search - 搜索翻译记录

public static Result<List<LocateSource>> Search(string keyword, bool searchInCode = true, bool searchInTranslation = true, string language = null, int limit = 100)

功能说明: 在原文或翻译中搜索关键词。

参数:

• keyword: 搜索关键词
• searchInCode: 是否在原文中搜索（默认 true）
• searchInTranslation: 是否在翻译中搜索（默认 true）
• language: 指定语言代码，为空则搜索所有语言
• limit: 查询数量限制（默认 100）

返回值: Result<List<LocateSource>>，成功时包含匹配的翻译记录列表

使用示例:

// 在所有语言中搜索
var result1 = Language.Search("Hello", searchInCode: false, searchInTranslation: true);

// 在指定语言中搜索
var result2 = Language.Search("你好", language: "en", limit: 50);

---

QueryByPage - 分页查询翻译记录

public static Result<List<LocateSource>> QueryByPage(int pageIndex, int pageSize, string language = null)

功能说明: 分页查询翻译记录。

参数:

• pageIndex: 页码（从 1 开始）
• pageSize: 每页数量（最大 1000）
• language: 语言代码，为空则查询所有语言

返回值: Result<List<LocateSource>>，成功时包含翻译记录列表

使用示例:

// 查询第一页，每页 20 条
var result = Language.QueryByPage(1, 20, "en");
if (result.Successed)
{
    foreach (var item in result.Content)
    {
        Console.WriteLine($"{item.Code}: {item.Translation}");
    }
}

---

统计方法

GetTotalCount - 获取翻译记录总数

public static Result<int> GetTotalCount(string language = null)

功能说明: 获取翻译记录总数。

参数:

• language: 语言代码，为空则统计所有语言

返回值: Result<int>，成功时包含记录总数

使用示例:

// 获取所有语言的记录总数
var totalResult = Language.GetTotalCount();

// 获取指定语言的记录总数
var enResult = Language.GetTotalCount("en");

---

GetAllLanguages - 获取所有支持的语言列表

public static Result<List<string>> GetAllLanguages()

功能说明: 获取数据库中所有支持的语言代码列表（去重）。

返回值: Result<List<string>>，成功时包含语言代码列表

使用示例:

var result = Language.GetAllLanguages();
if (result.Successed)
{
    foreach (var lang in result.Content)
    {
        Console.WriteLine(lang);
    }
}

---

GetLanguageStatistics - 获取语言统计信息

public static Result<Dictionary<string, int>> GetLanguageStatistics()

功能说明: 获取每种语言的翻译记录数量。

返回值: Result<Dictionary<string, int>>，成功时包含语言代码和数量的字典

使用示例:

var result = Language.GetLanguageStatistics();
if (result.Successed)
{
    foreach (var kvp in result.Content)
    {
        Console.WriteLine($"{kvp.Key}: {kvp.Value} 条记录");
    }
}

---

GetTranslationProgress - 获取翻译完成度

public static Result<double> GetTranslationProgress(string language)

功能说明: 获取指定语言的翻译完成度（相对于中文原文的数量，百分比 0-100）。

参数:

• language: 语言代码

返回值: Result<double>，成功时包含完成度百分比

使用示例:

var result = Language.GetTranslationProgress("en");
if (result.Successed)
{
    Console.WriteLine($"英文翻译完成度: {result.Content}%");
}

---

删除方法

DeleteById - 根据ID删除翻译记录

public static Result DeleteById(int id)

功能说明: 根据记录ID删除翻译记录。

参数:

• id: 记录ID

返回值: Result，表示操作结果

使用示例:

var result = Language.DeleteById(123);
if (result.Successed)
{
    Console.WriteLine("删除成功");
}

---

DeleteByLanguage - 根据语言代码删除所有翻译记录

public static Result<int> DeleteByLanguage(string language)

功能说明: 根据语言代码删除该语言的所有翻译记录。

参数:

• language: 语言代码

返回值: Result<int>，成功时包含删除的记录数量

使用示例:

var result = Language.DeleteByLanguage("en");
if (result.Successed)
{
    Console.WriteLine($"删除了 {result.Content} 条记录");
}

---

DeleteByCode - 根据原文代码删除所有语言的翻译记录

public static Result<int> DeleteByCode(string code)

功能说明: 根据原文代码删除所有语言的翻译记录。

参数:

• code: 原文代码

返回值: Result<int>，成功时包含删除的记录数量

使用示例:

var result = Language.DeleteByCode("你好");
if (result.Successed)
{
    Console.WriteLine($"删除了 {result.Content} 条记录");
}

---

DeleteEmptyTranslations - 删除空的翻译记录

public static Result<int> DeleteEmptyTranslations(string language = null)

功能说明: 删除翻译内容为空的记录。

参数:

• language: 语言代码，为空则删除所有语言的空记录

返回值: Result<int>，成功时包含删除的记录数量

使用示例:

// 删除所有语言的空记录
var result1 = Language.DeleteEmptyTranslations();

// 删除指定语言的空记录
var result2 = Language.DeleteEmptyTranslations("en");

---

ClearAll - 清空所有翻译记录

public static Result<int> ClearAll(bool confirm = false)

功能说明: 清空所有翻译记录（危险操作，需要确认）。

参数:

• confirm: 确认标志，必须为 true 才能执行

返回值: Result<int>，成功时包含删除的记录数量

使用示例:

// 危险操作，需要明确确认
var result = Language.ClearAll(confirm: true);
if (result.Successed)
{
    Console.WriteLine($"清空了 {result.Content} 条记录");
}

---

批量操作方法

BatchUpdate - 批量更新翻译记录

public static Result<int> BatchUpdate(List<LocateSource> items)

功能说明: 批量更新翻译记录。

参数:

• items: 要更新的翻译记录列表

返回值: Result<int>，成功时包含成功更新的记录数量

使用示例:

var items = new List<LocateSource>
{
    new LocateSource { Id = 1, Code = "你好", Language = "en", Translation = "Hello" },
    new LocateSource { Id = 2, Code = "世界", Language = "en", Translation = "World" }
};
var result = Language.BatchUpdate(items);
if (result.Successed)
{
    Console.WriteLine($"更新了 {result.Content} 条记录");
}

---

BatchInsert - 批量插入翻译记录

public static Result<int> BatchInsert(List<LocateSource> items)

功能说明: 批量插入翻译记录（如果已存在则更新）。

参数:

• items: 要插入的翻译记录列表

返回值: Result<int>，成功时包含成功插入的记录数量

使用示例:

var items = new List<LocateSource>
{
    new LocateSource { Code = "你好", Language = "en", Translation = "Hello" },
    new LocateSource { Code = "世界", Language = "en", Translation = "World" }
};
var result = Language.BatchInsert(items);
if (result.Successed)
{
    Console.WriteLine($"插入了 {result.Content} 条记录");
}

---

BatchDelete - 批量删除翻译记录

public static Result<int> BatchDelete(List<LocateSource> items)

功能说明: 批量删除翻译记录（使用 SQL IN 子句，高效批量删除）。

参数:

• items: 要删除的翻译记录列表

返回值: Result<int>，成功时包含成功删除的记录数量

使用示例:

var items = new List<LocateSource>
{
    new LocateSource { Id = 1 },
    new LocateSource { Id = 2 },
    new LocateSource { Id = 3 }
};
var result = Language.BatchDelete(items);
if (result.Successed)
{
    Console.WriteLine($"删除了 {result.Content} 条记录");
}

---

数据维护方法

RepairData - 检查并修复数据完整性

public static Result<int> RepairData()

功能说明: 检查并修复数据完整性（删除无效记录和重复记录）。

返回值: Result<int>，成功时包含修复的记录数量

使用示例:

var result = Language.RepairData();
if (result.Successed)
{
    Console.WriteLine($"修复了 {result.Content} 条记录");
}

---

OptimizeDatabase - 优化数据库

public static Result OptimizeDatabase()

功能说明: 优化数据库（执行 VACUUM 操作）。

返回值: Result，表示操作结果

使用示例:

var result = Language.OptimizeDatabase();
if (result.Successed)
{
    Console.WriteLine("数据库优化成功");
}

---

GetDatabaseSize - 获取数据库文件大小

public static Result<long> GetDatabaseSize()

功能说明: 获取数据库文件大小（字节）。

返回值: Result<long>，成功时包含文件大小（字节）

使用示例:

var result = Language.GetDatabaseSize();
if (result.Successed)
{
    Console.WriteLine($"数据库大小: {result.Content / 1024.0 / 1024.0:F2} MB");
}

---

BackupDatabase - 备份数据库

public static Result BackupDatabase(string backupPath)

功能说明: 备份数据库到指定路径。

参数:

• backupPath: 备份文件路径

返回值: Result，表示操作结果

使用示例:

var result = Language.BackupDatabase(@"C:\Backup\Language.db");
if (result.Successed)
{
    Console.WriteLine("备份成功");
}

---

RestoreDatabase - 恢复数据库

public static Result RestoreDatabase(string backupPath, bool confirm = false)

功能说明: 从备份文件恢复数据库（危险操作，需要确认）。

参数:

• backupPath: 备份文件路径
• confirm: 确认标志，必须为 true 才能执行

返回值: Result，表示操作结果

使用示例:

// 危险操作，需要明确确认
var result = Language.RestoreDatabase(@"C:\Backup\Language.db", confirm: true);
if (result.Successed)
{
    Console.WriteLine("恢复成功");
}

---

MergeDatabase - 合并数据库

public static Result<int> MergeDatabase(this string sourceDbPath, bool overwriteExisting = false)

功能说明: 合并数据库内容（相同数据库名称及表结构）。

参数:

• sourceDbPath: 源数据库文件路径（包含数据库文件名的完整路径）
• overwriteExisting: 是否覆盖目标数据库中已存在的记录（默认 false，以目标数据库为主）

返回值: Result<int>，成功时包含合并的记录数量（新增+更新）

合并规则:

1. 读取源数据库的所有记录
2. 对于每条记录，检查目标数据库中是否存在（基于 Code 和 Language）
3. 如果不存在，插入新记录
4. 如果存在，根据 overwriteExisting 参数决定是否覆盖
5. 合并完成后自动去重（相同 Code + Language，保留 ID 最小的记录）
6. 重新初始化缓存信息

使用示例:

// 合并数据库，不覆盖已有记录
var result1 = @"C:\Source\Language.db".MergeDatabase(overwriteExisting: false);

// 合并数据库，覆盖已有记录
var result2 = @"C:\Source\Language.db".MergeDatabase(overwriteExisting: true);
if (result2.Successed)
{
    Console.WriteLine($"合并了 {result2.Content} 条记录");
}

---

注意事项

1. API 密钥: 如果没有设置 API 密钥，系统只从数据库缓存中获取翻译，不会调用在线翻译服务
2. 缓存机制: 翻译结果会自动缓存到 SQLite 数据库，避免重复翻译
3. 线程安全: 大部分方法是线程安全的，但建议在单线程环境中进行初始化
4. 性能优化: 批量翻译会自动优化，合并相似文本，减少翻译次数
5. 错误处理: 所有方法都返回 Result 类型，请务必检查 Successed 属性
6. 翻译引擎: 支持多种翻译引擎，根据实际需求选择合适的引擎类型
7. 数据库操作: 所有数据库操作方法都会自动同步更新缓存
8. 危险操作: ClearAll 和 RestoreDatabase 是危险操作，需要明确确认才能执行

---

ResxHelper 类（RESX 文件本地化工具）

类说明

ResxHelper 类（位于 Hi.Ltd.LocalResource 命名空间）提供了 RESX 文件本地化的扩展方法，支持：

• 自动扫描项目中的 RESX 文件
• 智能翻译并创建多语言 RESX 文件
• 支持自定义翻译属性（如 .Text, .ToolTip 等）
• 支持保留已有翻译或覆盖翻译
• 一键清理本地化文件

方法

InitializeLocateFiles（初始化本地化文件）

public static Result<int> InitializeLocateFiles(this string path, bool isOverWrite = true, bool isUpdate = false, params string[] multiLanguage)
public static Result<int> InitializeLocateFiles(this string path, string[] handleItems, bool isOverWrite = true, bool isUpdate = false, params string[] multiLanguage)

功能说明: 初始化本地化文件，自动翻译并创建多语言 RESX 文件。

参数:

• path: 项目路径或目录路径
• handleItems: 需要翻译的属性项数组（如 [".Text", ".ToolTip"]），如果为 null 或空，使用默认属性
• isOverWrite: 是否覆盖已有翻译
  • true: 替换已有翻译项
  • false: 保留已有翻译，只添加新项
• isUpdate: 是否更新缓存（强制重新扫描文件）
• multiLanguage: 目标语言列表（如 "en-US", "ja-JP", "ko-KR"）

返回值: Result<int> 类型，表示成功处理的文件数量

使用示例:

using Hi.Ltd.LocalResource;

// 方式1：使用默认翻译属性（.Text, .ToolTip, .BalloonTipText, .BalloonTipTitle）
string projectPath = @"C:\MyProject";
var result1 = projectPath.InitializeLocateFiles(
    isOverWrite: false,  // 保留已有翻译
    isUpdate: false,
    "en-US", "ja-JP", "ko-KR"
);

// 方式2：自定义翻译属性
string[] customProperties = new[] { ".Text", ".ToolTip", ".Caption", ".Header" };
var result2 = projectPath.InitializeLocateFiles(
    customProperties,
    isOverWrite: true,  // 覆盖已有翻译
    isUpdate: false,
    "en-US", "ja-JP"
);

if (result1.Successed)
{
    Console.WriteLine($"成功处理 {result1.Content} 个文件");
}

功能特点:

• 自动扫描指定路径下的所有 .resx 文件
• 识别需要翻译的节点（包含指定属性的节点，以及纯中文文本节点）
• 排除不需要翻译的属性（如 .Name, .Location, .Size 等）
• 如果文件不存在，创建新的本地化文件
• 如果文件存在：
  • isOverWrite = true: 替换已有翻译项
  • isOverWrite = false: 保留已有翻译，只添加新项
• 只修改文本内容，保留其他属性（如字体大小等）

注意事项:

• 需要先初始化 Language 类（设置 API 密钥和翻译引擎）
• 如果没有 API 密钥，只从数据库缓存中获取翻译
• 翻译过程可能需要一些时间，建议在后台线程执行

---

GetAllResxFilePath（获取所有 RESX 文件路径）

public static Result<List<string>> GetAllResxFilePath(this string path, bool isUpdate = false)

功能说明: 获取指定路径下的所有 RESX 文件路径。

参数:

• path: 项目路径或目录路径
• isUpdate: 是否强制更新缓存（默认 false）

返回值: Result<List<string>> 类型，成功时包含所有 RESX 文件路径列表

使用示例:

using Hi.Ltd.LocalResource;

string projectPath = @"C:\MyProject";
var result = projectPath.GetAllResxFilePath(isUpdate: false);

if (result.Successed)
{
    Console.WriteLine($"找到 {result.Content.Count} 个 RESX 文件");
    foreach (var filePath in result.Content)
    {
        Console.WriteLine(filePath);
    }
}

功能特点:

• 自动排除系统目录（如 bin, obj, build, .vs, .git 等）
• 只返回基础 RESX 文件（文件名不包含语言代码的文件）
• 支持缓存机制，提高性能
• 递归扫描子目录

---

DeleteAllLocalizedFiles（删除所有本地化文件）

public static Result<int> DeleteAllLocalizedFiles(this string path, bool isUpdate = false)

功能说明: 删除所有本地化 RESX 文件，只保留基础文件（如 Form1.resx），删除所有语言版本（如 Form1.en-US.resx, Form1.ja-JP.resx 等）。

参数:

• path: 项目路径或目录路径
• isUpdate: 是否更新缓存（强制重新扫描文件）

返回值: Result<int> 类型，表示成功删除的文件数量

使用示例:

using Hi.Ltd.LocalResource;

string projectPath = @"C:\MyProject";
var result = projectPath.DeleteAllLocalizedFiles(isUpdate: false);

if (result.Successed)
{
    Console.WriteLine($"成功删除 {result.Content} 个本地化文件");
    // 现在可以重新初始化本地化文件
    projectPath.InitializeLocateFiles(true, false, "en-US", "ja-JP", "ko-KR");
}

功能特点:

• 自动识别本地化文件（通过语言代码格式验证）
• 保留基础 RESX 文件（如 Form1.resx）
• 删除所有语言版本（如 Form1.en-US.resx, Form1.ja-JP.resx 等）
• 支持识别标准语言代码和自定义语言代码

使用场景:

• 需要重新生成所有本地化文件时
• 清理旧的或错误的翻译文件
• 准备进行全新的本地化流程

---

GenCsvFile（生成 CSV 语言文件）

public static Result<int> GenCsvFile(this string filePath)

功能说明: 生成 CSV 语言文件，将当前缓存中的所有翻译数据导出为 CSV 格式。

参数:

• filePath: CSV 文件路径

返回值: Result<int> 类型，表示成功写入的行数

使用示例:

using Hi.Ltd.LocalResource;

string csvPath = @"C:\Translations\language.csv";
var result = csvPath.GenCsvFile();
if (result.Successed)
{
    Console.WriteLine($"成功生成 CSV 文件，共 {result.Content} 行");
}

CSV 文件格式:

• 第一行：表头，格式为 Id,zh,语言1,语言2,...
• 后续行：数据行，格式为 ID,中文原文,翻译1,翻译2,...

注意事项:

• 需要先加载语言资源（调用 InitializeLanguage）
• 如果缓存为空，会返回错误

---

ImportFromFile（从 CSV 文件导入翻译数据）

public static Result<int> ImportFromFile(this string filedPath, bool isOverWrite = false)

功能说明: 从 CSV 文件导入翻译数据到缓存和数据库。

参数:

• filedPath: CSV 文件路径
• isOverWrite: 是否覆盖数据库中的已有数据（默认 false，不修改数据库）

返回值: Result<int> 类型，表示成功导入的记录数量

使用示例:

using Hi.Ltd.LocalResource;

// 导入 CSV 文件，不覆盖数据库
string csvPath = @"C:\Translations\language.csv";
var result1 = csvPath.ImportFromFile(isOverWrite: false);
if (result1.Successed)
{
    Console.WriteLine($"成功导入 {result1.Content} 条记录到缓存");
}

// 导入 CSV 文件，覆盖数据库
var result2 = csvPath.ImportFromFile(isOverWrite: true);
if (result2.Successed)
{
    Console.WriteLine($"成功导入并更新 {result2.Content} 条记录");
}

CSV 文件格式要求:

• 第一行必须是表头：Id,zh,语言1,语言2,...
• 至少需要 3 列（Id, zh, 至少一种语言）
• 数据行格式：ID,中文原文,翻译1,翻译2,...

功能特点:

• 自动识别 CSV 文件中的语言列
• 如果缓存中没有该语言，会自动创建
• isOverWrite = true 时，会更新数据库中已存在的记录
• isOverWrite = false 时，只更新缓存，不修改数据库

注意事项:

• CSV 文件必须使用 UTF-8 编码
• 支持 CSV 标准格式（包含引号转义等）

---

使用示例

完整的本地化流程

using Hi.Ltd.LocalResource;

// 1. 初始化翻译引擎
Language.Initialize(
    TranslateEngineType.Baidu,
    "your-api-key",
    "your-secret-key",
    "en-US", "ja-JP", "ko-KR"
);

// 2. 验证 API 密钥
var validateResult = Language.ValidateApiKey();
if (!validateResult.Successed || !validateResult.Content)
{
    Console.WriteLine($"密钥配置无效: {validateResult.Message}");
    return;
}

// 3. 清理旧的本地化文件（可选）
string projectPath = @"C:\MyProject";
var deleteResult = projectPath.DeleteAllLocalizedFiles();
if (deleteResult.Successed)
{
    Console.WriteLine($"已删除 {deleteResult.Content} 个旧文件");
}

// 4. 初始化本地化文件
var initResult = projectPath.InitializeLocateFiles(
    isOverWrite: false,  // 保留已有翻译
    isUpdate: false,
    "en-US", "ja-JP", "ko-KR"
);

if (initResult.Successed)
{
    Console.WriteLine($"成功处理 {initResult.Content} 个文件");
}
else
{
    Console.WriteLine($"处理失败: {initResult.Message}");
}

---

自定义翻译属性

using Hi.Ltd.LocalResource;

// 只翻译特定的属性
string[] customProperties = new[] 
{ 
    ".Text", 
    ".ToolTip", 
    ".Caption", 
    ".Header",
    ".Hint",
    ".ErrorMessage"
};

string projectPath = @"C:\MyProject";
var result = projectPath.InitializeLocateFiles(
    customProperties,
    isOverWrite: true,
    isUpdate: false,
    "en-US", "ja-JP"
);

---

注意事项

1. API 密钥: 需要先初始化 Language 类并设置有效的 API 密钥
2. 文件路径: 确保路径正确，方法会递归扫描子目录
3. 翻译属性: 默认翻译 .Text, .ToolTip, .BalloonTipText, .BalloonTipTitle，可通过参数自定义
4. 覆盖模式:
   • isOverWrite = true: 适合首次创建或需要更新翻译
   • isOverWrite = false: 适合增量更新，保留已有翻译
5. 性能考虑: 大量文件翻译可能需要较长时间，建议在后台线程执行
6. 排除属性: 系统会自动排除不需要翻译的属性（如 .Name, .Location, .Size 等）

---