auto-i18n/auto-i18n-translation-plugins

README

🚀 auto-i18n-translation-plugins

🍉 插件介绍

一个 🎉 前端自动翻译插件，支持所有编译成 JS 的前端框架（例如 Vue2/3 和 React）。无需修改源码，通过支持多种翻译服务，一键轻松实现多语言支持！🌐🚀 默认集成有道翻译和谷歌翻译，同时支持自定义翻译器，兼容 Webpack、Vite、Rollup 等主流构建工具。

🎯 核心优势：

🛠️ 无需改动源码，一键快速翻译多语言；
🌐 支持多种翻译服务（包括 Google 和有道，及自定义翻译器）；
🔍 智能检测需要翻译的文本；
🔧 提供 灵活的配置选项，满足不同项目需求。

tips：有道翻译需要用户自己去申请有道的翻译服务，demo里面的key已经被用完了。

📚 插件调试

  pnpm install
  pnpm run build
  pnpm run preview // 别选react，里面太多英文不好扫

📖 支持范围

框架: 支持所有编译为 JS 的前端框架（如 Vue2/3 和 React 等）。
构建工具: 完美兼容 Webpack、Vite、Rsbuild 和 Rollup 🚀。
翻译服务: 默认支持 有道翻译 和 谷歌翻译，并支持自定义翻译器。

❓ 常见问题

问题文档。

🌟 快速开始 🚀

1️⃣ 安装插件 📦

🌐 Vite 项目:

npm install vite-auto-i18n-plugin --save-dev
# 或
yarn add vite-auto-i18n-plugin --dev

🛠️ Webpack 项目 (兼容 Webpack 4/5):

npm install webpack-auto-i18n-plugin --save-dev
# 或
yarn add webpack-auto-i18n-plugin --dev

⚡ Rsbuild 项目:

npm install rsbuild-auto-i18n-plugin --save-dev
# 或
yarn add rsbuild-auto-i18n-plugin --dev

2️⃣ 语言切换 🌐

⚙️ 基础切换

window.localStorage.setItem('lang', value)
window.location.reload()

// value 是 语言映射对象 的  key 值
// 映射对象默认存在于 lang/index.js 文件下，可以看里面的这部分代码
const langMap = {
  'en': (),
  'zhcn': ()
}

📲 即时切换语言

如果不想通过页面刷新来切换语言，可以直接通过 $changeLang 来修改语言，再重新渲染对应组件

window.$changeLang('en')

例如在 Vue2 中，可以通过以下方式进行语言无刷切换：

<template>
    <div id="app" v-if="isShow">
        <button @click="changeLang('en')">切换到英文</button>
        <button @click="changeLang('zh-cn')">切换到中文</button>
        <router-view></router-view>
    </div>
</template>
<script>
export default {
    data() {
        return {
            isShow: true
        }
    },
    methods: {
        changeLang(lang) {
            window.$changeLang(lang)
            this.isShow = false
            this.$nextTick(() => {
                this.isShow = true
            })
        }
    }
}
</script>

🔄 替换语言包

如果想修改内置生成的语言包，可以直接修改全局对象里面的 langMap，例如：

window.langMap = {
    en: {
        zccsau6: 'hello'
    },
    'zh-cn': {
        zccsau6: '你好'
    }
}

然后再通过上述的即时切换语言的方式进行刷新即可。

3️⃣ 基础配置 🔧

Vite 配置示例 (vite.config.js):

import vitePluginsAutoI18n, { YoudaoTranslator } from 'vite-auto-i18n-plugin'
import vue from '@vitejs/plugin-vue'
import { defineConfig } from 'vite'

export default defineConfig({
    plugins: [
        vue({
            template: {
                compilerOptions: {
                    hoistStatic: false,
                    cacheHandlers: false
                }
            }
        }),
        vitePluginsAutoI18n({
            translator: new YoudaoTranslator({
                appId: '4cdb9baea8066fef',
                appKey: 'ONI6AerZnGRyDqr3w7UM730mPuF8mB3j'
            })
        })
    ]
})

Webpack 配置示例 (webpack.config.js):

const webpackPluginsAutoI18n = require('webpack-auto-i18n-plugin')
const { YoudaoTranslator } = require('webpack-auto-i18n-plugin')

const i18nPlugin = new webpackPluginsAutoI18n.default({
    translator: new YoudaoTranslator({
        appId: '4cdb9baea8066fef',
        appKey: 'ONI6AerZnGRyDqr3w7UM730mPuF8mB3j'
    })
})

module.exports = {
    plugins: [
        new VueLoaderPlugin(),
        new HtmlWebpackPlugin({
            template: './public/index.html'
        }),
        i18nPlugin
    ]
}

Rsbuild 配置示例 (rsbuild.config.js):

const rsbuildPluginsAutoI18n = require('rsbuild-auto-i18n-plugin')
const { YoudaoTranslator } = require('rsbuild-auto-i18n-plugin')

