Lingarr插件开发实战：如何用.NET编写自定义翻译服务插件（附Cloudflare示例）

Lingarr插件开发实战：如何用.NET编写自定义翻译服务插件（附Cloudflare示例）

【免费下载链接】lingarrLingarr is an application that supports both local and SaaS translation services to translate subtitle files into a specified target language. With automated translation options, Lingarr simplifies translating subtitles.项目地址: https://gitcode.com/gh_mirrors/li/lingarr

你是否在使用Lingarr翻译字幕时遇到过这样的困扰：内置的翻译服务不够用，想接入自己公司的AI接口却无从下手？本文将带你进行Lingarr插件开发实战，用.NET编写自定义翻译服务插件。Lingarr是一款支持本地与SaaS翻译服务的开源字幕翻译应用，其灵活的插件机制允许任何人接入新的大模型。我们将以官方Cloudflare示例为蓝本，手把手完成从接口理解、编码实现到部署加载的全流程。

插件机制的核心：接口与清单

在动手写代码之前，先理解Lingarr插件系统的"三件套"：

• 翻译服务实现：实现ITranslationService接口，负责真正调用AI接口翻译文本。
• 插件清单：实现IPluginManifest接口，告诉Lingarr在设置界面展示哪些配置项（如API Key、模型名）。
• 版本声明：通过LingarrPluginApiVersion特性标记插件API版本，宿主会校验主版本号是否匹配。

官方已将这套机制整理成示例，源码位于 samples/CloudflarePlugin/，核心契约定义在 Lingarr.Contracts/Translation/ITranslationService.cs 和 Lingarr.Contracts/Interfaces/Plugins/IPluginManifest.cs。

第一步：搭建.NET类库项目

创建一个 .NET 类库，只需引用Lingarr.Contracts项目即可。参考官方示例的项目文件 samples/CloudflarePlugin/CloudflarePlugin.csproj：

• 目标框架为 .NET 10
• 引用Lingarr.Contracts项目
• 引用Microsoft.Extensions.Logging.Abstractions用于日志

在 samples/CloudflarePlugin/AssemblyInfo.cs 中声明API版本：

[assembly: LingarrPluginApiVersion(1, 0)]

这一行至关重要，缺失或主版本不匹配的DLL会被 PluginLoader 直接跳过。

第二步：实现翻译服务

翻译服务类用[PluginProvider("你的标识")]标记，然后实现ITranslationService的四个成员：

• TranslateAsync：核心翻译方法，接收文本、源语言、目标语言，还可选接收前后字幕行作为上下文。
• GetLanguages：返回支持的语言列表；如果服务没有语言列表接口，返回空即可。
• GetModels：返回可选的模型下拉列表。
• GetLanguagePair：将请求的语言解析为实际语言代码。

Cloudflare示例的实现思路很清晰（见 samples/CloudflarePlugin/CloudflareTranslator.cs）：

1. 通过注入的ISettingsAccess读取账号ID、加密的API Token和模型配置。
2. 构造HTTP请求，调用https://api.cloudflare.com/client/v4/accounts/{account_id}/ai/run/{model}。
3. 处理429 Too Many Requests和503状态码，按Lingarr配置的重试策略退避重试。
4. 失败时抛出TranslationException，让Lingarr统一处理错误提示。

注意：插件标识不能与内置服务冲突，以下为保留标识：anthropic、openai、gemini、deepseek、mistral、xai、localai、deepl、libretranslate、google、bing、microsoft、yandex。

第三步：编写插件清单，自动生成配置界面

清单类的作用是"零前端代码"生成设置表单。它声明了提供者名称、显示名称、描述，以及一个PluginSettingField列表。每个字段包含Key、Label、类型（文本/URL/密钥/远程下拉）、是否必填、默认值和说明。

Cloudflare清单声明了三个字段：Account ID（文本）、API token（密钥类型，会加密存储）、Translation model（文本，默认@cf/meta/m2m100-1.2b），见 samples/CloudflarePlugin/CloudflarePluginManifest.cs。

有了清单，你在设置 > 插件页面就能看到完整的配置表单，无需修改前端代码。

第四步：构建与部署插件

执行以下命令编译：

dotnet build samples/CloudflarePlugin/CloudflarePlugin.csproj -c Release

构建产物中你需要Lingarr.Plugin.Cloudflare.dll和Lingarr.Contracts.dll两个文件。

Lingarr通过环境变量PLUGINS_PATH指定插件目录。以Docker Compose为例：

services: lingarr: image: lingarr/lingarr:latest environment: PLUGINS_PATH: /app/plugins volumes: - ./plugins:/app/plugins

把两个DLL放入./plugins目录并重启Lingarr，看到日志输出类似Loaded plugin ... (1 manifest(s))即加载成功，随后插件会出现在Settings > Plugins中。

实战要点与安全提醒

• 上下文翻译：TranslateAsync的上下文参数可传递前后字幕行，这对依赖上下文的模型（如人名、术语一致性）很有帮助，务必善用。
• 加密存储：API密钥类字段使用Secret类型，并通过GetEncryptedSettingAsync读取，避免明文落盘。
• 错误处理：统一抛出TranslationException（定义在 Lingarr.Contracts/Exceptions/TranslationException.cs），让上层重试与展示逻辑正常工作。
• 安全警示：Lingarr的插件以完整权限运行，没有沙箱隔离，请只加载可信来源的DLL。

写在最后

通过本文的Lingarr插件开发实战，你已经掌握了自定义翻译服务插件的完整链路：理解ITranslationService接口、编写清单驱动配置界面、声明API版本、构建并部署到PLUGINS_PATH目录。无论你想接入企业私有大模型、国产AI服务，还是自建翻译网关，这套模式都完全适用。现在就动手写一个属于你自己的翻译插件吧！🚀

如需获取完整项目，可执行git clone https://gitcode.com/gh_mirrors/li/lingarr查看源码与示例。

【免费下载链接】lingarrLingarr is an application that supports both local and SaaS translation services to translate subtitle files into a specified target language. With automated translation options, Lingarr simplifies translating subtitles.项目地址: https://gitcode.com/gh_mirrors/li/lingarr