@wakeadmin/i18n #

B 端多语言基于 Vue i18n, @wakeadmin/i18n 负责按照我们定义的多语言使用规范，进一步封装：

• 支持语言包按需加载
• 统一多语言识别和切换
• 统一语言标识符
• ...

安装 #

Vue 2.x 版本

$ pnpm add @wakeadmin/i18n-legacy 'vue-i18n@8.*'
$ pnpm add @wakeadmin/vue-cli-plugin-i18n -D # 语言包解析和合并支持

Vue 3.x 版本

$ pnpm add @wakeadmin/i18n vue-i18n
$ pnpm add @wakeadmin/vue-cli-plugin-i18n -D # 语言包解析和合并支持

创建 i18n 实例 #

使用 createI18n 方法创建实例：

// i18n.ts
import { createI18n } from '@wakeadmin/i18n'; // vue 2 对应 @wakeadmin/i18n-legacy

export default createI18n();

createI18n 支持的参数参考 vue-i18n。大部分场景你可以不用传，按照我们规定的默认参数就行了:

• locale：会从 localStorage#__i18n__ 中读取, 如果未配置则使用 navigator.language
• fallbackLocale: zh
• datetimeFormats、numberFormats 参见代码
• localCache: false, 是否开启本地语言包缓存，默认关闭

export interface I18nInstance {
  /**
   * vue 插件安装
   * @param app
   */
  install(app: VueApp): void;

  i18n: VueI18nInstance;
  /**
   * 可以用于监听 i18n 的相关事件
   */
  eventBus: EventEmitter;

  /**
   * 当前语言检查、持久化
   */
  detect: LocaleDetector;

  /**
   * 语言标识符映射
   */
  localeMapper: (locale: string) => string;

  /**
   * 设置语言
   */
  setLocale(locale: string): string;

  /**
   * 获取当前语言
   */
  getLocale(): string;

  /**
   * 获取回退语言链
   */
  getFallbackLocaleChain(locale?: string, fallback?: FallbackLocale): string[];

  /**
   * 注册语言包
   * @param bundles
   */
  registerBundles(bundles: { [locale: string]: I18nBundle }): Promise<void>;
}

接下来初始化：

import { createApp } from 'vue';
import { createI18n } from '@wakeadmin/i18n';
import App from './Root.vue';

const i18n = createI18n();
const app = createApp(App);

app.use(i18n);

app.mount('#app');

import VueI18n from 'vue-i18n';
import Vue from 'vue';
import { createI18n } from '@wakeadmin/i18n-legacy';

// 首先 use vue-i18
Vue.use(VueI18n);

const { i18n } = createI18n();

new Vue({ i18n }).$mount('#app');

统一语言标识符 #

统一语言标识符指的：是我们要使用统一的命名来定义当前语言、语言包的命名。避免出现不一致的问题，比如 zh-CN、zh-Hans、 zh 都可以表示简体中文，如果不加以规范，就会比较凌乱，难以维护。

当前惟客支持以下四种'语言':

• en 英文
• zh 中文
• zh-Hant 繁体
• th 泰文

/**
 * 默认语言映射
 */
export const DEFAULT_MAPPER: LocaleMapper = {
  'zh-CN': 'zh',
  'zh-TW': 'zh-Hant',
  'zh-HK': 'zh-Hant',
  'zh-MO': 'zh-Hant',
};

注册语言包 #

使用 registerBundles 方法注册。

/**
 * 异步语言包
 */
export type I18nAsyncBundle = () => Promise<{ default: Record<string, any> }>;

/**
 * 语言包类型
 * 支持 url、异步模块、语言包
 */
export type I18nBundle = Record<string, any> | I18nAsyncBundle | I18nAsyncBundle[] | string | string[];

async function registerBundles(bundles: { [locale: string]: I18nBundle }, layer: number = 10): Promise<void>;

registerBundles 接受两个参数:

• bundles: 语言包对象。key 为 语言标识符, 值为语言包, 见下文 语言包类型
• layer: 语言包的优先级。layer 的值必须大于 0， 值越小优先级越高，默认为 10。比如后端配置的语言包, 可以比硬编码在代码中的语言包优先级要高，从而支持后端覆盖的效果

语言包类型 #

• 语言包对象:

  registerBundles({
    zh: {
      hello: '你好',
    },
    en: {
      hello: 'Hello',
    },
  });
  

• 异步模块：适用于比较大的语言包，可以根据当前语言按需加载

  registerBundles({
    zh: () => import('./zh.tr'),
    en: () => import('./en.tr'),
  });
  

• URL 远程语言包

  registerBundles({
    zh: 'http://example.com/i18n/zh.tr',
    en: 'http://example.com/i18n/en.tr',
  });
  

公共 API #

• getGlobalI18n(): VueI18n 获取全局的 vue-i18n 实例
• getLocale(): string 获取当前语言
• setLocale(locale: string) 设置当前语言