export default defineConfig({
    plugins: [
        pluginReact(),
        rsbuildPluginsAutoI18n({
            targetLangList: ['en'],
            translator: new YoudaoTranslator({
                appId: '4cdb9baea8066fef',
                appKey: 'ONI6AerZnGRyDqr3w7UM730mPuF8mB3j'
            })
        })
    ]
})

4️⃣ 翻译器配置示例 🛠️

插件默认使用谷歌翻译（默认配置代理端口7890）。在网络不支持访问谷歌的情况下，我们推荐使用 有道翻译 ✨，其翻译效果优秀。目前插件已经内置谷歌、有道和百度翻译功能。如果需要自定义翻译器，可参考下方的示例。

以下示例以 vite 为例，webpack、rsbuild 与其类似。

使用谷歌翻译（默认）

import { GoogleTranslator } from 'vite-auto-i18n-plugin'

...
translator: new GoogleTranslator({
    proxyOption: {
        host: '127.0.0.1',
        port: 7890,
        headers: {
            'User-Agent': 'Node'
        }
    }
})
...

使用有道翻译

需要申请api，api文档。

import { YoudaoTranslator } from 'vite-auto-i18n-plugin'

...
translator: new YoudaoTranslator({
    appId: '你申请的appId',
    appKey: '你申请的appKey'
})
...

百度翻译器

需要申请api，api文档。

import { BaiduTranslator } from 'vite-auto-i18n-plugin'

...
translator: new BaiduTranslator({
    appId: '你申请的appId', // 百度翻译 AppId
    appKey: '你申请的appKey' // 百度翻译 AppKey
})
...

火山引擎AI翻译器

支持调用 doubao 或 deepseek 进行翻译，AI大模型的翻译效果会比传统的API翻译更准确，但耗时较长。火山引擎大模型介绍：https://www.volcengine.com/docs/82379/1099455。需要开通大模型服务并申请API，api文档。

import { VolcengineTranslator } from 'vite-auto-i18n-plugin'

...
translator: new VolcengineTranslator({
    apiKey: '你申请的apiKey',
    model: '你要调用的模型，如：`doubao-1-5-pro-32k-250115`，请确保使用前已在控制台开通了对应模型'
})
...

空翻译器

如果只需要扫描目标语言，不进行翻译，该翻译器会生成 JSON 文件。

import { EmptyTranslator } from 'vite-auto-i18n-plugin'

...
translator: new EmptyTranslator()
...

自定义翻译器

如果你有一个自用的翻译接口，可以通过以下方式自定义翻译器——

最简单的方式是使用 Translator 基类定义翻译器实例。

import { Translator } from 'vite-auto-i18n-plugin'
import axios from 'axios'

...
translator: new Translator({
    name: '我的翻译器',
    // 翻译的方法
    fetchMethod: (str, fromKey, toKey, _separator) => {
        // 实际的接口调用可能比示例更复杂，具体可参考源码中YoudaoTranslator的实现，路径：packages\autoI18nPluginCore\src\translators\youdao.ts
        const myApi = 'https://www.my-i18n.cn/api/translate?from=${fromKey}&to=${toKey}&t={+new Date}'
        return axios.post(myApi, { str })
            .then(res => res.data)
    },
    // 接口触发间隔，有些接口频繁触发会被拉黑，请根据实际情况设置一个合理的接口触发间隔
    interval: 1000
})
...

如果需要更高阶的功能，可以使用继承，不过目前无相关场景。

import { Translator } from 'vite-auto-i18n-plugin'

class CustomTranslator extends Translator {
    constructor () {
        super({
            name: '我的翻译器',
            ...
        })
    }
}

...
translator: new CustomTranslator()
...

5️⃣ 项目入口配置 🏗️

请在项目入口文件（如 main.js）的顶部引入语言配置文件：

import '../lang/index.js' // 📍 必须在入口文件中第一行引入，文件会在运行插件时自动生成，默认位于打包配置目录同层的lang文件夹中，其中的index.js就是配置文件

生成的文件说明：

生成的 lang/index.js 文件包含以下全局函数和对象：

window.$t(key, defaultValue, namespace) - 翻译函数
window.$$t(value) - 简单翻译函数（直接返回原值）
window.$deepScan(value) - 深度扫描标记函数（仅在 deepScan: true 时有效）
window.$iS(template, args) - 插值字符串函数（支持 ${0} 或 \${0} 格式的占位符）
window.$changeLang(lang) - 语言切换函数
window.langMap - 语言映射对象

兼容性保证：

从 v1.1.17 开始，所有全局函数和对象都通过智能 fallback 机制挂载，完全兼容低版本浏览器（包括 IE 11）。

⚙️ 配置参数说明

