diff --git a/docs/src/guide/advanced/autoimport.md b/docs/src/guide/advanced/autoimport.md index 5eae4be..c1deb55 100644 --- a/docs/src/guide/advanced/autoimport.md +++ b/docs/src/guide/advanced/autoimport.md @@ -19,7 +19,7 @@ import { t } from "../../../languages" 为此,我们提供了插件可以来自动完成翻译函数的自动导入,包括: -- (Babel插件)[../tools/babel] -- (Vite插件)[../tools/vite] +- [Babel插件](../tools/babel) +- [Vite插件](../tools/vite) 当启用了`babel/vite`插件后,就会在编译时自动导入`t`函数。关于插件如何使用请参阅文档。 diff --git a/docs/src/guide/intro/history.md b/docs/src/guide/intro/history.md index fb0cdd9..5f3c158 100644 --- a/docs/src/guide/intro/history.md +++ b/docs/src/guide/intro/history.md @@ -1,9 +1,15 @@ # 更新日志 +## 2023/1/24 + +- `@voerkai18n/vite`默认不自动导入`t`函数 +- 重构`@voerkai18n/vue`,详见`指南`介绍 +- 新增`typescript`的`vue`例子 + ## 2023/1/11 - 重构`@voerkai18n/react`,支持自动重新渲染 -- 修复`@voerkai18n/vite`插件在转码`jsx`组件时存在的idMap错误 +- 修复`@voerkai18n/vite`插件在转码`jsx`组件时存在的`idMap`错误 ## 2023/1/10 diff --git a/docs/src/guide/tools/vite.md b/docs/src/guide/tools/vite.md index 3005b68..328575b 100644 --- a/docs/src/guide/tools/vite.md +++ b/docs/src/guide/tools/vite.md @@ -35,9 +35,28 @@ export default defineConfig({ ## 插件功能 -`@voerkai18n/vite`插件配置启用后,`vite`在进行`dev`或`build`时,就会在``自动注入`import { t } from "languages" `,同时会扫描源代码文件(包括`vue`,`js`等),根据`idMap.js`文件里面的文本映射表,将`t('"xxxx")`转换成`t("")`的形式。 +### 文本映射 -不同于`@voerkai18n/babel`插件,`@voerkai18n/vite`插件不需要配置`location`和`autoImport`参数,能正确地处理导入`languages`路径。 +- `@voerkai18n/vite`插件配置启用后,同时会扫描源代码文件(包括`vue`,`js`等),根据`idMap.js`文件里面的文本映射表,将`t('"xxxx")`转换成`t("")`的形式。 + +### 自动导入`t`函数 + +针对`js`文件,能通过指定`autoImport=true`来自动导入`t`函数。我们知道本质上翻译就是导入执行`t`函数,这样在一个复杂应用中可能就会存在这样的导入 + +```javascript | pure +import { t } from "languages" +import { t } from "../languages" +import { t } from "../../languages" +import { t } from "../../../languages" +import { t } from "../../languages" +``` + +`@voerkai18n/vite`插件可以实现自动导入功能,在`js`文件中不需要导入该函数,而是由`@voerkai18n/vite`插件在翻译阶段根据当前文件是否有使用了`t`函数而自动导入。 + +**注意:** +- 自动导入默认是关闭的,需要手动配置`@voerkai18n/vite`插件的参数`autoImport=true`才能生效。 +- 对于使用`typescript`开发则不建议开启自动导入功能,因此这会导入类型的丢失。 +- 不同于`@voerkai18n/babel`插件,`@voerkai18n/vite`插件不需要配置`location`和`autoImport`参数,能正确地处理导入`languages`路径。 ## 插件参数 @@ -50,7 +69,7 @@ export default defineConfig({ Inspect(), // 可选的 Voerkai18nPlugin({ location: "./", // 可选的,指定当前工程目录 - autoImport: true, // 是否自动导入t函数 + autoImport: false, // 是否自动导入t函数 debug:false, // 是否输出调试信息,当=true时,在控制台输出转换匹配的文件清单 patterns:[ "!(?/src/languages`文件夹下。 -- `autoImport`:可选的,默认`true`,用来配置是否自动导入`t`函数。当vue文件没有指定导入时才会自动导入,并且根据当前vue文件的路径处理好导入位置。 +- `autoImport`:可选的,默认`false`,用来配置是否自动导入`t`函数。当vue文件没有指定导入时才会自动导入,并且根据当前vue文件的路径处理好导入位置。 - `debug`:可选的,开启后会在控制台输出一些调试信息,对一般用户没有用。 diff --git a/docs/src/guide/use/vue.md b/docs/src/guide/use/vue.md index f9f6585..fb52856 100644 --- a/docs/src/guide/use/vue.md +++ b/docs/src/guide/use/vue.md @@ -1,9 +1,6 @@ # Vue应用 - -创建`Vue`应用可以采用`Vite`或`Vue Cli`来创建工程。 - -在`Vue3`应用中引入`voerkai18n`来添加国际化应用需要由两个插件来简化应用。 +创建`Vue`应用一般采用`Vite`或`Vue Cli`来创建工程。在`Vue3`应用中引入`voerkai18n`来添加国际化应用需要由两个插件来简化应用。 - **@voerkai18n/vue** @@ -11,7 +8,7 @@ - **@voerkai18n/vite** - **Vite插件**,在`vite.config.js`中配置,用来实现`自动文本映射`、`自动导入t函数`等功能。 + **Vite插件**,在`vite.config.js`中配置,用来实现`自动文本映射`等功能。 `@voerkai18n/vue`和`@voerkai18n/vite`两件插件相互配合,安装配置好这两个插件后,就可以在`Vue`文件使用多语言`t`函数。 @@ -27,35 +24,71 @@ > voerka18n init // 提取要翻译的文本到src/languages/translates/*.json > voerkai18n extract -// 进行人工翻译或自动翻译(百度) +// 可选,进行人工翻译或自动翻译(百度) > voerkai18n translate --apikey xxxx --apiid xxxxx // 编译语言包 > voerkai18n compile ``` -## 第二步:导入`t`翻译函数 -无论采用何种工具创建`Vite`应用,均可以直接从`languages`直接导入`t`函数。 +## 第二步:配置`@voerkai18n/vite`插件 -```vue - -``` -取决于您是从哪一个文件中导入,需要修改导入位置,可能类似这样: -```javascript | pure -import { t } from "./languages" -import { t } from "../languages" -import { t } from "../../languages" -import { t } from "../../../languages" -``` +`@voerkai18n/vite`插件可以根据`idMap.ts`映射文件将源码中的`t("xxxxx")`转换为`t("<数字>")`的形式,从而实现消除翻译内容的冗余内容。 -导入`t`函数后就可以直接使用了。 +`@voerkai18n/vite`插件的安装非常简单,只需要在`vite.config.(ts|js)`中添加如下内容: ```javascript | pure + +import { defineConfig } from 'vite' +import vue from '@vitejs/plugin-vue' +import Inspect from 'vite-plugin-inspect' +import Voerkai18nPlugin from "@voerkai18n/vite" + +export default defineConfig({ + plugins: [ + Inspect(), // 可选 + Voerkai18nPlugin(), + vue()], +}) + +``` +`@voerkai18n/vite`插件仅在开发和构建阶段作用。事实上,如果不在乎文本内容的冗余,不安装此插件也是可以工作正常的。 + +## 第三步:配置`@voerkai18n/vue`插件 + +`@voerkai18n/vue`插件用来自动注入`t`函数、切换语言等功能。 + +安装方法如下: + +```javascript pure +import { createApp } from 'vue' +import './style.css' +import App from './App.vue' +// 导入插件 +import i18nPlugin from '@voerkai18n/vue' +// 导入当前作用域 +import { i18nScope } from './languages' + +const app = createApp(App) +// 应用插件 +app.use(i18nPlugin,{i18nScope}) +app.mount('#app') + +``` + +`@voerkai18n/vue`插件本质上是为每一个Vue组件自动混入`t`函数。 + +## 第四步:使用`t`翻译函数 + +`Vue`应用使用多语言本质是调用`import { t } from 'langauges`导入的`t`函数来进行翻译。 + +```javascript | pure + +// 在setup中需要手动导入t函数 +// 直接使用t函数,不需要导入 +// 直接使用 ``` - -## 第三步:自动导入`t`翻译函数 - -当源码文件非常多时,手动导入`t`函数比较麻烦,我们提供了`vite`和`babel`两个插件可以实现自动导入`t`函数。 -如果应用是采用`Vite`+`@vitejs/plugin-vite`创建的工程,则可以通过配置`@voerkai18n/vite`插件实现自动导入`t`函数。 - -详见`@voerkai18n/vite`插件介绍。 + +**重点:** +- 在` -```javascript | pure ``` + -**说明:** +## 小结 + +- `@voerkai18n/vue`插件为`Vue`单文件组件提供自动注入`t`函数,可以在`