翻译组件

关于

除了使用t函数外，在前端代码中推荐使用<Translate>组件替代t函数。

Translate组件与t函数的区别在于：

• Translate翻译组件可以在语言切换时自动重新渲染，而t函数不会。
• Translate翻译组件支持段落翻译，而t函数不支持。见段落翻译。
• Translate翻译组件一般会为翻译内容包裹一个<span>标签，而t函数仅返回一个字符串。
• Translate翻译组件支持在线编辑翻译内容进行提交，而t函数不支持。

提示

一般推荐在UI模板中使用<Translate>翻译组件，而在脚本代码里使用t翻译函数。 比如在Vue的template部份使用<Translate>组件，而在script部份使用t函数。

使用方法

第1步：配置框架支持

显然，<Translate>组件是需要框架支持的，如Vue组件，React组件，Svelte组件等，不同的前端框架组件实现是不一样的。

所以我们需要先配置框架支持，具体如何配置请参考对应的框架文档。

以Vue 3为例，我们需要执行voerkai18n apply命令来自动配置Vue 3框架支持。

> voerkai18n apply

• 在apply命令中选择Vue3，会自动安装本配置@voerkai18n/vue支持, 更具体的配置详见集成Vue 3。
• 如果执行voerkai18n apply命令失败，可以手动配置支持，详见集成框架文件。

第2步：导入组件

接下，我们需要在代码中从languages导入Translate翻译组件。

// 从当前语言文件夹导入翻译组件
import { Translate } from "<myapp>/languages"

• 无论是React/Vue/Solid/Svelte等框架，均是同样从从languages导入Translate翻译组件

第3步：使用翻译组件

Translate翻译组件的作用就是将翻译内容渲染到页面上，并且可以在切换语言时自动重新渲染。

以Vue为例，我们可以在template中使用<Translate>翻译组件。

<template>
    <div>
        <Translate message="hello"/>  
        <!-- 动态翻译内容，向服务器发起请求 -->
        <Translate :message="(language)=>{.....}"/>  
    </div>
</template>

指南

组件属性

<Translate>组件支持以下属性：

属性	类型	默认值	说明
id	string	-	段落id，详见段落
message	string | VoerkaI18nToBeTranslatedMessage	-	文本信息
vars	string | number | Object | Array	-	插值变量
tag	string	span	标签名称
options	object	-	用来传递创建组件的参数
style	string	-	传递给组件的样式
className	string	-	传递给组件的类名
default	string	-	默认文本，当message是一个异步函数时提供默认值

• message属性的类型是VoerkaI18nToBeTranslatedMessage

type VoerkaI18nToBeTranslatedMessage = string 
    | ((
        language:string,
        vars?:VoerkaI18nTranslateVars,
        options?: VoerkaI18nTranslateOptions
    )=>string | Promise<string>)

特殊提醒

<Translate>翻译组件是框架相关的，不同的前端框架组件实现是不一样的。

启用组件支持

<Translate>翻译组件是框架相关的，不同的前端框架(React/Vue/Vue2/Svelte/Solid)的翻译组件实现是不一样的。

以Vue为例，可以通过修改languages/component.{ts|js}文件来启用<Translate>组件支持。

• myapp
  • languages
    • settings.json 语言配置文件
    • index.ts 包含该应用作用域下的翻译函数等
    • storage.ts
    • loader.ts
    • component.ts 修改此翻译组件
    • api.json 翻译API配置
    • +messages编译生成的语言包
    • translates此文件夹包含了所有需要翻译的内容
  • package.json
  • index.ts

编辑component.ts文件，启用<Translate>组件支持,如下：

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

自动启用组件支持

也可以通过voerkai18n apply命令来自动配置Vue 3框架支持。

> voerkai18n apply

动态翻译

<Translate>组件支持动态翻译，可以在message属性中传递一个函数，函数的参数是当前语言和插值变量。

<template>
    <div>
        <Translate :message="async (language)=>{return language==='zh-CN' ? '你好':'Hello'}" />  
    </div>
</template>

• 利用此特性可以实现动态翻译，比如从服务器获取翻译内容。
• message属性可以是一个异步函数，返回一个字符串或者一个Promise<string>。
• tag属性可以指定渲染的标签名称。
• t函数不支持动态翻译。

自定义翻译组件

除了官方提供的@voerkai18n/{vue|vue2|react|svelte|nextjs|solid}翻译组件外，您也可以自定义翻译组件。

// languages/component.ts
// import type { VoerkaI18nTranslateProps } from "@voerkai18n/runtime";

export const component = (scope:VoerkaI18nScope)=>{
      return (props:VoerkaI18nTranslateProps)=>{
         // 在此编写组件代码
      }
}
export type TranslateComponentType = ReturnType<typeof component>

VoerkaI18nTranslateProps类型声明如下：

export type VoerkaI18nTranslateProps<
    Options extends VoerkaI18nTranslateOptions = VoerkaI18nTranslateOptions,
    Children=any
>= {
    id?       : string
    message?  : VoerkaI18nToBeTranslatedMessage
    vars?     : VoerkaI18nTranslateVars
    default?  : any
    tag?      : string
    options?  : Options    
    children? : Children 
    style?    : any
    className?: string
}