# WCS 国际化语言包说明

## 读取位置

当前实现有两层语言包来源：

1. 内置语言包

```text
classpath:/i18n/<locale>/
```

也就是仓库里的：

```text
src/main/resources/i18n/<locale>/
```

这一层是项目自带的默认语言包，保证系统开箱可用。

2. 外置语言包

```text
./stock/out/wcs/i18n/<locale>/
```

这一层是运行时可安装、可替换、可覆盖的语言包目录，对应 `application.yml` 里的 `app.i18n.pack-path`。

实际加载顺序：

1. 先读内置语言包
2. 再读外置语言包
3. 外置语言包同名 key 会覆盖内置值

当前已配置语言：

- `zh-CN`
- `en-US`

外置目录示例：

```text
stock/out/wcs/i18n/
  en-US/
    messages.properties
    legacy.properties
  zh-CN/
    messages.properties
    legacy.properties
```

## 文件用途

### `messages.properties`

用于稳定的 key 形式国际化。

适合以下内容：

- 菜单名称
- 页面标题
- 对话框标题
- 按钮文案
- 状态名称
- 新增功能文案

### `legacy.properties`

用于旧页面的纯文本兼容替换。

这个项目里老的 Layui/jQuery 页面很多，存在大量直接写死的中文；这层是过渡方案，便于先让英文可用，再逐步把旧页面改成 key 化。

## key 规则

### 菜单 / 资源 key

后端菜单翻译 key 由 `sys_resource.code` 推导。

例如：

```properties
resource.develop=Development
resource.ai.llm_config=AI Configuration
resource.notifyReport.notifyReport=Notification Report
resource.ai.llm_config.view=View
```

### 权限 key

权限翻译 key 由 `action` 推导。

例如：

```properties
permission.function=Specified Functions
permission.user.resetPassword=Reset Password
```

### 通用 UI key

例如：

```properties
common.profile=Profile
common.logout=Log Out
index.homeTab=Control Center
login.title=WCS System V3.0
```

## 安装语言包

如果只是使用项目自带中文和英文，不需要额外操作。

如果要安装外置语言包，按下面做：

1. 在 `stock/out/wcs/i18n/` 下创建新语言目录。
2. 从现有语言包复制 `messages.properties` 和 `legacy.properties` 作为模板。
3. 只翻译 value，不要改 key。
4. 刷新页面，或重启服务。

系统会按配置周期检查外置目录，因此简单文本调整理论上不必重启；但正式环境建议仍按发布流程重启或重载。

## 推荐维护方式

1. 新增页面和新增接口文案，优先写入 `messages.properties`。
2. 老页面先通过 `legacy.properties` 兼容，不要一开始就全量重构。
3. 某个老页面重构时，再把它的纯文本逐步迁移到显式 key。

## 说明

- 默认语言是 `zh-CN`
- 前端请求会自动携带 `X-Lang`
- 登录页和首页都已经支持语言切换
- 非默认语言如果缺少菜单 key，后端会先尝试根据 `resource.code` 自动生成可读名称，再回退到原始中文名