---
url: /guide/i18n.md
---
# 国际化 

:::info
该特性由 [Vue I18n](https://vue-i18n.intlify.dev/) 提供技术支持。
:::

如果使用 VSCode 进行开发，推荐安装 [i18n Ally Next](https://marketplace.visualstudio.com/items?itemName=lydanne.i18n-ally-next) 扩展。

由于框架采用 Monorepo 架构，为了更好的隔离性，安装该扩展后需在 VSCode 工作区下使用，打开 `fantastic-admin.code-workspace` 文件，并点击“打开工作区”。

![](/i18n-ally.png){data-zoomable}

## 默认语言

[点击查看](settings/toolbar#默认语言)

## 语言包

框架公共语言包存放在 `packages/locales/lang/app/` 目录下，应用自身的路由和业务语言包存放在 `apps/<app>/src/locales/lang/` 目录下。构建时会先加载公共语言包，再加载应用语言包，因此应用可以按需覆盖公共文案。

### 全局新增

如果希望所有应用都新增一个语言，例如日文，需要在公共子包中补齐公共文案并注册语言信息。

1. 在 `packages/locales/lang/app/**` 下为每个公共文案模块补齐 `ja.json`。
2. 在 `packages/locales/src/index.ts` 的 `defaultLocalesInfo` 中增加语言信息。

```ts
export const defaultLocalesInfo: LocalesInfo = {
  'zh-cn': { label: '中文(简体)', direction: 'ltr' },
  'zh-tw': { label: '中文(繁體)', direction: 'ltr' },
  'en': { label: 'English', direction: 'ltr' },
  'ja': { label: '日本語', direction: 'ltr' }, // [!code ++]
}
```

公共子包只负责公共 `app.*` 文案，应用自身的路由和业务文案仍然需要在对应应用的 `apps/<app>/src/locales/lang/**` 下按需补齐。

### 单个应用新增

如果只有某个应用需要新增一个语言，例如只在 `apps/example` 中支持日文，不需要修改公共子包的 `defaultLocalesInfo`。

1. 在 `apps/<app>/src/locales/lang/route/ja.json` 中补齐路由文案。
2. 如果该应用需要业务文案，在 `apps/<app>/src/locales/lang/**` 下补齐对应 `ja.json`。
3. 如果公共子包没有该语言的 `app.*` 文案，则在 `apps/<app>/src/locales/lang/app/**` 下按需补齐该应用使用到的 `app.*` key。
4. 在 `apps/<app>/src/locales/index.ts` 里通过 `createLocalesInfo()` 第二个参数扩展语言信息。

```ts
const localesInfo = createLocalesInfo(messages, {
  ja: { label: '日本語', direction: 'ltr' }, // [!code ++]
})
```

`createLocalesInfo()` 的第二个参数会扩展语言清单；如果语言已存在则覆盖 `label` / `direction`，如果不存在则新增。

### 单个应用替换默认语言的 key

如果只是某个应用想替换默认语言里的公共文案，只需在应用侧创建同名语言文件和同名 key 即可。

例如要在 `apps/example` 中替换简体中文的登录文案，可以添加 `apps/<app>/src/locales/lang/app/route/zh-cn.json`：

```json
{
  "app": {
    "route": {
      "login": "账号登录"
    }
  }
}
```

应用语言包会在公共语言包之后加载，所以应用侧同名 key 会覆盖 `packages/locales/lang/app/**` 中的默认文案。

***

如果你新增了一个语言，并且应用使用了三方 UI 组件库，例如 Element Plus 。因为 Element Plus 本身也有自己的语言包，所以在做国际化支持的时候，框架的语言包和 Element Plus 的语言包需要进行数据合并，可[点击这里](https://github.com/element-plus/element-plus/tree/dev/packages/locale/lang)查看 Element Plus 的语言包文件。

假设你已经新增并配置好了日文语言包 `ja.json` ，然后你需要到 `apps/<app>/src/ui/provider/index.ts` 文件里做以下调整：

```ts
import zhCN from 'element-plus/es/locale/lang/zh-cn.mjs'
import zhTW from 'element-plus/es/locale/lang/zh-tw.mjs'
import en from 'element-plus/es/locale/lang/en.mjs'
import ja from 'element-plus/es/locale/lang/ja.mjs' // [!code ++]

// 语言代码需与 apps/<app>/src/locales/index.ts 导出的 localesInfo 保持一致
const locales: Record<string, any> = {
  'zh-cn': zhCN,
  'zh-tw': zhTW,
  'en': en,
  'ja': ja // [!code ++]
}
```

## 路由设置

以中文(简体)为例，打开 `apps/<app>/src/locales/lang/route/zh-cn.json` 文件可以看到路由相关的配置，在 `route` 对象里可以扩展需要开启国际化支持的路由。

```json
{
  "route": {
    "page": "页面标题",
  }
}
```

如果需要新增某个路由的国际化支持，光设置好中文(简体)的还不行，其它语言包文件里也要同步添加。当都设置好后，可在该路由的 `title` 参数上直接设置对应 key 值，例如：

```ts
meta: {
  title: 'route.page',
},
```

## 框架设置

以中文(简体)为例，框架公共语言信息已按模块拆分在 `packages/locales/lang/app/` 目录下，例如路由基础文案位于 `packages/locales/lang/app/route/zh-cn.json`，布局和组件文案则按对应模块目录维护。如果某个应用需要覆盖公共文案，可以在 `apps/<app>/src/locales/lang/app/` 下添加同名 key。

## 单页组件

如果每个页面都要做国际化支持，那语言包文件就会变得无比庞大且难以维护，推荐在每个页面组件里使用 `<i18n>` 自定义块进行语言维护，可访问 `apps/example/src/views/feature_example/i18n.vue` 查看示例。

## 与服务端交互

所有的请求均会在请求头里带上 [`Accept-Language`](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Headers/Accept-Language) ，后端可根据这一状态信息做动态数据国际化处理。

## RTL 模式

文字阅读方向由语言信息决定（例如阿拉伯文），所以可以在 `apps/<app>/src/locales/index.ts` 的 `localesInfo` 中为对应语言设置 `direction: 'rtl'` 。

这里作为演示，将中文改为 RTL 模式：

```ts
const localesInfo = createLocalesInfo(messages, {
  'zh-cn': { label: '中文(简体)', direction: 'rtl' },
})
```

![](/i18n-rtl.png){data-zoomable}

## 关闭国际化

如果不想开启国际化，可以关闭语言选择器，并设置默认语言为中文(简体)。

```ts twoslash
import { setSettings } from '@fantastic-admin/settings'

export default setSettings({
  toolbar: {
    i18n: {
      enable: false,
      defaultLang: 'zh-cn',
    },
  },
})
```