参数	类型	必选	默认值	描述
enabled	boolean	❌	`true`	是否触发翻译。
translateType	string	❌	`full-auto`	翻译状态，默认有两种可选`full-auto` 和 `semi-auto` 。
translateKey	string	✅	`$t`	翻译调用函数名称，例如`$t` 表示翻译调用时的函数名
excludedCall	string[]	❌	`['$i8n', 'require', …]`	标记不会被翻译的函数调用列表
excludedPattern	RegExp[]	❌	`[/\.\w+$/]`	用于标记排除不翻译的字符串模式，例如文件路径中的文件后缀
excludedPath	string[]	❌	`['node_modules']`	指定需要排除翻译的文件夹路径，例如默认会跳过`node_modules`
includePath	RegExp[]	❌	`[/src\//]`	指定只翻译某些目录路径（白名单），默认为`src`
globalPath	string	❌	`'./lang'`	翻译文件配置生成路径
distPath	string	✅	`''`	打包后生成的文件位置路径
distKey	string	✅	`'index'`	打包后生成的翻译主文件名称
namespace	string	✅	`lang`	项目命名空间，用于区分不同项目的翻译配置
originLang	string	✅	`'zh-cn'`	源语言，翻译以此语言为基础
targetLangList	string[]	✅	`['en']`	目标语言列表，支持配置多个语言
buildToDist	boolean	❌	`false`	是否在构建结束后将最新的翻译文件打包到主包中，默认不打包
translator	Translator	❌	`GoogleTranslator`	翻译器实例
translatorOption	object	❌	`{}`	翻译器的配置项，优先级低于`translator`
rewriteConfig	boolean	❌	`true`	插件每次运行时是否重写配置文件
deepScan	boolean	❌	`false`	实验性属性，表示是否进行深层扫描字符串
commonTranslateKey	string	❌	`''`	通用翻译key，用于多个不同命名空间的项目共享同一个语言设置。当设置该值后，语言切换会优先读取localStorage中commonTranslateKey对应的语言，实现跨项目的统一语言管理
insertFileExtensions	string[]	❌	`[]`	要插入翻译代码的文件扩展名列表
isClear	boolean	❌	`false`	是否清除已经不在上下文中的内容（清除项目中不再使用到的源语言键值对）,仅仅支持打包模式下使用
isClearSpace	boolean	❌	`false`	是否清除源字符串中左右两边的空格，默认会保留空格
languageJsonMode	string	❌	`'merged'`	语言JSON存储模式：`'merged'`（所有语言合并到一个index.json）或 `'split'`（每种语言单独一个json文件）

🔍 deepScan 选项的作用？

deepScan 是一个实验性的属性，用于控制插件是否进行深层扫描字符串。默认情况下，插件会扫描字符串或者模版字符串，只需要里面存在一个目标语言就会被扫进去，比如：

;`<div>
    <p>你好</p>
</div>`

因为里面有一个中文，所以整个字符串会被扫进去，可能会导致翻译不准确，因为我们只想翻译你好这个字符串，所以我们可以设置deepScan为true，插件会对字符串进行切割，重新拼接成模版字符串，值对符合的字符串进行翻译，比如：

;`<div>
    <p>${$t('你好')}</p>
</div>`

这样就只会翻译你好这个字符串，而不会翻译整个字符串。

🔥 $deepScan 函数的使用

在启用 deepScan: true 后，插件会自动生成 $deepScan 全局函数。此函数用于标记需要深度扫描的模板字符串：

// 使用 $deepScan 包裹模板字符串
const template = $deepScan(`
    <div class="container">
        <h1>欢迎使用</h1>
        <p>这是一个测试</p>
    </div>
`)

// 插件会自动转换为：
const template = `
    <div class="container">
        <h1>${$t('欢迎使用')}</h1>
        <p>${$t('这是一个测试')}</p>
    </div>
`

注意事项：

$deepScan 在运行时仅返回原始值，不做任何处理
主要用于在编译时告诉插件需要对该字符串进行深度扫描
只在 deepScan: true 配置下生效

🌐 全局对象兼容性说明

从 v1.1.17 版本开始，生成的翻译配置文件 (lang/index.js) 已经完全兼容低版本浏览器，包括 IE 11。

兼容性机制

插件使用以下 fallback 优先级获取全局对象：

globalThis - 现代浏览器（ES2020+）
window - 浏览器环境（兼容 IE 11+）
global - Node.js 环境
self - Web Workers 环境

支持的浏览器版本

✅ Chrome 49+
✅ Firefox 52+
✅ Safari 10+
✅ Edge 12+
✅ IE 11
✅ 所有现代浏览器

无需额外配置，生成的文件会自动处理兼容性问题。

👋 translateType 选项的作用

translateType 是 v1.0.11 新增的属性，有两个可选值full-auto 和 semi-auto 。

full-auto 第一个是全自动翻译，默认来源语言只支持中日韩俄四种语言。

semi-auto 第二个半自动翻译，支持所有来源语言。

