Skip to content

React

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

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

  • @voerkai18n/react

    React插件,在初始化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.tsx 翻译组件
        • index.ts 入口文件
        • settings.json 配置文件
        • storage.ts 存储管理
        • loader.ts 加载器
        • transform.ts 翻译变换
        • formatters.json 格式化器配置
    • package.json
    • index.ts

第3步:启用React支持

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

bash
> voerkai18n apply

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

  • 安装@voerkai18n/react
  • 更新languages的相关文件,主要是languages/component.{tsx|jsx}

提示

也可以手动安装@voerkai18n/react,并更新languages的相关文件。见下文手工配置。

第4步:配置应用

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

ts
import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import './index.css'
import App from './App.tsx' 
import "./languages"   
import { i18nScope } from "./languages"

i18nScope.ready(()=>{
  createRoot(document.getElementById('root')!).render(
    <StrictMode>
      <App />
    </StrictMode>,
  )
})

第5步:配置插件

修改vite.config.{ts|js}文件,引入@voerkai18n/plugins/vite

ts
import { defineConfig } from 'vite'
import i18nPlugin from '@voerkai18n/plugins/vite'
import react from '@vitejs/plugin-react-swc'
import tailwindcss from '@tailwindcss/vite'
import viteInspector from 'vite-plugin-inspect'

// https://vite.dev/config/
export default defineConfig({
  plugins: [
    i18nPlugin(),             
    react(),    
    tailwindcss(),
    viteInspector(),    
  ],
})
  • @voerkai18n/plugins/vite插件的作用为Vue应用提供自动文本映射功能。

注意

@voerkai18n/plugins/vite插件需要在react插件之前引入。 因为react插件会对jsx进行编译转码,从而导致@voerkai18n/plugins/vite插件无法通过正则表达式对代码中的t函数和Translate组件进行识别。

第6步:翻译内容

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

tsx
import { t, Translate } from './languages'

export default ()=>{
  return (
    <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>            
      <button onClick={login}>
        <Translate message="登录" />
      </button>
    </div>
  )
}

提示

  • 使用t函数和Translate组件时来包裹要翻译的内容。
  • 大段落文本内容可以使用Translate组件来包裹。

第7步:切换语言

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

tsx
import React from 'react'; 
import { useVoerkaI18n } from '@voerkai18n/react';
import classNames from 'classnames'

const LanguageBar: React.FC = () => {
  const { activeLanguage, changeLanguage, languages } = useVoerkaI18n();
  return (
    <div className="flex md:order-2 flex-row justify-items-center align-middle">
      { languages.map((lang) => {
        return (<button 
          key={lang.name} 
          onClick={() => changeLanguage(lang.name) } 
          className={ lang.name === activeLanguage ? 'active' : ''}
        >{lang.name}</button>)
      })}
    </div>
  )
}

useVoerkaI18n返回值:

ts
{
    scope          : VoerkaI18nScope
    manager        : VoerkaI18nManager
    activeLanguage : string
    defaultLanguage: string
    languages      : VoerkaI18nLanguage
    changeLanguage : (language:string)=>Promise<string>,
    t              : VoerkaI18nTranslate
};

指南

手动配置

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

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

翻译组件

使用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
}
参数 类型 默认值 说明
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

useVoerkaI18n

useVoerkaI18n是一个ReactHook,用来访问VoerkaI18n的相关信息。

ts
import { useVoerkaI18n } from "@voerkai18n/react"

const { 
  t, 
  activeLanguage,
  defaultLanguage, 
  changeLanguage,
  scope,
  manager
} = useVoerkaI18n()

使用useVoerkaI18n可以渲染出语言切换的组件:

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 setup>
import { i18nScope} from './languages';
import { useVoerkaI18n } from '@voerkai18n/vue';   
const { activeLanguage,languages } =  useVoerkaI18n(i18nScope)
</script>

VoerkaI18nProvider

VoerkaI18nProvider用来包装入口,是对i18nScope.ready的封装。

tsx
import { VoerkaI18nProvider } from '@voerkai18n/react'

<VoerkaI18nProvider>
    <StrictMode>
      <App />
    </StrictMode>,
</VoerkaI18nProvider>

// 等效于

i18nScope.ready(()=>{
  createRoot(document.getElementById('root')!).render(
    <StrictMode>
      <App />
    </StrictMode>,
  )
})
  • VoerkaI18nProvider提供一个fallback属性,用来在加载过程中显示一个loading组件。

加载中

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

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

tsx
// languages/component.tsx
import { createTranslateComponent,ReactTranslateComponentType } from "@voerkai18n/react";
import Loading from '../components/Loading';
export const component = createTranslateComponent({loading:<Loading/>})
export type TranslateComponentType = ReactTranslateComponentType

提示

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

示例