Skip to content

Vue2

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

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

  • @voerkai18n/vue2

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

  • @voerkai18n/plugins

    编译期插件,在vite.config.js中配置,用来实现自动文本映射等功能,参考IdMap

使用方法

第1步:安装依赖

首先安装@voerkai18n/cli到全局.

bash
npm install -g @voerkai18n/cli
bash
yarn global add @voerkai18n/cli
bash
pnpm  add -g @voerkai18n/cli

第2步:初始化

接着VoerkaI18n init初始化工程。

bash
> voerkai18n init

初始化完成后,会创建一个语言工作目录,默认位置是src/languages。文件夹结构如下:

  • myapp
    • src
      • languages
        • messages
        • paragraphs
        • translates/提取需要翻译的内容
          • messages提取的需要翻译的内容
          • paragraphs提取的需要翻译的段落
        • prompts执行AI翻译的相关提示词
        • api.json API接口
        • component.ts 翻译组件
        • index.ts 入口文件
        • settings.json 配置文件
        • storage.ts 存储管理
        • loader.ts 加载器
        • transform.ts 翻译变换
        • formatters.json 格式化器配置
    • package.json
    • index.ts

第3步:启用Vue 2 支持

接下需要voerkai18n apply来启用Vue 2支持。

bash
> voerkai18n apply

执行voerkai18n apply命令后,选择Vue3后,会执行以下操作:

  • 安装@voerkai18n/vue2
  • 更新languages的相关文件,主要是languages/component.{ts|js}

第4步:配置应用

修改main.ts文件,引入@voerkai18n/vue2

ts
import Vue from 'vue'
import App from './App.vue'
import router from './router'
import store from './store'
import  { i18nPlugin } from '@voerkai18n/vue2'  
import { i18nScope } from "./languages"

Vue.config.productionTip = false

Vue.use(i18nPlugin,{
  i18nScope
})

i18nScope.ready(()=>{
  new Vue({
    router,
    store,
    render: h => h(App)
  }).$mount('#app')
})

i18nPlugin插件的作用为Vue组件提供:

  • 提供全局组件实例t函数
  • 全局的Translate组件

第5步:配置插件

修改vue.config.js文件,引入@voerkai18n/plugins/webpack

ts
const webpackPlugin  = require("@voerkai18n/plugins/webpack")

module.exports = {
    configureWebpack: {
      plugins: [
        webpackPlugin()
      ] 
    }
  }
  • @voerkai18n/plugins/webpack插件的作用为Vue应用提供自动文本映射功能。

第6步:翻译内容

接下来就可以直接在Vue组件中使用t函数和Translate组件进行翻译。

vue
<template>
	<div>
        <h1>
          <Translate message="请输入用户名称"/>
        </h1>
        <div>
            <span>
              <Translate message="用户名:" />
            </span>
            <input type="text" :placeholder="t('邮件/手机号码/帐号')"/>
            <span>
              <Translate message="密码:" />
            </span>
            <input type="password" :placeholder="t('至少6位的密码')"/>            
            <Translate id="notice">
              大段文本内容
            </Translate>
    	</div>            
    </div>
        <button @click="login">
          <Translate message="登录" />
        </button>
    </div>
</template>

提示

  • 使用t函数和Translate组件时来包裹要翻译的内容。
  • 大段落文本内容可以使用Translate组件来包裹。
  • t函数和Translate已经由@voerkai18n/vue插件自动注入到组件中,不需要额外导入。

第7步:切换语言

引入useVoerkaI18n插件来实现切换语言的功能。

vue
<template>
    <ul class="language-bar"> 
        <li v-for="lang in languages">
            <button 
                class="lang-button"
                @click="changeLanguage(lang.name)" 
                :class="{ active: lang.name === activeLanguage }"
                :key="lang.name">{{ lang.title }}-{{ lang.name }}</button>
        </li> 
    </ul>
</template>
<script>
import { i18nScope } from '../languages';
import { withI18n } from '@voerkai18n/vue2';

export default withI18n({   
  // Vue 2.x代码
},i18nScope)

</script>
  • withI18n函数会为当前组件混入changeLanguageactiveLanguagelanguages等属性。

指南

手动配置

voerkai18n apply负责自动配置Vue 2应用支持,也可以手动配置.

  • 编辑languages/component.{ts|js}文件
ts
import { 
  createTranslateComponent, 
  type VueTranslateComponentType 
} from "@voerkai18n/vue2";
export const component = createTranslateComponent()
export type TranslateComponentType = VueTranslateComponentType

启用插件

ts
import Vue from 'vue'
import App from './App.vue'
import router from './router'
import store from './store'
import  { i18nPlugin } from '@voerkai18n/vue2'
import { i18nScope } from "./languages" 

Vue.use(i18nPlugin,{
  i18nScope
})

