H5多语言方案—基于 vue-i18n

258 阅读4分钟

Vue+i18n

1. 基本概念

Vue I18n是一个基于Vue.js的国际化插件,它允许开发者在Vue应用中轻松实现多语言支持。通过Vue I18n,开发者可以将应用中的文本内容抽象为语言包,然后根据用户的语言偏好动态加载相应的语言包。这样,应用就可以根据不同的语言环境显示不同的文本内容。Vue 官方推荐使用 vue-i18n 插件进行国际化实现。本篇文档总结 Vue + vue-i18n 在 H5 多语言方案中的功能和应用。

2. 工作原理

Vue I18n的工作原理主要基于Vue的响应式系统和插件机制。它首先会扫描Vue组件中的文本内容,并将其标记为可翻译的文本。然后,Vue I18n会根据当前的语言环境,从相应的语言包中查找对应的翻译文本,并将其替换到组件中。由于Vue的响应式系统,当语言环境发生变化时,Vue I18n会自动更新组件中的文本内容,保持与语言环境的同步。

3. vue-i18n 基本功能

3.1. 多语言配置
  • 定义语言包:通过 messages 对象定义不同语言的文本。
  • 默认语言:可以设置默认显示的语言。
  • 备用语言:当当前语言中未找到某个翻译时,可以回退到备用语言。

示例代码:

const i18n = new VueI18n({
  locale: 'en', // 默认语言
  fallbackLocale: 'en', // 备用语言
  messages: {
    en: { hello: 'Hello' },
    zh: { hello: '你好' },
  },
});
3.2. 文本渲染

vue-i18n 提供了 $t 方法来获取对应语言的翻译文本。

<template>
  <div>{{ $t('hello') }}</div>
</template>
// en: Hello / zh: 你好
3.3. 动态切换语言

可以通过修改 this.$i18n.locale 来动态切换语言。

<template>
  <div>
    <p>{{ $t('hello') }}</p>
    <button @click="changeLang('en')">English</button>
    <button @click="changeLang('zh')">中文</button>
  </div>
</template>

<script>
export default {
  methods: {
    changeLang(lang) {
      this.$i18n.locale = lang; // 切换语言
    },
  },
};
</script>
3.4. 参数占位与动态文本

vue-i18n 支持带参数的占位符,实现动态文本替换。

const messages = {
  en: { greeting: 'Hello, {name}!' },
  zh: { greeting: '你好,{name}!' },
};

<p>{{ $t('greeting', { name: 'Tom' }) }}</p>

// en:Hello, Tom! / zh:你好,Tom!
3.5. 复数处理

支持复数规则,根据数量动态显示不同的文本。

const messages = {
  en: {
    apple: 'No apples | One apple | {count} apples',
  },
  zh: {
    apple: '没有苹果 | 一个苹果 | {count} 个苹果',
  },
};

<p>{{ $tc('apple', 0) }}</p> <!-- No apples -->
<p>{{ $tc('apple', 1) }}</p> <!-- One apple -->
<p>{{ $tc('apple', 5, { count: 5 }) }}</p> <!-- 5 apples -->
3.6. 格式化日期和数字
const messages = {
  en: { date: 'Current date: {date}' },
  zh: { date: '当前日期:{date}' },
};

<template>
  <div>
    <p>{{ $t('date', { date: new Date().toLocaleDateString() }) }}</p>
    <p>{{ $n(123456.789, 'currency') }}</p>
  </div>
</template>

<script>
export default {
  methods: {
    // 使用 $n 方法对数字进行本地化
    $n(value, type) {
      return new Intl.NumberFormat(this.$i18n.locale, { style: type, currency: 'USD' }).format(value);
    },
  },
};
</script>

// 英文:Current date: 12/31/2024
// 中文:当前日期:2024/12/31
// 数字:123,456.79(按货币格式化)
3.7. 语言文件拆分与异步加载
const i18n = new VueI18n({
  locale: 'en',
  fallbackLocale: 'en',
  messages: {}, // 初始为空
});

// 动态加载语言包
async function loadLanguageAsync(lang) {
  if (!i18n.getLocaleMessage(lang)) {
    const messages = await import(`@/locales/${lang}.json`);
    i18n.setLocaleMessage(lang, messages.default);
  }
  i18n.locale = lang;
}