使用 semi-auto 时，用户需要主动去使用translateKey对目标字符进行包裹，比如 $t('hello')，插件会自动完成翻译。

例子：

const HelloWorld: React.FC<HelloWorldProps> = ({ name = 'World' }) => {
    return (
        <div className="hello-world">
            <h1>
                {$t('Hello,')} {name}!
            </h1>
            <p>{$t('Welcome to our application')}</p>
        </div>
    )
}

❓ 为什么需要 `buildToDist`？

在 Vite 环境中，插件执行后仅会生成翻译配置文件。如果直接构建，虽然翻译配置文件已生成，但默认不会立即将之打包到主包中。⚠️ 因此提供了 buildToDist 选项，可在构建时主动将翻译文件打包到主包中。但需要注意，这可能导致您的项目中生成两份翻译配置文件。

🔄 如何更新翻译？

完成插件运行后，\lang 目录会生成两个文件：index.js 和 index.json。

index.js：存储翻译相关的函数逻辑。
index.json：存储翻译文本内容。

如果需要更新翻译内容，可以直接修改 index.json 文件内容。

⚠️ 使用注意事项

代理要求
- 国内使用，强烈推荐使用有道翻译
- 使用谷歌翻译的功能时，国内用户必须配置代理环境。
- 默认代理端口为 7890。
- 可通过 proxyOption 参数自定义代理端口。
翻译频率
- 谷歌翻译是免费服务，但频繁请求可能触发使用限制 🔒。
- 建议设置一个适当的时间间隔再发起新的翻译请求 💡。
翻译更新机制
- globalPath 目录中的 index.json 是核心翻译文件。
- 修改并保存后，您的翻译内容将立即更新。
JSON 存储模式切换 ⚠️
- 当切换 languageJsonMode 配置（merged ↔ split）时，强烈建议将 rewriteConfig 设置为 true。
- 这样可以确保插件重新生成配置文件，避免新旧模式文件冲突导致的错误。
- 切换模式后，插件会自动处理 JSON 文件的合并或拆分。

📦 用户群

微信群已满，使用QQ群

📦 示例项目

☁️ 示例项目参考仓库：example（点击查看）

📜 许可证

本插件基于 MIT License 开源协议 🪪。自由使用，欢迎贡献！

希望它能让您的国际化开发变得更加简单和高效！🌍✨

✨ 更新

自 1.0.5 版本起，用户只需在入口文件中引入插件生成文件夹下的 index.js 文件，无需再手动构建语言切换函数文件。👏

🎆 作者

原始作者：wenps、xu-code、Caleb-Xu、Winfans

更新日志

v1.1.17 (最新版本)

新增全局对象兼容性增强：生成的翻译配置文件现在支持低版本浏览器（IE 11+），通过 globalThis → window → global → self 的 fallback 机制确保兼容性
优化 deepScan 功能：新增 $deepScan 全局函数，用于标记模板字符串中需要深度扫描的部分，提升翻译精准度
改进代码结构：优化翻译函数生成逻辑，所有代码封装在 IIFE 中，避免全局作用域污染

v1.1.16 (推荐版本)

修复模板字符串内部出现"导致生成id映射异常问题

v1.1.15 (推荐版本)

补充node14兼容

v1.1.14 (推荐版本)

修复rewriteConfig异常问题

v1.1.13 (不推荐版本)

新增json拆分配置

v1.1.12 (推荐版本)

优化控制台输出格式

v1.1.11 (推荐版本)

优化控制台输出格式，减少冗余打印
新增翻译进度条显示
支持 Webpack 4

v1.1.10 (推荐版本)

新增 rsbuild 插件

v1.1.9 (推荐版本)

修复 deepScan 切分字符串不处理换行符等问题

v1.1.8 (推荐版本)

是否支持清除前后空格配置重命名

v1.1.7 (推荐版本)

enable 能力兼容翻译初始化补全
新增扫描是否支持清除前后空格配置
修复异常触发新增翻译问题
修复清理配置异常不生效问题

v1.1.6 (推荐版本)

修复模板字符串前后空格清空导致 JSON 对应不上翻译函数的问题
修复插值中文括号导致插值失效的问题
新增清理配置功能

v1.1.5 (推荐版本)

支持插值翻译

v1.1.4 (推荐版本)

修复排除函数处理模版字符串异常问题
谷歌新增interval配置
新增翻译器支持自定义接口入参

v1.1.3 (推荐版本)

新增无刷更新语言能力及最佳实践

v1.1.2

修复ai翻译异常

v1.1.1

新增翻译禁用功能

v1.1.0

新增ai翻译器
新增翻译插件vue2拓展插件机制

v1.0.26 (推荐版本)

新增自定义拓展名数组

v1.0.25 (推荐版本)

新增通用翻译key

v1.0.24 (推荐版本)

修复半自动模式异常问题

v1.0.23 (推荐版本)

修复打包写入重大bug

