Fantastic-admin 官方文档

Appearance

国际化 专业版 ​

INFO

该特性由 Vue I18n 提供技术支持。

如果使用 VSCode 进行开发，推荐安装 i18n Ally Next 扩展。

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

默认语言 ​

点击查看

语言包 ​

框架公共语言包存放在 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' }, 
}

公共子包只负责公共 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' }, 
})

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 的语言包需要进行数据合并，可点击这里查看 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'

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

路由设置 ​

以中文(简体)为例，打开 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 ，后端可根据这一状态信息做动态数据国际化处理。

RTL 模式 ​

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

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

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

关闭国际化 ​

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

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

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

Copyright © 2020-present Fantastic-admin