翻译引擎（TranslationEngine）

通过实现 TranslationEngine 接口，可以为 MT 管理器的翻译模式和文本输入框增加翻译功能。

快速开始

public class TranslationEngineDemo extends BaseTranslationEngine {

    @Override
    protected void onBuildConfiguration(ConfigurationBuilder builder) {
        super.onBuildConfiguration(builder);
        builder.setForceNotToSkipTranslated(true);
    }

    @NonNull
    @Override
    public String name() {
        return "{case_conversion}";
    }

    @NonNull
    @Override
    public List<String> loadSourceLanguages() {
        return List.of("src");
    }

    @NonNull
    @Override
    public List<String> loadTargetLanguages(String sourceLanguage) {
        return List.of("upper", "lower");
    }

    @NonNull
    @Override
    public String getLanguageDisplayName(String language) {
        return switch (language) {
            case "src" -> "原文";
            case "upper" -> "大写";
            case "lower" -> "小写";
            default -> "???";
        };
    }

    @NonNull
    @Override
    public String translate(String text, String sourceLanguage, String targetLanguage) {
        return targetLanguage.equals("upper") ? text.toUpperCase() : text.toLowerCase();
    }
}

接口概览

TranslationEngine 接口

方法	说明
void init(PluginContext context)	初始化翻译引擎
PluginContext getContext()	获取插件上下文
String name()	获取翻译引擎名称
Configuration getConfiguration()	获取配置信息
List<String> loadSourceLanguages()	加载源语言列表
List<String> loadTargetLanguages(String sourceLanguage)	加载目标语言列表
String getLanguageDisplayName(String language)	将语言代码转换为显示名称
void beforeStart()	翻译开始前回调（UI线程）
void onStart()	翻译开始回调（子线程）
String translate(String text, String sourceLanguage, String targetLanguage)	执行翻译（子线程）
void onFinish()	翻译结束回调（子线程）
void afterFinish()	翻译结束后回调（UI线程）
boolean onError(Exception e)	错误处理回调（UI线程）

BaseTranslationEngine 基类

BaseTranslationEngine 提供了 TranslationEngine 的默认实现：

• 自动管理 PluginContext
• 提供可重写的 init()（无参）
• 提供可重写的 onBuildConfiguration(...)
• 默认使用 MT 内置语言名称实现 getLanguageDisplayName(...)
• 生命周期方法提供空实现
• 默认将 autoRepairFormatSpecifiersError 设为 true（仅无参构造）

BaseTranslationEngine 的构造方式：

• BaseTranslationEngine()：先调用 onBuildConfiguration(builder) 再构建配置
• BaseTranslationEngine(Configuration configuration)：直接使用传入配置，不调用 onBuildConfiguration(...)

生命周期

TranslationEngine 生命周期如下：

1. init(PluginContext)（每个引擎实例仅一次）
2. beforeStart()（UI线程）
3. onStart()（子线程）
4. translate(...)（子线程，可多次）
5. onFinish()（子线程）
6. afterFinish()（UI线程）

如果 translate(...) 抛出异常，将调用 onError(...)，且不会再调用 onFinish()、afterFinish()。

详细说明

init

void init(PluginContext context)

初始化翻译引擎。每个实例只会调用一次。

name

@NonNull
String name()

引擎显示名称。支持 {key} 本地化键，详见 本地化文本。

translate

@NonNull
String translate(String text, String sourceLanguage, String targetLanguage) throws IOException

执行单文本翻译。

• text：待翻译文本
• sourceLanguage：源语言代码
• targetLanguage：目标语言代码
• 返回值：翻译结果（不能为 null）
• 异常：网络/IO 错误可抛出 IOException

onBuildConfiguration（BaseTranslationEngine）

protected void onBuildConfiguration(ConfigurationBuilder builder)

仅在 BaseTranslationEngine()（无参构造）中调用，用于统一配置项。默认实现会执行：

builder.setAutoRepairFormatSpecifiersError(true);

init（BaseTranslationEngine）

protected void init()

BaseTranslationEngine#init(PluginContext) 会先保存上下文，再调用此无参方法。子类可在这里完成初始化。

配置选项

通过 TranslationEngine.ConfigurationBuilder 构建配置：

Configuration config = new ConfigurationBuilder()
        .setAllowBatchTranslationBySeparator(true)
        .setMaxTranslationTextLength(4000)
        .setAcceptTranslated(false)
        .build();

配置字段

字段	默认值	说明
maxTranslationTextLength	0	单次翻译最大文本长度。<= 0 表示无限制
allowBatchTranslationBySeparator	false	翻译模式是否允许分隔线批量合并
acceptTranslated	false	是否允许把已翻译文本作为下一次输入
forceNotToSkipTranslated	false	是否强制不跳过已翻译词条
targetLanguageMutable	false	目标语言列表是否随源语言变化
autoRepairFormatSpecifiersError	false	是否自动修复 %s 等格式化占位符误译
disableAutoHideLanguage	false	是否禁用语言自动隐藏

