gitee/voerka-i18n
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

update docs

Browse Source
This commit is contained in:
wxzhang 2023-01-27 22:15:14 +08:00
parent d1d9f503cd
commit b21c1385ae
15 changed files with 208 additions and 71 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
.umirc.ts
View File

@ -116,7 +116,8 @@ export default defineConfig({
"/guide/tools/cli.md",
"/guide/tools/babel.md",
"/guide/tools/vite.md",
"/guide/tools/vue.md"
"/guide/tools/vue.md",
"/guide/tools/webpack.md"
],
},
],

7
docs/src/guide/tools/vite.md
View File

@ -69,7 +69,9 @@ export default defineConfig({
Inspect(), // 可选的
Voerkai18nPlugin({
location: "./", // 可选的，指定当前工程目录
autoImport: false, // 是否自动导入t函数
autoImport: false, // 不自动导入t函数
// autoImport: true, // 自动导入t函数
// autoImport: [".js"], // 仅在js文件中自动导入t函数
debug:false, // 是否输出调试信息，当=true时，在控制台输出转换匹配的文件清单
patterns:[
"!(?<!.vue\?.*).(css|json|scss|less|sass)$", // 排除所有css文件
@ -83,7 +85,8 @@ export default defineConfig({
- `location`：可选的，用来指定当前工程目录，一般情况是不需要配置的，会自动取当前文件夹。并且假设`languages`文件夹在`<location>/src/languages`文件夹下。
- `autoImport`：可选的，默认`false`，用来配置是否自动导入`t`函数。当vue文件没有指定导入时才会自动导入，并且根据当前vue文件的路径处理好导入位置。
- `autoImport`：可选的，用来配置是否自动导入`t`函数。默认`false`代表不自动导入`t`函数。`true`代表自动导入`t`函数。`autoImport=[".<扩展名>",".<扩展名>"]`列出源码扩展名列表，代表仅仅在这些扩展名文件中自动导入`t`函数，如`autoImport=[".js"]`代表仅在js源文件中自动导入`t`函数。
由于在`typescript`下自动导入`t`函数会导致类型错误提示，所以一般仅建议在`nodejs`下使用。
- `debug`：可选的，开启后会在控制台输出一些调试信息，对一般用户没有用。

129
docs/src/guide/tools/webpack.md Normal file
View File

@ -0,0 +1,129 @@
# Webpack Loader
`voerkai18n-loader`是一个标准的`webpack loader`用来实现在`webpack`下实现根据`idMap`文件自动映射翻译内容和自动导入`t`函数。主要功能：
- 自动读取当前工程`languages/idMap.(js|ts)`文件，将`t("xxxxx")`的待翻译内容转换为`t("1")`、`t("2")`、`t("<数字>")`形式，从而消除源码中的冗余文本。
- 根据配置,在`(js|ts|tsx|jsx)`等文件中从`languages`自动导入`t`函数。
## 安装
```shell
pnpm add -D voerkai18n-loader
npm install -D voerkai18n-loader
yarn add -D voerkai18n-loader
```
## 使用方法
`voerkai18n-loader`是一个标准的`webpack loader`,在任意使用`webpack`作为构建工具的环境下均可以使用。
关于如何安装配置`webpack loader`请参阅`webpack`的相关文档。
下面我们以使用`Create React App`创建的`React`应用为例介绍如何安装配置`voerkai18n-loader`。
### 第一步: 创建`React`应用
```shell
npx create-react-app myapp
```
### 第二步: 修改webpack配置
要修改使用`Create React App`创建的`React`应用的`webpack`配置有两种方法:
- **第一种：修改`react-scripts eject`命令输出的配置文件**
执行`react-scripts eject`命令，该命令会在当前工程的`config`文件下生成`webpack.config.js`。
打开`config/webpack.config.js`，在`module.rules`中添加一项：
```javascript
// config/webpack.config.js
{
module:{
rules:[
{
test: [/^$/, /\.(js|mjs|jsx|ts|tsx)$/],
loader:"voerkai18n-loader",
include: paths.appSrc,
enforce:'pre',
}
//...其他规则
]
}
}
```
也可以指定`voerkai18n-loader`配置参数。
```javascript
// config/webpack.config.js
{
module:{
rules:[
{
test: [/^$/, /\.(js|mjs|jsx|ts|tsx)$/],
use:[
{
loader:"voerkai18n-loader",
// 可选的配置参数
options: {
autoImport:false, // 是否自动导入t函数
debug:false, // 输出一些调试信息
}
}
],
include: paths.appSrc, // 只转换
enforce:'pre',
}
//...其他规则
]
}
}
```
- **第二种：使用`@craco/craco`配置**
`react-scripts eject`命令生成的`config/webpack.config.js`比较复杂，新手容易修改出问题来，这时可以使用`@craco/craco`。
[@craco/craco](https://github.com/dilanx/craco)是一个第三方库，可以在`React`应用不进行`eject`的情况下更加方便地修改`webpack`配置。
按照`@craco/craco`配置好`React`应用后，修改`craco.config.js`，如下：
```javascript
module.exports = {
webpack: {
configure:(config, { env, paths })=>{
config.module.rules.push(
{
test: [/^$/, /\.(js|mjs|jsx|ts|tsx)$/],
use:[
{
loader:"voerkai18n-loader",
options: {
autoImport:true,
debug:true
}
}
],
include: paths.appSrc,
enforce:'pre',
}
)
return config
}
}
}
```
## 配置参数
`voerkai18n-loader`支持两个配置参数：
- **autoImport**
是否自动导入`t`函数，当在使用`js`开发时，可以通过配置`autoImport=true`来自动从当前应用的`languages`自动导入`t`函数。
如果您的是使用`typescript`开发，则不建议开启此功能，在此如果不导入`t`函数，会导致类型错误。
- **debug**
在控制台输出一些调试信息。

90
docs/src/guide/use/react.md
View File

@ -1,6 +1,6 @@
# React应用
开发`React`应用一般可以采用`create-react-app`或`Vite+"@vitejs/plugin-react`工具来创建工程。
`React`应用一般可以采用`create-react-app`或`Vite+"@vitejs/plugin-react`工具来创建工程。
本节介绍如何为`Vite`+`@vitejs/plugin-react`创建的工程添加`voerkai18n`支持。
@ -17,14 +17,40 @@
> voerkai18n compile
```
## 第二步：导入`t`翻译函数
## 第二步： 安装`Vite`插件
如果应用是采用`Vite`+`@vitejs/plugin-react`创建的工程，则可以通过配置`@voerkai18n/vite`插件实现自动导入`t`函数和`翻译内容自动映射`等。
在`vite.config.js`中配置导入安装`@voerkai18n/vite`插件。
```typescript | pure
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import Inspect from 'vite-plugin-inspect'
import Voerkai18nPlugin from "@voerkai18n/vite"
// https://vitejs.dev/config/
export default defineConfig({
plugins: [
Inspect(), // localhost:3000/__inspect/
Voerkai18nPlugin({
debug: true // 输出一些调试信息
}),
react()
]
})
```
详见[@voerkai18n/vite](/guide/tools/vite)插件介绍。
## 第三步：导入`t`翻译函数
`t`翻译函数用来进行文件翻译，普通的`React`应用`t`翻译函数可以用在两个地方：
- 普通的`js`或`ts`文件
- `React`组件`jsx、tsx`文件
### 在`js`或`ts`文件中使用
### 在`js|ts`文件中使用
只需要从`languages`直接导入`t`函数即可。
@ -37,17 +63,20 @@ import { t } from "./languages"
import { t } from "../languages"
import { t } from "../../languages"
import { t } from "../../../languages"
console.log(t("中华人民共和国"))
```
导入`t`函数后就可以直接使用了。
### 在`React`组件中翻译
### 在`React`组件中使用
在`React`组件中使用`t`函数翻译与在`js`或`ts`文件中使用的最大区别在于：**当切换语言时，需要触发组件的重新渲染**。
在`React`组件中使用`t`函数翻译与在`js|ts`文件中使用的最大区别在于：**当切换语言时，需要触发组件的重新渲染**。为此我们需要在根应用配置`Provider`。
- **配置根组件Provider**
1. **配置根组件Provider**
使用`VoerkaI18nProvider`包装应用根组件，本质上是创建了一个`VoerkaI18nContext.Provider`
使用`VoerkaI18nProvider`包装应用根组件，本质上是创建了一个`VoerkaI18nContext.Provider`。
```jsx | pure
@ -64,9 +93,9 @@ export default App(){
}
```
- **组件中使用翻译函数**
2. **组件中使用`t`翻译函数**
通过`useVoerkaI18n`获取当前作用域的`t`翻译函数。
接下来通过`useVoerkaI18n`获取当前作用域的`t`翻译函数。
```jsx | pure
import { useVoerkaI18n } from "@voerkai18n/react"
@ -79,42 +108,13 @@ export function MyComponent(){
```
注意：在组件中直接使用`import { t } from "languages`也是可以工作的，因为本质上`t`函数仅仅是一个普通的函数。但是当动态切换语言时，对应的组件不能自动重新渲染。因此，需要使用`{ t } = useVoerkaI18n()`导入`t`函数，才可以在切换语言时自动重新渲染组件。
## 第三步： 自动导入`t`翻译函数
如果应用是采用`Vite`+`@vitejs/plugin-react`创建的工程，则可以通过配置`@voerkai18n/vite`插件实现自动导入`t`函数和`翻译内容自动映射`等。
在`vite.config.js`中配置导入安装`@voerkai18n/vite`插件。
```typescript | pure
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import Inspect from 'vite-plugin-inspect'
import Voerkai18nPlugin from "@voerkai18n/vite"
// https://vitejs.dev/config/
export default defineConfig({
plugins: [
Inspect(), // localhost:3000/__inspect/
Voerkai18nPlugin({ debug: true }),
react()
]
})
```
详见`@voerkai18n/vite`插件介绍。
`@voerkai18n/vite`插件主要干两件事情：
- 对`js/ts`文件自动导入`t`函数，`jsx/tsx`文件不需要自动导入，只能使用`useVoerkaI18n`。
- 根据`idMap.(js|ts)`内容自动替换翻译内容，用来消除冗余内容。
**注意：**
在组件中直接使用`import { t } from "languages`也是可以工作的，因为本质上`t`函数仅仅是一个普通的函数。但是当动态切换语言时，对应的组件不能自动重新渲染。因此，只有通过`{ t } = useVoerkaI18n()`导入的`t`函数，才可以在切换语言时自动重新渲染组件。
## 第四步：切换语言
接下来在一般我们还需要实现语言切换的功能界面,`useVoerkaI18n`提供了：
- `t`: 当前作用域的翻译函数
- `language`: 当前激活语言名称
- `defaultLanguage`: 默认语言名称
- `changeLanguage(language)`: 用来切换当前语言
@ -126,12 +126,13 @@ export default defineConfig({
import { useVoerkaI18n } from "@voerkai18n/react"
export function MyComponent(){
const { t, language,changeLanguage,languages,defaultLanguage } = useVoerkaI18n()
const { t, activeLanguage,changeLanguage,languages,defaultLanguage } = useVoerkaI18n()
return (
<div>
<h1>{t("当前语言")}:{language}</h1>
<h1>{t("当前语言")}:{activeLanguage}</h1>
<h1>{t("默认语言")}:{defaultLanguage}</h1>
<div> {
{/* 遍历出支持的所有语言 */}
languages.map(lang=>{
return (<button
key={lang.name}
@ -150,7 +151,8 @@ export function MyComponent(){
- 使用`<VoerkaI18nProvider scope={i18nScope}>`封装根组件
- `const { t } = useVoerkaI18n()`来导入翻译函数
- 使用`const { language,changeLanguage } = useVoerkaI18n()`来访问切换语言的函数
- 使用`const { changeLanguage } = useVoerkaI18n()`来访问切换语言的函数
- 在普通`ts/js`文件中使用`import { t } from "./languages"`来导入`t`翻译函数
- `@voerkai18n/vite`插件是可选的，仅仅普通`ts/js`文件使用`t`翻译函数时用来自动导入。
- 如果使用`Create React App`创建`React`应用，则请参考`voerki18n-loader`

4
packages/apps/reactapp/src/components/LanguageConfigurator.jsx
View File

@ -2,10 +2,10 @@ import { useState } from "react";
import { useVoerkaI18n } from "@voerkai18n/react"
function LanguageConfigurator(props) {
const { language, changeLanguage, languages,t } = useVoerkaI18n();
const { activeLanguage, changeLanguage, languages,t } = useVoerkaI18n();
return (
<div>
<div>{t("当前语言")}：{ language }</div>
<div>{t("当前语言")}：{ activeLanguage }</div>
<div>
{languages.map((lang) => {
return (

4
packages/babel/package.json
View File

@ -1,6 +1,6 @@
{
"name": "@voerkai18n/babel",
"version": "1.0.33",
"version": "1.0.34",
"description": "Babel插件，实现自动导入t函数和自动文本映射",
"main": "index.js",
"homepage": "https://gitee.com/zhangfisher/voerka-i18n",
@ -17,5 +17,5 @@
"dependencies": {
"@voerkai18n/utils": "workspace:latest"
},
"lastPublish": "2023-01-27T20:55:13+08:00"
"lastPublish": "2023-01-27T21:05:20+08:00"
}

4
packages/cli/package.json
View File

@ -1,6 +1,6 @@
{
"name": "@voerkai18n/cli",
"version": "1.0.47",
"version": "1.0.48",
"description": "命令行工具,用来初始化/提取/编译/自动翻译等工具链",
"main": "index.js",
"homepage": "https://gitee.com/zhangfisher/voerka-i18n",
@ -47,5 +47,5 @@
"through2": "^4.0.2",
"vinyl": "^2.2.1"
},
"lastPublish": "2023-01-27T20:55:01+08:00"
"lastPublish": "2023-01-27T21:05:04+08:00"
}

4
packages/formatters/package.json
View File

@ -1,6 +1,6 @@
{
"name": "@voerkai18n/formatters",
"version": "1.0.16",
"version": "1.0.17",
"description": "格式化器，提供对要翻译文本的转换功能",
"main": "index.js",
"homepage": "https://gitee.com/zhangfisher/voerka-i18n",
@ -20,5 +20,5 @@
"dependencies": {
"dayjs": "^1.11.0"
},
"lastPublish": "2023-01-27T20:54:24+08:00"
"lastPublish": "2023-01-27T21:04:37+08:00"
}

4
packages/react/index.jsx
View File

@ -2,7 +2,7 @@ import React, { useState, useEffect,useContext,useCallback} from 'react';
export const VoerkaI18nContext = React.createContext({
languages:null,
language:'zh',
activeLanguage:'zh',
defaultLanguage:null,
changeLanguage:() => {},
t:()=>{}
@ -29,8 +29,8 @@ export function VoerkaI18nProvider(props){
},[language])
return (
<VoerkaI18nContext.Provider value={{
language,
changeLanguage,
activeLanguage:language,
defaultLanguage:VoerkaI18n.defaultLanguage,
languages:VoerkaI18n.languages,
t:scope.t

4
packages/react/package.json
View File

@ -1,6 +1,6 @@
{
"name": "@voerkai18n/react",
"version": "1.0.12",
"version": "1.0.13",
"description": "React支持,提供语言切换等功能",
"main": "index.jsx",
"typings": "index.d.ts",
@ -22,5 +22,5 @@
"peerDependencies": {
"react": "^17.0.2"
},
"lastPublish": "2023-01-27T20:54:45+08:00"
"lastPublish": "2023-01-27T21:04:50+08:00"
}

4
packages/runtime/package.json
View File

@ -1,6 +1,6 @@
{
"name": "@voerkai18n/runtime",
"version": "1.1.19",
"version": "1.1.20",
"description": "核心运行时",
"main": "./dist/index.cjs",
"module": "./dist/index.esm.js",
@ -40,5 +40,5 @@
"rollup-plugin-clear": "^2.0.7",
"rollup-plugin-terser": "^7.0.2"
},
"lastPublish": "2023-01-27T20:54:12+08:00"
"lastPublish": "2023-01-27T21:04:25+08:00"
}

4
packages/utils/package.json
View File

@ -1,6 +1,6 @@
{
"name": "@voerkai18n/utils",
"version": "1.0.22",
"version": "1.0.23",
"description": "公共工具库",
"main": "index.js",
"scripts": {
@ -13,5 +13,5 @@
"fs-extra": "^10.0.1",
"shelljs": "^0.8.5"
},
"lastPublish": "2023-01-27T20:53:53+08:00"
"lastPublish": "2023-01-27T21:04:08+08:00"
}

7
packages/vite/package.json
View File

@ -1,12 +1,13 @@
{
"name": "@voerkai18n/vite",
"version": "1.0.22",
"version": "1.0.23",
"description": "Vite插件,提供自动插入翻译函数和文本映射等功能",
"homepage": "https://gitee.com/zhangfisher/voerka-i18n",
"repository": {
"type": "git",
"url": "git+https://github.com/zhangfisher/voerka-i18n"
}, "main": "index.js",
},
"main": "index.js",
"types": "index.d.ts",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1",
@ -17,7 +18,7 @@
"dependencies": {
"@voerkai18n/utils": "workspace:latest"
},
"lastPublish": "2023-01-27T20:55:25+08:00",
"lastPublish": "2023-01-27T21:05:33+08:00",
"devDependencies": {
"vite": "^4.0.4"
}

4
packages/vue/package.json
View File

@ -1,6 +1,6 @@
{
"name": "@voerkai18n/vue",
"version": "1.0.15",
"version": "1.0.16",
"description": "Vue3插件,提供自动插件翻译函数和语言切换功能",
"main": "index.js",
"typings": "index.d.ts",
@ -19,5 +19,5 @@
"@voerkai18n/runtime": "workspace:^1.1.16",
"vue": "latest"
},
"lastPublish": "2023-01-27T20:55:37+08:00"
"lastPublish": "2023-01-27T21:05:46+08:00"
}

7
packages/webpack/package.json
View File

@ -1,13 +1,14 @@
{
"name": "voerkai18n-loader",
"version": "1.0.2",
"version": "1.0.3",
"description": "voerkai18n loader for webpack",
"main": "loader.js",
"homepage": "https://gitee.com/zhangfisher/voerka-i18n",
"repository": {
"type": "git",
"url": "git+https://github.com/zhangfisher/voerka-i18n"
}, "scripts": {
},
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"keywords": [],
@ -19,5 +20,5 @@
"dependencies": {
"@voerkai18n/utils": "workspace:^1.0.21"
},
"lastPublish": "2023-01-27T20:55:54+08:00"
"lastPublish": "2023-01-27T21:06:05+08:00"
}