4. 优势

简单易用:提供 tthis.t 和 this.i18n.locale 等 API,方便文本渲染与语言切换。

多语言配置灵活:可扩展多语言包,通过 JSON 或对象统一管理文本。

动态替换参数:支持占位符,实现动态插值。

性能优化:仅加载当前语言包,适合大型项目使用。

支持回退语言:当前语言缺少文本时自动回退备用语言,提升健壮性。

5. 缺点

包体积较大: vue-i18n 的功能比较多,因此引入后会增加项目的包体积。

配置复杂度: 管理多语言包的配置较为繁琐,语言包拆分和维护需要额外投入精力。

首屏性能影响: 当语言包较大时,加载语言资源可能会增加首屏时间。

6. 使用:

6.1. 安装:vue2 安装版本需要 <= 8

npm install vue-i18n@8 --save

6.2. 创建配置文件

在 src 目录下创建 i18n/index.ts,用于初始化:

// src/i18n/index.ts
import Vue from 'vue';
import VueI18n from 'vue-i18n';

Vue.use(VueI18n);

const messages = {
  en: {
    hello: 'Hello',
    welcome: 'Welcome to our App',
  },
  zh: {
    hello: '你好',
    welcome: '欢迎使用我们的应用',
  },
};

const i18n = new VueI18n({
  locale: 'en', // 设置默认语言
  fallbackLocale: 'en', // 备用语言
  messages,
});

export default i18n;
6.3. 挂载

main.js 中引入 i18n 并挂载到 Vue 实例中:

// src/main.ts
import Vue from 'vue';
import App from './App.vue';
import i18n from './i18n'; // 引入 i18n

Vue.config.productionTip = false;

new Vue({
  i18n, // 挂载 i18n 实例
  render: h => h(App),
}).$mount('#app');
6.4. 在组件中使用
<template>
  <div>
    <!-- 使用 $t 方法来翻译文本 -->
    <p>{{ $t('hello') }}</p>
    <p>{{ $t('welcome') }}</p>

    <!-- 切换语言按钮 -->
    <button @click="changeLanguage('en')">English</button>
    <button @click="changeLanguage('zh')">中文</button>
  </div>
</template>

<script>
export default {
  methods: {
    changeLanguage(lang) {
      this.$i18n.locale = lang; // 动态切换语言
    },
  },
};
</script>

7. 开发插件 - i18n Ally

VSCode 的 i18n Ally 插件

7.1. 功能:
  • 自动识别语言文件:
    • 支持识别常见国际化工具的语言文件,如 vue-i18n 的 JSON 格式文件。
    • 自动扫描项目中的 src/locales 或指定路径的语言文件。
  • 语言文件预览与编辑:
    • 在代码中 快速预览 国际化文本内容,无需切换文件。
    • 支持 直接编辑 语言文件,修改时自动更新。
  • 快捷键快速跳转与定位:
    • 通过 快捷键 快速定位到对应的语言文件,提升开发效率。
    • 支持从代码中直接跳转到语言键所在的 JSON 文件。
  • 语言键自动补全:
    • 在代码中输入 $t('') 时,插件会自动提示可用的语言键,减少拼写错误和重复操作。
    • 通过补全功能,可以快速找到已经定义的国际化文本。
  • 语言缺失检查:
    • 自动检测各语言文件中是否缺失翻译内容。
    • 直观显示未翻译的键,确保各个语言的完整性。
  • 多语言预览:
    • 在编辑页面时,支持实时预览不同语言的翻译效果。
    • 开发者可以在编辑器中切换语言,检查多语言界面内容。
7.2. 安装与配置

在 VSCode 扩展市场搜索 i18n Ally 并安装。

在 settings.json 中进行基础配置:

{
  "i18n-ally.localesPaths": ["src/i18n"], // 指定语言文件路径
  "i18n-ally.keystyle": "nested", // 设置语言文件的格式,如嵌套格式
  "i18n-ally.sourceLanguage": "en", // 设置默认语言
  "i18n-ally.displayLanguage": "zh" // 编辑器中显示的预览语言
}

8. 参考文档

Vue I18n 官网

vue-i18n源码分析

vue i18n 国际化保姆级教程