基本介绍
源码插件通过services.I18n()获取运行时翻译能力。该能力读取宿主已经加载的翻译目录，并根据当前请求语言返回本地化文本。
动态插件需要注意：hostServices目录没有i18n服务。动态插件可以随插件包交付manifest/i18n资源，但资源的发现、合并、缓存、失效和前端运行时分发都由宿主管理。动态插件后端不应直接读取、合并或翻译自身语言包，也不应在plugin.yaml中声明service: i18n。
能力阶段：运行期
类型支持：源码插件
能力设计
翻译目录与插件资源的关系
I18nService消费的是宿主运行时翻译目录；插件manifest/i18n是静态交付资源。两者职责不同：
| 内容 | 作用 |
|---|---|
I18nService | 源码插件查询已经加载并参与运行时解析的翻译文本 |
manifest/i18n | 源码插件和动态插件交付语言资源，由宿主资源管线统一发现和合并 |
动态插件不需要通过manifest.get读取语言包来完成运行时翻译。读取语言包文件不等于注册翻译，翻译资源在安装、升级或运行时如何被加载，由宿主插件资源管线负责。
翻译回退机制
Translate的回退文本很重要。翻译目录未命中时，宿主会返回回退文本，确保通知、日志和页面提示仍然可读。插件业务文案、通知标题和审计文本应使用稳定键，并提供可读回退文本。
搜索能力定位
FindMessageKeys适合日志筛选、接口文档筛选等管理端场景，不应用于高频请求路径。
接口定义
源码插件接口
| 方法 | 说明 |
|---|---|
GetLocale | 返回当前请求的有效语言 |
Translate | 根据翻译键和回退文本返回本地化文本 |
FindMessageKeys | 在指定前缀下按本地化文本关键词搜索翻译键 |
动态插件接口
动态hostServices目录没有发布独立i18n服务。动态插件的国际化边界如下：
| 需求 | 处理方式 |
|---|---|
| 交付插件语言资源 | 将资源放入manifest/i18n/<locale>/，由宿主资源管线加载 |
| 返回可本地化业务结果 | 返回稳定messageKey、messageParams和英文fallback，或返回原始业务数据 |
| 运行时翻译和语言切换 | 由宿主错误治理、前端运行时语言包或宿主统一展示层完成 |
能力使用
源码插件使用
源码插件通过services.I18n()进行运行时翻译：
// 获取当前请求语言
locale := services.I18n().GetLocale(ctx)
// 按翻译键返回本地化文本
text := services.I18n().Translate(ctx, "plugin.reports.export.success", "导出成功")
// 搜索翻译键
keys := services.I18n().FindMessageKeys(ctx, "plugin.reports", "导出")
动态插件使用
动态插件不应在plugin.yaml中声明不存在的service: i18n，也不应读取manifest/i18n后自行翻译。后端可以返回稳定消息键、参数和回退文本：
type ExportResult struct {
MessageKey string `json:"messageKey"`
MessageParams map[string]any `json:"messageParams"`
Fallback string `json:"fallback"`
}
return &ExportResult{
MessageKey: "plugin.reports.export.success",
MessageParams: map[string]any{"count": 12},
Fallback: "Export completed",
}, nil
最终展示文案由宿主错误治理、前端运行时语言包或宿主统一展示层完成。
设计约束
- 源码插件使用
services.I18n()。 这是当前发布的运行时翻译入口。 - 动态插件不声明
i18n服务。 最新pluginbridge/protocol.HostServiceDescriptors()没有发布该服务。 - 动态插件不自行处理语言包。
manifest/i18n资源由宿主统一加载和分发，动态插件后端返回消息键、参数、回退文本或原始业务数据。 - 翻译键应稳定。 插件业务文案、通知标题和审计文本应使用稳定键，并提供可读回退文本。
- 搜索能力用于管理端筛选。
FindMessageKeys适合日志筛选、接口文档筛选等场景，不应用于高频请求路径。