i18nScope.ready(()=>{
  new Vue({
    router,
    store,
    render: h => h(App)
  }).$mount('#app')
})

插件参数:

参数 类型 默认值 说明
i18nScope VoerkaI18nScope 语言作用域

启用i18nPlugin插件后

  • 提供一个全局t函数,可以全局直接访问。这样就不用再在每个组件中额外引入t函数了
  • 提供一个全局$activeLangauge属性代表当前激活的语言,该属性是一个Vue.observable对象,访问$activeLangauge.value代表当前激语言。
  • 提供一个全局Translate组件,这样就可以在组件中直接使用Translate组件了,不需要额外导入。

翻译组件

使用voerkai18n apply -f vue后,会更新languages/component.ts,导出一个Vue 2组件,该组件可以在切换语言时自动重新渲染。也可以手动更新修改languages/component.ts,内容如下:

ts
import { 
  createTranslateComponent, 
  type VueTranslateComponentType 
} from "@voerkai18n/vue2";
export const component = createTranslateComponent()
export type TranslateComponentType = VueTranslateComponentType

创建参数

createTranslateComponent方法用来构建Vue组件,类型如下:

ts
type CreateTranslateComponentOptions = {
  default?: string
  tagName?: string 
  class?  : string
  style?  : string
  loading?: Component | boolean | string
}
参数 类型 默认值 说明
default string 默认显示文本
tagName string div 标签名称
class string CSS类名
style string CSS样式
loading Component 是否显示加载中
  • loading参数用来提供一个加载中的Vue组件,当加载远程文本时显示。加载中组件仅在message参数是一个Function或提供段落id时有效。

组件参数

ts
type VoerkaI18nTranslateProps<
  Options extends VoerkaI18nTranslateOptions = VoerkaI18nTranslateOptions,
  Children = any> = {
    id?       : string;
    message?  : VoerkaI18nToBeTranslatedMessage;
    vars?     : VoerkaI18nTranslateVars;
    default?  : any;
    tag?      : string;
    options?  : Options;
}
参数 类型 默认值 说明
id string 可选,段落ID
message VoerkaI18nToBeTranslatedMessage 可选,要翻译的文本
vars VoerkaI18nTranslateVars 可选,插值变量
default any 可选,默认文本
tag string 可选,标签名称
options Options 可选,选项
  • idmessage二选一,id优先级高于message

withI18n

withI18n可以为组件实例混入语言切换枚举语言等能力。

withI18n为组件实例混入以下属性和方法:

属性 类型 说明
activeLangauge string 当前激活的语言
defaultLangauge string 当前激活的语言
changeLangauge (lang:string)=>Promise<void> 切换语言方法
languages Array<VoerkaI18nLanguage> 语言列表

使用方法如下:

vue
<template>
  <div>
    <button  
      v-for="(lang, index) in languages"
      @click="i18nScope.change(lang.name)"
      type="button"       
      :class="{'red-text': activeLanguage === lang.name }"
      >  
      {{ lang.name }}     
      </button>
  </div>
</template>

<script>
import { withI18n } from '@voerkai18n/vue2';    
export default withI18n({

})

</script>

加载中

当使用翻译组件的动态翻译时,允许在翻译过程中显示加载中的状态。

可以按如下方式提供一个加载中的状态:

ts
import { 
  createTranslateComponent, 
  type VueTranslateComponentType 
} from "@voerkai18n/vue";
import Loading from './Loading.vue'  //! 您的加载中组件
export const component = createTranslateComponent({
  loading:Loading   //!
})
export type TranslateComponentType = VueTranslateComponentType

提示

大多数情况下,不需要提供加载中的状态,因为翻译过程是非常快的。 仅在动态翻译或异步加载大段落的场景下,才需要提供加载中的状态。

切换刷新陷阱

在使用VoerkaI18n时,新手经常会碰到的问题,就是切换语言后,Vue组件不会自动刷新。

比如以下代码在切换语言时自动刷新渲染:

vue
<template>
  <div>  
    <div> {{ title }} </div>
  </div>
</template>
<script >
export default {
  data(){
    return {
      title: this.t('你好') // 不会自动刷新
    }
  },
}
<script>

为什么以上代码在切换语言后不会自动刷新呢?

因为Vue组件的data函数中调用t函数时,t函数的执行结果已经固定,所以不会再随着语言的切换而刷新。

如何解决?

要解决这个问题,需要充分理解Vue的晌应式机制

  • 让翻译的结果成为响应式数据
  • 在语言切换时更新翻译的结果

重点就是让翻译的结果成为响应式数据,这样在语言切换时,Vue才会自动更新视图。 此时只需要将title变为响应式数据即可。

vue
<template>
  <div>  
    <div> {{ title }} </div>
  </div>
</template>
<script >
export default {
  computed:{
      title:()=>this.t('你好') // 自动刷新
  }
}
</script >

示例