v1.0.22

新增扫描翻译器

v1.0.21

新增深度扫描

v1.0.20

修复过滤函数异常问题，以及补充是否覆盖生成配置文件项

v1.0.19

配置文件兼容旧版本

v1.0.18

修复了低版本 Node 中可选链操作导致运行时异常的问题。

v1.0.17

支持基本的服务器端渲染（实验性）

v1.0.16

修复已知问题（vue3注释节点）

v1.0.15

新增百度翻译

v1.0.14

修复新增语言类型，不主动切割问题
自动翻译能力新增日语，韩语，俄语

v1.0.13

已知问题修复

v1.0.12

优化类型

v1.0.11

修复已知缺陷
新增翻译状态选项，支持半自动状态

// 用户可以用 translateKey 包裹需要翻译的文案
// 如：$t('hello')，插件会扫描这些文案并实现自动翻译

$t('hello')

README

🚀 auto-i18n-translation-plugins

English Documentation

🍉 插件介绍

🎯 核心优势：

🛠️ 无需改动源码，一键快速翻译多语言；
🌐 支持多种翻译服务（包括 Google 和有道，及自定义翻译器）；
🔍 智能检测需要翻译的文本；
🔧 提供 灵活的配置选项，满足不同项目需求。

tips：有道翻译需要用户自己去申请有道的翻译服务，demo里面的key已经被用完了。

📚 插件调试

  pnpm install
  pnpm run build
  pnpm run preview // 别选react，里面太多英文不好扫

📖 支持范围

框架: 支持所有编译为 JS 的前端框架（如 Vue2/3 和 React 等）。
构建工具: 完美兼容 Webpack、Vite、Rsbuild 和 Rollup 🚀。
翻译服务: 默认支持 有道翻译 和 谷歌翻译，并支持自定义翻译器。

❓ 常见问题

问题文档。

🌟 快速开始 🚀

1️⃣ 安装插件 📦

🌐 Vite 项目:

npm install vite-auto-i18n-plugin --save-dev
# 或
yarn add vite-auto-i18n-plugin --dev

🛠️ Webpack 项目 (兼容 Webpack 4/5):

npm install webpack-auto-i18n-plugin --save-dev
# 或
yarn add webpack-auto-i18n-plugin --dev

⚡ Rsbuild 项目:

npm install rsbuild-auto-i18n-plugin --save-dev
# 或
yarn add rsbuild-auto-i18n-plugin --dev

2️⃣ 语言切换 🌐

⚙️ 基础切换

window.localStorage.setItem('lang', value)
window.location.reload()

// value 是 语言映射对象 的  key 值
// 映射对象默认存在于 lang/index.js 文件下，可以看里面的这部分代码
const langMap = {
  'en': (),
  'zhcn': ()
}

📲 即时切换语言

如果不想通过页面刷新来切换语言，可以直接通过 $changeLang 来修改语言，再重新渲染对应组件

window.$changeLang('en')

例如在 Vue2 中，可以通过以下方式进行语言无刷切换：

<template>
    <div id="app" v-if="isShow">
        <button @click="changeLang('en')">切换到英文</button>
        <button @click="changeLang('zh-cn')">切换到中文</button>
        <router-view></router-view>
    </div>
</template>
<script>
export default {
    data() {
        return {
            isShow: true
        }
    },
    methods: {
        changeLang(lang) {
            window.$changeLang(lang)
            this.isShow = false
            this.$nextTick(() => {
                this.isShow = true
            })
        }
    }
}
</script>

🔄 替换语言包

如果想修改内置生成的语言包，可以直接修改全局对象里面的 langMap，例如：

window.langMap = {
    en: {
        zccsau6: 'hello'
    },
    'zh-cn': {
        zccsau6: '你好'
    }
}

然后再通过上述的即时切换语言的方式进行刷新即可。

3️⃣ 基础配置 🔧

Vite 配置示例 (vite.config.js):

import vitePluginsAutoI18n, { YoudaoTranslator } from 'vite-auto-i18n-plugin'
import vue from '@vitejs/plugin-vue'
import { defineConfig } from 'vite'

export default defineConfig({
    plugins: [
        vue({
            template: {
                compilerOptions: {
                    hoistStatic: false,
                    cacheHandlers: false
                }
            }
        }),
        vitePluginsAutoI18n({
            translator: new YoudaoTranslator({
                appId: '4cdb9baea8066fef',
                appKey: 'ONI6AerZnGRyDqr3w7UM730mPuF8mB3j'
            })
        })
    ]
})

Webpack 配置示例 (webpack.config.js):

const webpackPluginsAutoI18n = require('webpack-auto-i18n-plugin')
const { YoudaoTranslator } = require('webpack-auto-i18n-plugin')

const i18nPlugin = new webpackPluginsAutoI18n.default({
    translator: new YoudaoTranslator({
        appId: '4cdb9baea8066fef',
        appKey: 'ONI6AerZnGRyDqr3w7UM730mPuF8mB3j'
    })
})

