update docs

.umirc.ts

@@ -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"
                 ],
             },
         ],

docs/src/guide/tools/vite.md

@@ -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`：可选的，开启后会在控制台输出一些调试信息，对一般用户没有用。
 

docs/src/guide/tools/webpack.md

@@ -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**
+
+在控制台输出一些调试信息。

docs/src/guide/use/react.md

@@ -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`函数，才可以在切换语言时自动重新渲染组件。
+**注意：**
-
+在组件中直接使用`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)`内容自动替换翻译内容，用来消除冗余内容。
-
 
 ## 第四步：切换语言
 
 接下来在一般我们还需要实现语言切换的功能界面,`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`
 

packages/apps/reactapp/src/components/LanguageConfigurator.jsx

@@ -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 (

packages/babel/package.json

@@ -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"
 }

packages/cli/package.json

@@ -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"
 }

packages/formatters/package.json

@@ -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"
 }

packages/react/index.jsx

@@ -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

packages/react/package.json

@@ -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"
 }

packages/runtime/package.json

@@ -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"
 }

packages/utils/package.json

@@ -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"
 }

packages/vite/package.json

@@ -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"
     }

packages/vue/package.json

@@ -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"
 }

packages/webpack/package.json

@@ -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"
 }