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）：
- 通过注入的
ISettingsAccess读取账号ID、加密的API Token和模型配置。 - 构造HTTP请求，调用
https://api.cloudflare.com/client/v4/accounts/{account_id}/ai/run/{model}。 - 处理
429 Too Many Requests和503状态码，按Lingarr配置的重试策略退避重试。 - 失败时抛出
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
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考