module.exports = {
    plugins: [
        new VueLoaderPlugin(),
        new HtmlWebpackPlugin({
            template: './public/index.html'
        }),
        i18nPlugin
    ]
}

Rsbuild 配置示例 (rsbuild.config.js):

const rsbuildPluginsAutoI18n = require('rsbuild-auto-i18n-plugin')
const { YoudaoTranslator } = require('rsbuild-auto-i18n-plugin')

export default defineConfig({
    plugins: [
        pluginReact(),
        rsbuildPluginsAutoI18n({
            targetLangList: ['en'],
            translator: new YoudaoTranslator({
                appId: '4cdb9baea8066fef',
                appKey: 'ONI6AerZnGRyDqr3w7UM730mPuF8mB3j'
            })
        })
    ]
})

4️⃣ 翻译器配置示例 🛠️

以下示例以 vite 为例，webpack、rsbuild 与其类似。

使用谷歌翻译（默认）

import { GoogleTranslator } from 'vite-auto-i18n-plugin'

...
translator: new GoogleTranslator({
    proxyOption: {
        host: '127.0.0.1',
        port: 7890,
        headers: {
            'User-Agent': 'Node'
        }
    }
})
...

使用有道翻译

需要申请api，api文档。

import { YoudaoTranslator } from 'vite-auto-i18n-plugin'

...
translator: new YoudaoTranslator({
    appId: '你申请的appId',
    appKey: '你申请的appKey'
})
...

百度翻译器

需要申请api，api文档。

import { BaiduTranslator } from 'vite-auto-i18n-plugin'

...
translator: new BaiduTranslator({
    appId: '你申请的appId', // 百度翻译 AppId
    appKey: '你申请的appKey' // 百度翻译 AppKey
})
...

火山引擎AI翻译器

import { VolcengineTranslator } from 'vite-auto-i18n-plugin'

...
translator: new VolcengineTranslator({
    apiKey: '你申请的apiKey',
    model: '你要调用的模型，如：`doubao-1-5-pro-32k-250115`，请确保使用前已在控制台开通了对应模型'
})
...

空翻译器

如果只需要扫描目标语言，不进行翻译，该翻译器会生成 JSON 文件。

import { EmptyTranslator } from 'vite-auto-i18n-plugin'

...
translator: new EmptyTranslator()
...

自定义翻译器

如果你有一个自用的翻译接口，可以通过以下方式自定义翻译器——

最简单的方式是使用 Translator 基类定义翻译器实例。

import { Translator } from 'vite-auto-i18n-plugin'
import axios from 'axios'

...
translator: new Translator({
    name: '我的翻译器',
    // 翻译的方法
    fetchMethod: (str, fromKey, toKey, _separator) => {
        // 实际的接口调用可能比示例更复杂，具体可参考源码中YoudaoTranslator的实现，路径：packages\autoI18nPluginCore\src\translators\youdao.ts
        const myApi = 'https://www.my-i18n.cn/api/translate?from=${fromKey}&to=${toKey}&t={+new Date}'
        return axios.post(myApi, { str })
            .then(res => res.data)
    },
    // 接口触发间隔，有些接口频繁触发会被拉黑，请根据实际情况设置一个合理的接口触发间隔
    interval: 1000
})
...

如果需要更高阶的功能，可以使用继承，不过目前无相关场景。

import { Translator } from 'vite-auto-i18n-plugin'

class CustomTranslator extends Translator {
    constructor () {
        super({
            name: '我的翻译器',
            ...
        })
    }
}

...
translator: new CustomTranslator()
...

5️⃣ 项目入口配置 🏗️

请在项目入口文件（如 main.js）的顶部引入语言配置文件：

import '../lang/index.js' // 📍 必须在入口文件中第一行引入，文件会在运行插件时自动生成，默认位于打包配置目录同层的lang文件夹中，其中的index.js就是配置文件

生成的文件说明：

生成的 lang/index.js 文件包含以下全局函数和对象：

window.$t(key, defaultValue, namespace) - 翻译函数
window.$$t(value) - 简单翻译函数（直接返回原值）
window.$deepScan(value) - 深度扫描标记函数（仅在 deepScan: true 时有效）
window.$iS(template, args) - 插值字符串函数（支持 ${0} 或 \${0} 格式的占位符）
window.$changeLang(lang) - 语言切换函数
window.langMap - 语言映射对象

兼容性保证：

从 v1.1.17 开始，所有全局函数和对象都通过智能 fallback 机制挂载，完全兼容低版本浏览器（包括 IE 11）。

⚙️ 配置参数说明

