XUnity.AutoTranslator 自定义翻译端点开发指南

概述

XUnity.AutoTranslator 是一个强大的 Unity 游戏自动翻译框架，它允许开发者通过插件机制扩展翻译功能。本文将详细介绍如何为 XUnity.AutoTranslator 开发自定义翻译端点，以 LibreTranslate 为例，帮助开发者理解其工作原理和实现方法。

核心组件结构

XUnity.AutoTranslator 的翻译端点系统基于以下几个关键接口和类：

1. HttpEndpoint 基类：提供 HTTP 请求的基础功能
2. IInitializationContext 接口：处理端点初始化
3. IHttpRequestCreationContext 接口：负责创建 HTTP 请求
4. IHttpTranslationExtractionContext 接口：处理翻译结果提取

实现步骤详解

1. 端点类定义

自定义翻译端点需要继承自 HttpEndpoint 基类，并实现三个核心方法：

public class LibreTranslateEndpoint : HttpEndpoint
{
    // 端点标识符，必须唯一
    public override string Id => "LibreTranslate";
    
    // 用户友好名称，显示在UI中
    public override string FriendlyName => "LibreTranslate";
    
    // 初始化方法
    public override void Initialize(IInitializationContext context) { ... }
    
    // 创建请求方法
    public override void OnCreateRequest(IHttpRequestCreationContext context) { ... }
    
    // 提取翻译结果方法
    public override void OnExtractTranslation(IHttpTranslationExtractionContext context) { ... }
}

2. 初始化实现

初始化阶段需要从配置文件中读取必要的参数，并进行验证：

private string _endpointUrl;

public override void Initialize(IInitializationContext context)
{
    _endpointUrl = context.GetOrCreateSetting("LibreTranslate", "Url", "http://localhost:5000/");
    
    if(string.IsNullOrEmpty(_endpointUrl))
    {
        throw new EndpointInitializationException("LibreTranslate端点需要配置URL");
    }
    
    // 可选：为特定主机禁用证书检查
    var uri = new Uri(_endpointUrl);
    context.DisableCertificateChecksFor(new[] { uri.Host });
    
    // 更新友好名称显示主机信息
    FriendlyName = $"LibreTranslate ({uri.Host})";
}

3. 请求创建实现

创建翻译请求时，需要正确处理多文本批量和单文本情况：

public override void OnCreateRequest(IHttpRequestCreationContext context)
{
    // 构造请求体
    var requestBody = new {
        q = string.Join("\n", context.UntranslatedTexts),
        source = context.SourceLanguage,
        target = context.DestinationLanguage
    };
    
    // 创建POST请求
    var request = new XUnityWebRequest(_endpointUrl, "POST")
    {
        ContentType = "application/json",
        RequestBody = JsonConvert.SerializeObject(requestBody)
    };
    
    context.Complete(request);
}

4. 结果提取实现

处理API返回结果时需要考虑各种边界情况：

private class TranslationResponse
{
    public string translatedText { get; set; }
}

public override void OnExtractTranslation(IHttpTranslationExtractionContext context)
{
    try
    {
        var response = JsonConvert.DeserializeObject<TranslationResponse>(context.Response.Data);
        
        if(string.IsNullOrEmpty(response?.translatedText))
        {
            context.Fail("未收到有效翻译结果");
            return;
        }
        
        // 处理批量翻译结果分割
        var translations = response.translatedText.Split('\n');
        if(translations.Length != context.UntranslatedTexts.Length)
        {
            context.Fail("返回的翻译数量与请求不匹配");
            return;
        }
        
        context.Complete(translations);
    }
    catch(Exception ex)
    {
        context.Fail($"解析响应时出错: {ex.Message}");
    }
}

常见问题解决方案

1. 端点未被识别

   • 确保DLL文件放置在正确的Translators目录
   • 验证类是否实现了所有必需的方法
   • 检查配置文件中的Endpoint名称是否与Id属性一致

2. 初始化失败

   • 验证配置文件中是否有对应的配置节
   • 确保URL等必需参数已正确配置

3. 请求构造问题

   • 检查API文档确认请求格式
   • 验证语言代码是否符合API要求

4. 结果解析错误

   • 添加详细的错误日志
   • 考虑API可能返回的不同错误格式

最佳实践建议

1. 完善的错误处理：在所有关键步骤添加错误处理和日志记录

2. 配置灵活性：通过配置文件暴露尽可能多的可调参数

3. 性能优化：对于批量翻译API，合理利用其批量处理能力

4. 兼容性考虑：处理不同游戏环境下可能出现的特殊情况

5. 资源释放：确保网络请求等资源被正确释放

调试技巧

1. 使用日志输出中间结果
2. 在开发阶段降低超时设置以便快速发现问题
3. 使用模拟API服务进行离线测试
4. 逐步验证从配置读取到结果解析的每个环节

通过遵循以上指南，开发者可以创建稳定可靠的自定义翻译端点，扩展XUnity.AutoTranslator的功能，满足各种特定的翻译需求。