Bitzsoft.Integrations.Translation.Abstractions 1.0.0

Bitzsoft.Integrations.Translation.Abstractions

翻译服务抽象层 -- 统一传统机器翻译（阿里云 / 百度 / 腾讯云 / 有道 / DeepL / Google）与 AI 大模型翻译 （OpenAI 兼容网关 / Anthropic / 通义 Qwen-MT / 百度大模型 / 火山引擎大模型）的接口定义、结果模型、领域错误码与多供应商工厂。

本包仅含抽象层（接口、工厂、模型、异常、统一 Options 基类）。各厂商实现见独立子包，或一步到位的聚合包 Translation.All。

功能特性

• 统一契约：一套 ITranslationProvider 接口覆盖单文本、批量与语言检测，结果携带检测语言与置信度
• AI 扩展契约：IAiTranslationProvider : ITranslationProvider 增加风格 / 术语约束、温度、系统提示词模板
• 领域词汇表注入点：TranslationTerm（原文=译文）随请求传递，原生支持术语干预的供应商严格采用
• 统一语言编码：TranslationLanguages 把 zh-CN / ZH / Chinese 等别名收敛为统一短码，厂商包内部映射
• 统一 Options 基类：TranslationProviderOptions 沉淀 BaseAddress / ApiKey / AppId+AppSecret / 超时 / 重试 通用配置
• 标准错误码：TranslationErrors 收敛配额、鉴权失败、语言不支持、网络不可达等跨供应商错误语义
• Provider 工厂：ITranslationProviderFactory 按编码（aliyun / deepl / openai ...）运行时解析，支撑按语言 / 用途路由
• 健康探测：CheckHealthAsync 以最小代价（用量 / 语言列表 / 模型列表）探测供应商可用性

安装

dotnet add package Bitzsoft.Integrations.Translation.Abstractions

通常无需单独安装本包，安装任意一个厂商实现包或聚合包时会自动引入。

核心契约

ITranslationProvider

public interface ITranslationProvider
{
    // 供应商编码（"aliyun" / "deepl" / "google" / "openai" ...）
    string Code { get; }

    // 单文本翻译（结果含检测语言与置信度）
    Task<TranslationResult<TranslationTextResult>> TranslateAsync(
        TranslationTextRequest request, CancellationToken ct = default);

    // 批量翻译（结果顺序与请求一一对应）
    Task<TranslationResult<TranslationBatchResult>> TranslateBatchAsync(
        TranslationBatchRequest request, CancellationToken ct = default);

    // 语言检测（供应商无检测接口时返回 NotSupported）
    Task<TranslationResult<TranslationDetectionResult>> DetectLanguageAsync(
        TranslationDetectRequest request, CancellationToken ct = default);

    // 健康探测（启动探活 / 路由决策）
    Task<TranslationHealthResult> CheckHealthAsync(CancellationToken ct = default);
}

IAiTranslationProvider

// 大模型翻译扩展：风格 / 术语约束、温度、系统提示词模板
public interface IAiTranslationProvider : ITranslationProvider
{
    Task<TranslationResult<TranslationTextResult>> TranslateAsync(
        AiTranslationRequest request, CancellationToken ct = default);
}

AiTranslationRequest 在基础请求之上增加 Style（译文风格）、Instructions（附加指令）、 SystemPromptTemplate（占位符模板）、Temperature（采样温度）与 MaxOutputTokens。 超长文本由 AI 实现包自动按长度上限分段并回拼，输出优先 JSON 模式解析、失败回退纯文本。

ITranslationProviderFactory

public interface ITranslationProviderFactory
{
    ITranslationProvider GetProvider(string code);   // 按编码解析
    IEnumerable<string> GetRegisteredCodes();        // 已注册的供应商编码
}

使用示例

// 注册任意厂商实现包后（如 AddBitzsoftDeepLTranslation），工厂按编码解析
public class TranslationService(ITranslationProviderFactory factory)
{
    public async Task<string> TranslateContractAsync(string text)
    {
        var provider = factory.GetProvider("deepl");

        var result = await provider.TranslateAsync(new TranslationTextRequest
        {
            Text = text,
            SourceLanguage = "auto",
            TargetLanguage = "zh",
            Terms = new[]
            {
                new TranslationTerm("force majeure", "不可抗力"),
                new TranslationTerm("consideration", "对价"),
            }
        });

        return result.IsSuccess
            ? result.Data!.TranslatedText
            : throw new InvalidOperationException($"{result.ErrorCode}: {result.ErrorMessage}");
    }
}

按语言 / 用途路由

// 中文为主的法律文书走 DeepL，站内消息走阿里云，批量走 Google 官方 API
var code = usage switch
{
    "legal" => "deepl",
    "message" => "aliyun",
    _ => "google",
};
var provider = factory.GetProvider(code);

核心类型一览

供应商编码对照表

与 AI 域抽象的关系

模型调用复用既有 Bitzsoft.Integrations.AI.Abstractions 的 IAIChatClientFactory / IChatClient 体系（密钥进凭据存储、租户感知）；翻译特有语义（术语注入、 统一语言编码、分段回拼、JSON 输出回退、领域错误码）全部落在本抽象与翻译实现包内，两个抽象互不依赖。

相关包

• Bitzsoft.Integrations.Translation.Aliyun -- 阿里云机器翻译
• Bitzsoft.Integrations.Translation.Baidu -- 百度翻译
• Bitzsoft.Integrations.Translation.Tencent -- 腾讯云机器翻译
• Bitzsoft.Integrations.Translation.Youdao -- 有道智云翻译
• Bitzsoft.Integrations.Translation.DeepL -- DeepL
• Bitzsoft.Integrations.Translation.Google -- Google 官方翻译 API
• Bitzsoft.Integrations.Translation.AI.OpenAI -- OpenAI 兼容网关大模型翻译
• Bitzsoft.Integrations.Translation.AI.Anthropic -- Claude 大模型翻译
• Bitzsoft.Integrations.Translation.AI.Tongyi -- 通义 Qwen-MT 翻译
• Bitzsoft.Integrations.Translation.AI.Baidu -- 百度大模型文本翻译
• Bitzsoft.Integrations.Translation.AI.Volcengine -- 火山引擎机器翻译大模型
• Bitzsoft.Integrations.Translation.All -- 聚合包