参数	类型	必选	默认值	描述
enabled	boolean	❌	`true`	是否触发翻译。
translateType	string	❌	`full-auto`	翻译状态，默认有两种可选`full-auto` 和 `semi-auto` 。
translateKey	string	✅	`$t`	翻译调用函数名称，例如`$t` 表示翻译调用时的函数名
excludedCall	string[]	❌	`['$i8n', 'require', …]`	标记不会被翻译的函数调用列表
excludedPattern	RegExp[]	❌	`[/\.\w+$/]`	用于标记排除不翻译的字符串模式，例如文件路径中的文件后缀
excludedPath	string[]	❌	`['node_modules']`	指定需要排除翻译的文件夹路径，例如默认会跳过`node_modules`
includePath	RegExp[]	❌	`[/src\//]`	指定只翻译某些目录路径（白名单），默认为`src`
globalPath	string	❌	`'./lang'`	翻译文件配置生成路径
distPath	string	✅	`''`	打包后生成的文件位置路径
distKey	string	✅	`'index'`	打包后生成的翻译主文件名称
namespace	string	✅	`lang`	项目命名空间，用于区分不同项目的翻译配置
originLang	string	✅	`'zh-cn'`	源语言，翻译以此语言为基础
targetLangList	string[]	✅	`['en']`	目标语言列表，支持配置多个语言
buildToDist	boolean	❌	`false`	是否在构建结束后将最新的翻译文件打包到主包中，默认不打包
translator	Translator	❌	`GoogleTranslator`	翻译器实例
translatorOption	object	❌	`{}`	翻译器的配置项，优先级低于`translator`
rewriteConfig	boolean	❌	`true`	插件每次运行时是否重写配置文件
deepScan	boolean	❌	`false`	实验性属性，表示是否进行深层扫描字符串
commonTranslateKey	string	❌	`''`	通用翻译key，用于多个不同命名空间的项目共享同一个语言设置。当设置该值后，语言切换会优先读取localStorage中commonTranslateKey对应的语言，实现跨项目的统一语言管理
insertFileExtensions	string[]	❌	`[]`	要插入翻译代码的文件扩展名列表
isClear	boolean	❌	`false`	是否清除已经不在上下文中的内容（清除项目中不再使用到的源语言键值对）,仅仅支持打包模式下使用
isClearSpace	boolean	❌	`false`	是否清除源字符串中左右两边的空格，默认会保留空格
languageJsonMode	string	❌	`'merged'`	语言JSON存储模式：`'merged'`（所有语言合并到一个index.json）或 `'split'`（每种语言单独一个json文件）

🔍 deepScan 选项的作用？

;`<div>
    <p>你好</p>
</div>`

;`<div>
    <p>${$t('你好')}</p>
</div>`

这样就只会翻译你好这个字符串，而不会翻译整个字符串。

🔥 $deepScan 函数的使用

在启用 deepScan: true 后，插件会自动生成 $deepScan 全局函数。此函数用于标记需要深度扫描的模板字符串：

// 使用 $deepScan 包裹模板字符串
const template = $deepScan(`
    <div class="container">
        <h1>欢迎使用</h1>
        <p>这是一个测试</p>
    </div>
`)

// 插件会自动转换为：
const template = `
    <div class="container">
        <h1>${$t('欢迎使用')}</h1>
        <p>${$t('这是一个测试')}</p>
    </div>
`

注意事项：

$deepScan 在运行时仅返回原始值，不做任何处理
主要用于在编译时告诉插件需要对该字符串进行深度扫描
只在 deepScan: true 配置下生效

🌐 全局对象兼容性说明

从 v1.1.17 版本开始，生成的翻译配置文件 (lang/index.js) 已经完全兼容低版本浏览器，包括 IE 11。

兼容性机制

插件使用以下 fallback 优先级获取全局对象：

globalThis - 现代浏览器（ES2020+）
window - 浏览器环境（兼容 IE 11+）
global - Node.js 环境
self - Web Workers 环境

支持的浏览器版本

✅ Chrome 49+
✅ Firefox 52+
✅ Safari 10+
✅ Edge 12+
✅ IE 11
✅ 所有现代浏览器

无需额外配置，生成的文件会自动处理兼容性问题。

👋 translateType 选项的作用

translateType 是 v1.0.11 新增的属性，有两个可选值full-auto 和 semi-auto 。

full-auto 第一个是全自动翻译，默认来源语言只支持中日韩俄四种语言。

semi-auto 第二个半自动翻译，支持所有来源语言。

使用 semi-auto 时，用户需要主动去使用translateKey对目标字符进行包裹，比如 $t('hello')，插件会自动完成翻译。

例子：

const HelloWorld: React.FC<HelloWorldProps> = ({ name = 'World' }) => {
    return (
        <div className="hello-world">
            <h1>
                {$t('Hello,')} {name}!
            </h1>
            <p>{$t('Welcome to our application')}</p>
        </div>
    )
}

❓ 为什么需要 `buildToDist`？

🔄 如何更新翻译？

完成插件运行后，\lang 目录会生成两个文件：index.js 和 index.json。