注意：以上是 ConfigurationBuilder 的默认值。若继承 BaseTranslationEngine 并使用无参构造，autoRepairFormatSpecifiersError 默认会被设为 true。

setMaxTranslationTextLength

ConfigurationBuilder setMaxTranslationTextLength(int maxTranslationTextLength)

设置单次翻译最大长度，超长文本会自动拆分并拼接回填。

方法名是 setMaxTranslationTextLength(...)，对应字段是 maxTranslationTextLength。

setAllowBatchTranslationBySeparator

ConfigurationBuilder setAllowBatchTranslationBySeparator(boolean allowBatchTranslationBySeparator)

在翻译模式中启用“分隔线批量翻译”优化。

setAcceptTranslated

ConfigurationBuilder setAcceptTranslated(boolean acceptTranslated)

为 true 时，二次翻译可能使用“已翻译文本”作为输入；false 时始终用原文。

setForceNotToSkipTranslated

ConfigurationBuilder setForceNotToSkipTranslated(boolean forceNotToSkipTranslated)

启用后，翻译模式中的“跳过已翻译”选项会被隐藏。

setTargetLanguageMutable

ConfigurationBuilder setTargetLanguageMutable(boolean targetLanguageMutable)

启用后，源语言切换时会重新调用 loadTargetLanguages(sourceLanguage)。

setAutoRepairFormatSpecifiersError

ConfigurationBuilder setAutoRepairFormatSpecifiersError(boolean autoRepairFormatSpecifiersError)

自动修复常见格式化占位符误译（例如 %s 被翻译成 ％S）。

setAutoRepairFormatControlError（已弃用）

@Deprecated
ConfigurationBuilder setAutoRepairFormatControlError(boolean autoRepairFormatSpecifiersError)

已弃用，建议改用 setAutoRepairFormatSpecifiersError(...)。

setDisableAutoHideLanguage

ConfigurationBuilder setDisableAutoHideLanguage(boolean disableAutoHideLanguage)

设置是否禁用语言自动隐藏功能。

批量优化与超长文本拆分

分隔线批量翻译（allowBatchTranslationBySeparator = true）

在翻译模式中，MT 会把多个词条拼接成一个字符串，通过一次 translate(...) 调用降低网络往返。

超长文本拆分（maxTranslationTextLength > 0）

当单条文本超过长度上限时，MT 会自动按边界拆分后逐段调用 translate(...)，再按顺序拼接：

在分隔线批量模式下，超长词条会先独立拆分翻译，普通词条仍按批量方式合并，最后回填到原顺序。

完整示例

public class OnlineTranslationEngine extends BaseTranslationEngine {

    private OkHttpClient httpClient;

    @Override
    protected void init() {
        httpClient = new OkHttpClient.Builder().build();
    }

    @Override
    protected void onBuildConfiguration(ConfigurationBuilder builder) {
        super.onBuildConfiguration(builder);
        builder.setAllowBatchTranslationBySeparator(true);
        builder.setMaxTranslationTextLength(4000);
        builder.setTargetLanguageMutable(true);
    }

    @NonNull
    @Override
    public String name() {
        return "在线翻译";
    }

    @NonNull
    @Override
    public List<String> loadSourceLanguages() {
        return List.of("auto", "en", "zh-CN", "ja", "ko");
    }

    @NonNull
    @Override
    public List<String> loadTargetLanguages(String sourceLanguage) {
        return List.of("en", "zh-CN", "ja", "ko");
    }

    @NonNull
    @Override
    public String translate(String text, String sourceLanguage, String targetLanguage) throws IOException {
        Request request = new Request.Builder()
                .url("https://api.example.com/translate?text=" + text
                        + "&from=" + sourceLanguage
                        + "&to=" + targetLanguage)
                .build();

        try (Response response = httpClient.newCall(request).execute()) {
            if (!response.isSuccessful()) {
                throw new IOException("翻译请求失败: " + response.code());
            }
            return response.body().string();
        }
    }

    @Override
    public boolean onError(Exception e) {
        if (e instanceof IOException) {
            getContext().showToastL("网络错误：" + e.getMessage());
            return true;
        }
        return false;
    }
}

接口注册

所有翻译引擎实现都需要在模块的 build.gradle 中注册：

mtPlugin {
    pluginID = "com.example.myplugin"
    versionCode = 1
    versionName = "v1.0"
    name = "翻译插件"

    interfaces = [
        "com.example.myplugin.TranslationEngineDemo",
        "com.example.myplugin.OnlineTranslationEngine",
    ]
}

相关接口

• PluginContext - 插件上下文
• LocalString - 本地化文本