diff --git a/.umirc.ts b/.umirc.ts index 5a9fb15..b120bfa 100644 --- a/.umirc.ts +++ b/.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" ], }, ], diff --git a/docs/src/guide/tools/vite.md b/docs/src/guide/tools/vite.md index 328575b..c036f82 100644 --- a/docs/src/guide/tools/vite.md +++ b/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:[ "!(?/src/languages`文件夹下。 -- `autoImport`：可选的，默认`false`，用来配置是否自动导入`t`函数。当vue文件没有指定导入时才会自动导入，并且根据当前vue文件的路径处理好导入位置。 +- `autoImport`：可选的，用来配置是否自动导入`t`函数。默认`false`代表不自动导入`t`函数。`true`代表自动导入`t`函数。`autoImport=[".<扩展名>",".<扩展名>"]`列出源码扩展名列表，代表仅仅在这些扩展名文件中自动导入`t`函数，如`autoImport=[".js"]`代表仅在js源文件中自动导入`t`函数。 +由于在`typescript`下自动导入`t`函数会导致类型错误提示，所以一般仅建议在`nodejs`下使用。 - `debug`：可选的，开启后会在控制台输出一些调试信息，对一般用户没有用。 diff --git a/docs/src/guide/tools/webpack.md b/docs/src/guide/tools/webpack.md new file mode 100644 index 0000000..0362632 --- /dev/null +++ b/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** + +在控制台输出一些调试信息。 \ No newline at end of file diff --git a/docs/src/guide/use/react.md b/docs/src/guide/use/react.md index 4ba6492..24d79f2 100644 --- a/docs/src/guide/use/react.md +++ b/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`函数，才可以在切换语言时自动重新渲染组件。 - -## 第三步： 自动导入`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 (
-

{t("当前语言")}:{language}

+

{t("当前语言")}:{activeLanguage}

{t("默认语言")}:{defaultLanguage}

{ + {/* 遍历出支持的所有语言 */} languages.map(lang=>{ return (