index.js：存储翻译相关的函数逻辑。
index.json：存储翻译文本内容。

如果需要更新翻译内容，可以直接修改 index.json 文件内容。

⚠️ 使用注意事项

代理要求
- 国内使用，强烈推荐使用有道翻译
- 使用谷歌翻译的功能时，国内用户必须配置代理环境。
- 默认代理端口为 7890。
- 可通过 proxyOption 参数自定义代理端口。
翻译频率
- 谷歌翻译是免费服务，但频繁请求可能触发使用限制 🔒。
- 建议设置一个适当的时间间隔再发起新的翻译请求 💡。
翻译更新机制
- globalPath 目录中的 index.json 是核心翻译文件。
- 修改并保存后，您的翻译内容将立即更新。
JSON 存储模式切换 ⚠️
- 当切换 languageJsonMode 配置（merged ↔ split）时，强烈建议将 rewriteConfig 设置为 true。
- 这样可以确保插件重新生成配置文件，避免新旧模式文件冲突导致的错误。
- 切换模式后，插件会自动处理 JSON 文件的合并或拆分。

📦 用户群

微信群已满，使用QQ群

📦 示例项目

☁️ 示例项目参考仓库：example（点击查看）

📜 许可证

本插件基于 MIT License 开源协议 🪪。自由使用，欢迎贡献！

希望它能让您的国际化开发变得更加简单和高效！🌍✨

✨ 更新

自 1.0.5 版本起，用户只需在入口文件中引入插件生成文件夹下的 index.js 文件，无需再手动构建语言切换函数文件。👏

🎆 作者

原始作者：wenps、xu-code、Caleb-Xu、Winfans

更新日志

v1.1.17 (最新版本)

新增全局对象兼容性增强：生成的翻译配置文件现在支持低版本浏览器（IE 11+），通过 globalThis → window → global → self 的 fallback 机制确保兼容性
优化 deepScan 功能：新增 $deepScan 全局函数，用于标记模板字符串中需要深度扫描的部分，提升翻译精准度
改进代码结构：优化翻译函数生成逻辑，所有代码封装在 IIFE 中，避免全局作用域污染

v1.1.16 (推荐版本)

修复模板字符串内部出现"导致生成id映射异常问题

v1.1.15 (推荐版本)

补充node14兼容

v1.1.14 (推荐版本)

修复rewriteConfig异常问题

v1.1.13 (不推荐版本)

新增json拆分配置

v1.1.12 (推荐版本)

优化控制台输出格式

v1.1.11 (推荐版本)

优化控制台输出格式，减少冗余打印
新增翻译进度条显示
支持 Webpack 4

v1.1.10 (推荐版本)

新增 rsbuild 插件

v1.1.9 (推荐版本)

修复 deepScan 切分字符串不处理换行符等问题

v1.1.8 (推荐版本)

是否支持清除前后空格配置重命名

v1.1.7 (推荐版本)

enable 能力兼容翻译初始化补全
新增扫描是否支持清除前后空格配置
修复异常触发新增翻译问题
修复清理配置异常不生效问题

v1.1.6 (推荐版本)

修复模板字符串前后空格清空导致 JSON 对应不上翻译函数的问题
修复插值中文括号导致插值失效的问题
新增清理配置功能

v1.1.5 (推荐版本)

支持插值翻译

v1.1.4 (推荐版本)

修复排除函数处理模版字符串异常问题
谷歌新增interval配置
新增翻译器支持自定义接口入参

v1.1.3 (推荐版本)

新增无刷更新语言能力及最佳实践

v1.1.2

修复ai翻译异常

v1.1.1

新增翻译禁用功能

v1.1.0

新增ai翻译器
新增翻译插件vue2拓展插件机制

v1.0.26 (推荐版本)

新增自定义拓展名数组

v1.0.25 (推荐版本)

新增通用翻译key

v1.0.24 (推荐版本)

修复半自动模式异常问题

v1.0.23 (推荐版本)

修复打包写入重大bug

v1.0.22

新增扫描翻译器

v1.0.21

新增深度扫描

v1.0.20

修复过滤函数异常问题，以及补充是否覆盖生成配置文件项

v1.0.19

配置文件兼容旧版本

v1.0.18

修复了低版本 Node 中可选链操作导致运行时异常的问题。

v1.0.17

支持基本的服务器端渲染（实验性）

v1.0.16

修复已知问题（vue3注释节点）

v1.0.15

新增百度翻译

v1.0.14

修复新增语言类型，不主动切割问题
自动翻译能力新增日语，韩语，俄语

v1.0.13

已知问题修复

v1.0.12

优化类型

v1.0.11

修复已知缺陷
新增翻译状态选项，支持半自动状态

// 用户可以用 translateKey 包裹需要翻译的文案
// 如：$t('hello')，插件会扫描这些文案并实现自动翻译

$t('hello')