Vue应用多语言支持工程化最佳实践

前言

VoerkaI18n是一款非常优秀的全新的开源国际化多语言解决方案，主要特性包括：

• 全面工程化解决方案，提供初始化、提取文本、自动翻译、编译等工具链支持。
• 符合直觉，不需要手动定义文本Key映射。
• 强大的插值变量格式化器机制，可以扩展出强大的多语言特性。
• 支持babel插件自动导入t翻译函数。
• 支持nodejs、浏览器(vue/react/solid)等、React Native等任意JS场景
• 采用工具链与运行时分开设计，发布时只需要集成很小的运行时。
• 高度可扩展的复数、货币、数字等常用的多语言处理机制。
• 翻译过程内，提取文本可以自动进行同步，并保留已翻译的内容。
• 可以动态在线添加支持的语言
• 支持发布后的在线打语言包补丁，修复翻译错误
• 支持调用在线自动翻译对提取文本进行翻译。
• 核心运行时@voerkai18n/runtime超过90%的测试覆盖率
• 支持·TypeScript·开发

本节主要介绍如何在Vue 3应用中使用VoerkaI18n。

创建Vue 3应用一般采用Vite或Vue Cli来创建工程。在Vue3应用中引入voerkai18n来添加国际化应用需要由两个插件来简化应用。

• @voerkai18n/vue

  Vue插件，在初始化Vue应用时引入，提供访问当前语言、切换语言、自动更新等功能。

• @voerkai18n/vite

  Vite插件，在vite.config.js中配置，用来实现自动文本映射和t函数的自动导入等功能。

@voerkai18n/vue和@voerkai18n/vite两件插件相互配合，安装配置好这两个插件后，就可以在Vue文件使用多语言t函数。

第一步：基本流程

Vue应用启用VoerkaI18n国际化功能的完整工程化流程如下：

• 调用voerkai18n init初始化多语言工程
• 调用voerkai18n extract提取要翻译的文本
• 调用voerkai18n translate进行自动翻译或人工翻译
• 调用voerkai18n compile编译语言包
• 在Vue应用中引入@voerkai18n/vue和@voerkai18n/vite插件
• 在源码中使用t函数进行翻译

完整的工程化流程请参见工程化，以下简要介绍如何在Vue应用中使用VoerkaI18n。

第二步：启用@voerkai18n/vite插件

@voerkai18n/vite插件作用是：

• 可以根据idMap.ts映射文件将源码中的t("xxxxx")转换为t("<数字>")的形式，从而实现消除翻译内容的冗余内容。
• 实现自动导入t函数的功能，省却手动导入的麻烦。

@voerkai18n/vite插件的安装非常简单，只需要在vite.config.(ts|js)中添加如下内容：

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import Inspect from 'vite-plugin-inspect'
import Voerkai18nPlugin from "@voerkai18n/vite"
 
export default defineConfig({
  plugins: [    
    Inspect(),                // 可选    
    Voerkai18nPlugin(),       // 新增加
    vue()
  ],
})

• @voerkai18n/vite插件仅在开发和构建阶段作用。事实上，如果不在乎文本内容的冗余，不安装此插件也是可以工作正常的。
• vite-plugin-inspect仅用于调试，可以在http://localhost:3000/__inspect/查看当前工程中的@voerkai18n/vite是否正确地进行自动导入和idMap.ts映射，供开发阶段进行调试使用。
• @voerkai18n/vite插件的完整使用说明。

第三步：配置@voerkai18n/vue插件

@voerkai18n/vue插件用来自动注入t函数、切换语言等功能。

安装方法如下：

import { createApp } from 'vue'
import './style.css'
import App from './App.vue'
// 导入插件
import i18nPlugin from '@voerkai18n/vue'
// 导入当前作用域
import { i18nScope } from './languages'

// 等待i18nScope初始化完成
i18nScope.ready(()=>{
  const app = createApp(App)
  // 应用插件
  app.use<VoerkaI18nPluginOptions>(i18nPlugin as any,{
      i18nScope
  })
  app.mount('#app')
})

@voerkai18n/vue插件本质上是为每一个Vue组件自动混入t函数。

第四步：使用t翻译函数

Vue应用使用多语言本质是调用import { t } from 'langauges导入的t函数来进行翻译。

<script setup>
// 手动导入t函数
// 如果启用了@voerkai18n/vite插件，则可以省略此行实现自动导入
import { t } from "./languages"
console.log(t("Welcome to VoerkaI18n"))

</script>


// 直接使用t函数，不需要导入
<script>
export default {
    data(){
        return {
            username:"",
            password:"",
            title:t("认证")
        }
    },
    methods:{
        login(){
            alert(t("登录"))
        }
    }
}
</script>
// 直接使用
<template>
	<div>
        <h1>{{ t("请输入用户名称") }}</h1>
        <div>
            <span>{{t("用户名:")}}</span><input type="text" :placeholder="t('邮件/手机号码/帐号')"/>
            <span>{{t("密码:")}}</span><input type="password" :placeholder="t('至少6位的密码')"/>            
    	</div>            
    </div>
        <button @click="login">{{t("登录")}}</button>
    </div>
</template>

重点：

• 在<script setup>中手动导入import { t } from "./languages"
• 在<script>和<template>中可以直接使用t函数进行翻译。
• @voerkai18n/vue插件本质上是为每一个Vue组件自动混入t函数，并在在语言切换时会自动重新渲染

第五步：切换语言

引入@voerkai18n/vue插件来实现切换语言和自动重新渲染的功能。

<script setup lang="ts">
import { injectVoerkaI18n } from "@voerkai18n/vue"

// 提供一个i18n对象
const i18n = injectVoerkaI18n()
</script>

<script>
export default {
   //......
}
</script>  
<template>
  <img alt="Vue logo" src="./assets/logo.png" />
  <h1>{{ t("中华人民共和国")}} </h1>
  <h2>{{ t("迎接中华民族的伟大复兴")}} </h2>
  <h5>默认语言：{{ i18n.defaultLanguage }}</h5>
  <h5>当前语言：{{ i18n.activeLanguage }}</h5>
  <!-- 遍历支持的语言  -->
  <button v-for="lng of i18n.languages" 
    @click="i18n.activeLanguage = lng.name"  
    >{{ lng.title }}</button>
</template>

小结

• @voerkai18n/vue插件为Vue单文件组件提供自动注入t函数，可以在<script>和<template>中直接使用，在<script setup>中需要手动从language中导入t函数。
• Vue应用的中普通js/ts文件需要手动从language中导入t函数。
• 使用injectVoerkaI18n()来实现遍历支持的语言和切换语言的功能。
• 当切换语言时会自动重新渲染组件。
• @voerkai18n/vue插件只能用在Vue 3。
• 完整的示例请见这里