# 9.17 国际化（i18n）

:::danger 功能未实现
本章描述的国际化（i18n）方案为规划中的功能，核心依赖（`locales/` 目录、`LangSwitch` 组件、`locale` Store）尚未在项目中实现。请勿按本文档操作，等待后续版本发布。
:::

:::tip 概述
本节介绍前端项目的国际化方案，基于 vue-i18n 实现多语言切换。项目默认提供中文和英文两种语言，可按需扩展其他语言。
:::

## 技术方案

| 项目 | 说明 |
|------|------|
| 插件 | vue-i18n v9 |
| 默认语言 | 中文（zh-CN） |
| 支持语言 | zh-CN、en-US |
| 存储位置 | localStorage（持久化用户选择） |

## 目录结构

:::warning 下列目录尚未创建
`ui/src/locales/` 目录当前不存在，以下为规划结构。
:::

```text
ui/src/
├── locales/
│   ├── index.ts           # i18n 初始化配置
│   ├── lang/
│   │   ├── zh-CN.ts       # 中文语言包
│   │   └── en-US.ts       # 英文语言包
│   └── helper.ts          # 语言切换辅助函数
```

## 语言包结构

:::warning 下列文件尚不存在
`ui/src/locales/lang/zh-CN.ts` 当前不存在，以下为规划示例。
:::

```typescript
// ui/src/locales/lang/zh-CN.ts
export default {
  common: {
    search: '搜索',
    reset: '重置',
    add: '新增',
    edit: '编辑',
    delete: '删除',
    export: '导出',
    import: '导入',
    confirm: '确认',
    cancel: '取消',
    success: '操作成功',
    failed: '操作失败',
  },
  table: {
    id: 'ID',
    name: '名称',
    status: '状态',
    createTime: '创建时间',
    action: '操作',
  },
  login: {
    username: '用户名',
    password: '密码',
    captcha: '验证码',
    submit: '登录',
    rememberMe: '记住我',
  },
};
```

## 使用方式

### 模板中使用

```vue
<template>
  <div>
    <!-- 基础翻译 -->
    <el-button>{{ $t('common.search') }}</el-button>
    <el-button>{{ $t('common.reset') }}</el-button>

    <!-- 带参数翻译 -->
    <p>{{ $t('message.welcome', { name: 'Admin' }) }}</p>
  </div>
</template>
```

### Script 中使用

```vue
<script setup lang="ts">
import { useI18n } from 'vue-i18n';

const { t, locale } = useI18n();

// 翻译
const searchText = t('common.search');

// 切换语言
const switchLang = (lang: string) => {
  locale.value = lang;
  localStorage.setItem('lang', lang);
};
</script>
```

### 列定义中使用

```vue
<script setup lang="ts">
import { useI18n } from 'vue-i18n';

const { t } = useI18n();

const columns = computed(() => [
  { title: t('table.id'), field: 'id', width: 80 },
  { title: t('table.name'), field: 'name' },
  { title: t('table.status'), field: 'statusText', width: 100 },
  { title: t('table.createTime'), field: 'createTime', width: 180 },
]);
</script>
```

## 语言切换组件

:::warning 下列组件和 Store 尚不存在
`ui/src/components/LangSwitch/` 和 `ui/src/store/modules/locale.ts` 当前不存在，以下为规划示例。
:::

```vue
<!-- ui/src/components/LangSwitch/index.vue -->
<template>
  <el-dropdown @command="switchLang">
    <el-button :icon="Icon" circle />
    <template #dropdown>
      <el-dropdown-menu>
        <el-dropdown-item command="zh-CN">中文</el-dropdown-item>
        <el-dropdown-item command="en-US">English</el-dropdown-item>
      </el-dropdown-menu>
    </template>
  </el-dropdown>
</template>

<script setup lang="ts">
import { useI18n } from 'vue-i18n';
import { useLocaleStore } from '@/store/modules/locale';

const { locale } = useI18n();
const localeStore = useLocaleStore();

const switchLang = (lang: string) => {
  locale.value = lang;
  localeStore.setLocale(lang);
};
</script>
```

## 后端消息国际化

后端错误消息也可支持国际化，通过请求头 `Accept-Language` 判断语言：

:::warning 下列中间件尚不存在
`app/middleware/LangMiddleware.php` 当前不存在，以下为规划示例。
:::

```php
// app/middleware/LangMiddleware.php
public function handle(Request $request, \Closure $next): Response
{
    $lang = $request->header('Accept-Language', 'zh-CN');
    app()->setLang($lang);
    return $next($request);
}
```

## 添加新语言

:::warning 以下步骤依赖未实现的功能
`ui/src/locales/` 目录尚不存在，请勿执行以下操作。
:::

1. 创建语言包文件 `ui/src/locales/lang/ja-JP.ts`
2. 复制中文语言包结构并翻译
3. 在 `ui/src/locales/index.ts` 中注册新语言
4. 在语言切换组件中添加选项

```typescript
// ui/src/locales/index.ts
import zhCN from './lang/zh-CN';
import enUS from './lang/en-US';
import jaJP from './lang/ja-JP';  // 新增

const messages = {
  'zh-CN': zhCN,
  'en-US': enUS,
  'ja-JP': jaJP,  // 新增
};
```

## 相关文档

- [前端概述](/zh/frontend/overview.html)
- [状态管理](/zh/frontend/store.html)
- [环境配置](/zh/frontend/env-config.html)