基本介绍
LinaPro的国际化能力由主框架统一加载和合并。主框架提供基础语言包，源码插件提供插件自己的语言包，动态插件发布产物可以携带语言资源。启用插件后，主框架会把可用资源合并成运行时语言目录，供管理工作台、菜单、错误信息、插件页面和接口文档使用。
当前主仓库默认提供zh-CN和en-US两套语言资源。其他语言需要项目团队自行创建和维护。
配置入口
国际化配置位于config.yaml：
i18n:
default: zh-CN
enabled: true
locales:
- locale: en-US
nativeName: English
- locale: zh-CN
nativeName: 简体中文
| 配置项 | 说明 |
|---|---|
default | 请求未携带语言标识或语言不受支持时使用的默认语言 |
enabled | 是否启用多语言能力；关闭后前端隐藏语言切换入口 |
locales | 运行时可选语言列表和展示名称 |
locales不仅影响前端语言切换菜单，也决定运行时哪些语言资源应被完整维护。
资源布局
主框架语言资源位于：
apps/lina-core/manifest/i18n/<locale>/
典型结构如下：
manifest/i18n/
├── zh-CN/
│ ├── framework.json
│ ├── menu.json
│ ├── dict.json
│ ├── config.json
│ ├── error.json
│ ├── job.json
│ ├── notify.json
│ ├── role.json
│ ├── plugin.json
│ ├── public-frontend.json
│ └── apidoc/
│ ├── common.json
│ └── core-api-*.json
└── en-US/
└── ...
直接位于<locale>/下的JSON文件用于运行时界面文案，apidoc/下的JSON文件用于接口文档翻译。两类资源分开加载，避免接口文档资源污染运行时界面文案。
语言包格式
语言包使用JSON格式，可以使用嵌套结构，也可以使用扁平点分隔键：
{
"menu": {
"dashboard": {
"title": "工作台"
}
},
"framework": {
"description": "面向可持续交付的 AI 原生全栈框架"
}
}
等价扁平键：
{
"menu.dashboard.title": "工作台",
"framework.description": "面向可持续交付的 AI 原生全栈框架"
}
加载后会规范化为扁平键。为了减少冲突，插件语言包应放在插件自己的命名空间下。
插件国际化
源码插件在自己的manifest/i18n/目录维护语言包：
apps/lina-plugins/content-notice/manifest/i18n/
├── zh-CN/
│ ├── content-notice.json
│ └── apidoc/
│ └── plugin-api-notice.json
└── en-US/
└── content-notice.json
插件语言包建议使用plugins.<plugin-id>.命名空间：
{
"plugins": {
"content-notice": {
"notice": {
"title": "通知公告",
"status": {
"draft": "草稿",
"published": "已发布"
}
}
}
}
}
动态插件的语言资源随发布产物携带。主框架加载有效发布版本时，会把这些资源作为插件资源参与合并，插件禁用或升级后再随运行时快照变化。
接口文档翻译
接口文档翻译放在manifest/i18n/<locale>/apidoc/下。主框架和插件都可以维护自己的apidoc资源：
manifest/i18n/zh-CN/apidoc/core-api-auth.json
manifest/i18n/zh-CN/apidoc/common.json
manifest/i18n/zh-CN/apidoc/plugin-api-notice.json
接口文档翻译使用结构化键，不建议使用展示文本作为键。插件翻译只维护自己的插件命名空间，主框架翻译只维护核心接口命名空间。
en-US接口文档资源通常可以保持为空占位，让源码中的英文summary、dc和字段说明作为默认文案。中文等非英文语言应补齐翻译，保证工作台开发中心可读。
语言选择
运行时语言选择通常来自请求头、查询参数或前端保存的用户偏好。具体调用路径由工作台和主框架中间件协作完成。请求语言不存在或未配置时，主框架回退到i18n.default。
当i18n.enabled: false时，前端隐藏语言切换入口，主框架仍使用默认语言加载必要文案。
添加新语言
添加新语言通常需要四步：
- 在
config.yaml的i18n.locales中加入语言代码和原生名称。 - 在
apps/lina-core/manifest/i18n/<locale>/下创建主框架语言包。 - 为所有启用插件补齐
manifest/i18n/<locale>/语言包。 - 如需接口文档本地化，补齐
manifest/i18n/<locale>/apidoc/资源。
示例：
i18n:
locales:
- locale: ja-JP
nativeName: 日本語
创建目录：
mkdir -p apps/lina-core/manifest/i18n/ja-JP/apidoc
LinaPro不会自动生成新增语言的翻译内容。缺失翻译会回退到默认文案或显示未翻译键，具体表现取决于调用位置。
缓存与刷新
运行时语言资源会被缓存。开发环境修改语言包后，重启服务最直接：
make dev
生产环境应使用运行时缓存失效能力，按最小范围刷新：
| 范围 | 说明 |
|---|---|
| 指定语言 | 只刷新某个locale |
| 指定插件 | 只刷新某个插件的语言资源 |
| 主框架资源 | 只刷新主框架语言包 |
| 接口文档资源 | 只刷新apidoc翻译目录 |
不建议无理由清空所有语言和所有插件缓存。全量刷新会造成短暂的翻译抖动，也会增加下一次请求的加载成本。
语言代码
LinaPro使用标准IETF BCP 47语言代码。常见示例：
| 语言 | 代码 |
|---|---|
| 简体中文 | zh-CN |
| 繁體中文 | zh-TW |
| 英文 | en-US |
| 日文 | ja-JP |
| 韩文 | ko-KR |
目录名、config.yaml中的locale字段和前端请求中的语言参数应保持一致。