Svelte

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

• @voerkai18n/svelte

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

• @voerkai18n/plugins

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

使用方法

第1步：安装依赖

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

npm

npm install -g @voerkai18n/cli

yarn

yarn global add @voerkai18n/cli

pnpm

pnpm  add -g @voerkai18n/cli

第2步：初始化

接着VoerkaI18n init初始化工程。

> 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步：启用Svelte支持

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

> voerkai18n apply

执行voerkai18n apply命令后，选择Svelte后，会执行以下操作：

• 安装@voerkai18n/svelte
• 更新languages的相关文件。

提示

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

第4步：配置应用

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

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。

import tailwindcss from "@tailwindcss/vite";
import { sveltekit } from '@sveltejs/kit/vite';
import { defineConfig } from 'vite'; 
import i18nPlugin from '@voerkai18n/plugins/vite' 

export default defineConfig({
	plugins: [
		i18nPlugin(),
		sveltekit(),
		tailwindcss()]
});

• @voerkai18n/plugins/vite插件的作用为Svelte应用提供自动文本映射功能。

注意

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

第6步：翻译内容

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

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插件来实现切换语言的功能。

import React from 'react'; 
import { useVoerkaI18n } from '@voerkai18n/svelte';
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返回值：

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

指南

手动配置

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

• 编辑languages/component.{tsx|jsx}文件

import { createTranslateComponent,type SvelteTranslateComponent } from "@voerkai18n/svelte";
export const component  = createTranslateComponent()
export type TranslateComponentType = SvelteTranslateComponent

加载中

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

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

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

提示

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

示例

• 完整的示例请见这里