mirror of https://github.com/allinssl/allinssl
304 lines
16 KiB
Markdown
304 lines
16 KiB
Markdown
一、概述
|
||
本项目是一个 Vite 插件，主要用于实现 i18n（国际化）自动化翻译功能。它会自动扫描项目文件，精准抓取 vue - i18n 的 $t 模板变量里的中文内容，借助不同的翻译服务（包括传统 API 翻译和 AI 批量翻译）进行翻译，并生成对应的翻译文件。同时，插件具备缓存机制，能有效加速对重复内容的处理，还可清理缓存文件中的无效数据。翻译过程采用并发模式，并发上限为 200，以提高处理效率。在扫描文件前，会同步缓存的状态配置，确保数据的一致性。各模块采用正交性设计，保证了系统的可维护性和扩展性。
|
||
二、技术选型
|
||
项目类型：Vite 插件
|
||
Vite 版本：Vite 4.x 及以上，以充分利用其快速构建和热更新特性。
|
||
Vue 版本：Vue 3.x，借助其响应式系统和组合式 API 提升开发效率。
|
||
vue - i18n 版本：vue - i18n 9.x，适配 Vue 3 实现国际化支持。
|
||
翻译服务：支持智谱 AI 等多种 AI 翻译服务以及传统 API 翻译服务，提供多样化的翻译选择。
|
||
Lodash：用于数组处理等操作，简化复杂的数据处理逻辑。
|
||
FS Promises：用于文件操作的异步处理，避免阻塞主线程。
|
||
Axios：用于发送 HTTP 请求，与翻译服务进行通信。
|
||
三、整体架构
|
||
目录架构图
|
||
plaintext
|
||
vite-plugin-i18n-ai-translate/
|
||
├── src/
|
||
│ ├── fileOperation/ # 文件操作模块
|
||
│ │ ├── index.js
|
||
│ │ └── ...
|
||
│ ├── translation/ # 翻译模块
|
||
│ │ ├── index.js
|
||
│ │ ├── adapter/ # 翻译适配器模块
|
||
│ │ │ ├── index.js
|
||
│ │ │ ├── traditionalApiAdapter.js # 传统 API 翻译适配器
|
||
│ │ │ ├── aiBatchAdapter.js # AI 批量翻译适配器
|
||
│ │ │ └── ...
|
||
│ │ ├── ai/ # AI 翻译模块集合
|
||
│ │ │ ├── zhipuAI.js # 智谱 AI 翻译模块
|
||
│ │ │ ├── otherAI.js # 其他 AI 翻译模块示例
|
||
│ │ │ └── ...
|
||
│ │ └── traditional/ # 传统 API 翻译模块集合
|
||
│ │ ├── api1.js # 传统 API 1 翻译模块
|
||
│ │ ├── api2.js # 传统 API 2 翻译模块
|
||
│ │ └── ...
|
||
│ ├── stateManagement/ # 状态管理模块
|
||
│ │ ├── index.js
|
||
│ │ └── ...
|
||
│ ├── cache/ # 缓存模块
|
||
│ │ ├── index.js
|
||
│ │ └── ...
|
||
│ ├── logManagement/ # 日志管理模块
|
||
│ │ ├── index.js
|
||
│ │ └── ...
|
||
│ ├── utils/ # 工具函数
|
||
│ │ ├── index.js
|
||
│ │ └── ...
|
||
├── config/
|
||
│ └── config.json # 独立的配置文件
|
||
├── cache/ # 缓存文件目录
|
||
├── logs/ # 日志文件目录
|
||
└── package.json # 项目依赖和脚本配置
|
||
功能流程图
|
||
plaintext
|
||
开始
|
||
|
|
||
|-- 同步缓存状态配置
|
||
|
|
||
|-- 扫描文件
|
||
| |
|
||
| |-- 捕获 $t 模板变量中的中文内容
|
||
| |
|
||
| |-- 清理缓存中的无效数据
|
||
| |
|
||
| |-- 过滤重复内容（通过缓存）
|
||
|
|
||
|-- 并发调用翻译服务进行翻译（上限 200）
|
||
| |
|
||
| |-- 根据 translateMethod 选择对应翻译模块
|
||
| | |
|
||
| | |-- 通过适配器转换请求和响应格式
|
||
| | | |
|
||
| | | |-- 支持多个目标语言（JSON 字符串数组）
|
||
| | | |-- 错误处理和重试机制
|
||
| | | |-- 并发请求精细控制（请求间隔、失败重试）
|
||
|
|
||
|-- 生成翻译文件（动态追加）
|
||
| |
|
||
| |-- 文件操作模块创建、修改、复制、读取文件
|
||
|
|
||
|-- 更新缓存
|
||
|
|
||
|-- 状态管理模块更新状态
|
||
|
|
||
|-- 日志管理模块记录日志
|
||
|
|
||
结束
|
||
功能清单
|
||
文件操作模块：负责文件和目录的创建、修改、复制、读取等操作，为翻译文件的生成和管理提供支持。
|
||
翻译模块：根据配置选择合适的翻译服务，通过适配器统一请求和响应格式，对中文内容进行并发翻译。
|
||
状态管理模块：集中管理插件的状态信息，确保在扫描文件前同步缓存状态，保证数据一致性。
|
||
缓存模块：创建和管理缓存文件，加速重复内容的处理，同时清理无效缓存，提高性能。
|
||
日志管理模块：记录插件运行过程中的关键信息，包括错误信息，方便调试和问题排查。
|
||
文件扫描模块：按照指定的文件后缀扫描项目文件，捕获 $t 模板变量中的中文内容。
|
||
文件监听模块：按配置的时间间隔监听文件变化，触发翻译流程，实现实时更新。
|
||
功能模块划分
|
||
核心功能模块：翻译模块、文件操作模块，直接实现主要业务逻辑。
|
||
辅助功能模块：状态管理模块、缓存模块、日志管理模块，为核心功能提供支持和保障。
|
||
监测模块：文件扫描模块、文件监听模块，负责监测项目文件的变化。
|
||
四、功能模块详细设计
|
||
|
||
1. 文件操作模块
|
||
函数名：createFile
|
||
参数：filePath（文件路径），content（文件内容）
|
||
职责：创建指定路径的文件，并将内容写入文件，同时处理文件创建过程中可能出现的错误。
|
||
函数名：modifyFile
|
||
参数：filePath（文件路径），newContent（新的文件内容）
|
||
职责：修改指定路径文件的内容，处理文件修改过程中的错误。
|
||
函数名：copyFile
|
||
参数：sourcePath（源文件路径），destinationPath（目标文件路径）
|
||
职责：将源文件复制到目标路径，处理文件复制过程中的错误。
|
||
函数名：readFile
|
||
参数：filePath（文件路径）
|
||
职责：读取指定路径文件的内容，处理文件读取过程中的错误。
|
||
函数名：createDirectory
|
||
参数：dirPath（目录路径）
|
||
职责：创建指定路径的目录，处理目录创建过程中的错误。
|
||
2. 翻译模块
|
||
函数名：translateTexts
|
||
参数：
|
||
texts（待翻译的中文内容列表）
|
||
apiKey（翻译服务的 API 密钥）
|
||
languages（翻译的目标语言 JSON 字符串数组）
|
||
concurrency（并发数量）
|
||
requestInterval（请求间隔时间）
|
||
maxRetries（最大重试次数）
|
||
translateMethod（翻译方式，如 "zhipuAI"、"api1" 等）
|
||
职责：根据 translateMethod 选择对应翻译模块，通过适配器将请求和响应格式统一，以指定的并发数量调用该模块对中文内容列表进行翻译，控制请求间隔，处理请求失败重试，支持多个目标语言，返回翻译结果列表。
|
||
3. 翻译适配器模块（translation/adapter）
|
||
适配器基类（translation/adapter/index.js）
|
||
javascript
|
||
class TranslationAdapter {
|
||
constructor() {
|
||
if (this.constructor === TranslationAdapter) {
|
||
throw new Error('Abstract class cannot be instantiated directly.');
|
||
}
|
||
}
|
||
|
||
translate(text, apiKey, languages, maxRetries) {
|
||
throw new Error('Method "translate" must be implemented.');
|
||
}
|
||
|
||
}
|
||
|
||
module.exports = TranslationAdapter;
|
||
传统 API 翻译适配器（translation/adapter/traditionalApiAdapter.js）
|
||
javascript
|
||
const TranslationAdapter = require('./index');
|
||
const traditionalApiModule = require('../traditional/api1'); // 示例传统 API 模块
|
||
|
||
class TraditionalApiAdapter extends TranslationAdapter {
|
||
async translate(text, apiKey, languages, maxRetries) {
|
||
// 转换请求格式以适配传统 API
|
||
const requestData = {
|
||
text,
|
||
apiKey,
|
||
languages,
|
||
maxRetries
|
||
};
|
||
const result = await traditionalApiModule.translate(requestData);
|
||
// 转换响应格式以统一输出
|
||
return {
|
||
text,
|
||
translations: result.translations
|
||
};
|
||
}
|
||
}
|
||
|
||
module.exports = TraditionalApiAdapter;
|
||
AI 批量翻译适配器（translation/adapter/aiBatchAdapter.js）
|
||
javascript
|
||
const TranslationAdapter = require('./index');
|
||
const aiModule = require('../ai/zhipuAI'); // 示例 AI 模块
|
||
|
||
class AIBatchAdapter extends TranslationAdapter {
|
||
async translate(text, apiKey, languages, maxRetries) {
|
||
// 转换请求格式以适配 AI 批量翻译
|
||
const requestData = {
|
||
text,
|
||
apiKey,
|
||
languages,
|
||
maxRetries
|
||
};
|
||
const result = await aiModule.translate(requestData);
|
||
// 转换响应格式以统一输出
|
||
return {
|
||
text,
|
||
translations: result.translations
|
||
};
|
||
}
|
||
}
|
||
|
||
module.exports = AIBatchAdapter; 4. AI 翻译模块集合（translation/ai）和传统 API 翻译模块集合（translation/traditional）
|
||
每个具体的翻译模块（如 zhipuAI.js、api1.js 等）负责与对应的翻译服务进行交互，接收适配器转换后的请求数据，返回翻译结果。5. 状态管理模块
|
||
函数名：syncCacheState
|
||
参数：无
|
||
职责：在扫描文件前同步缓存的状态配置。
|
||
函数名：updateState
|
||
参数：newState（新的状态信息）
|
||
职责：更新插件的状态信息。
|
||
函数名：getState
|
||
参数：无
|
||
职责：获取插件的当前状态信息。6. 缓存模块
|
||
函数名：getCachedTranslations
|
||
参数：texts（待检查的中文内容列表），languages（翻译的目标语言 JSON 字符串数组），cachePath（缓存文件存放地址）
|
||
职责：检查指定路径的缓存文件，返回已缓存的翻译结果，同时返回未缓存的中文内容列表。
|
||
函数名：updateCache
|
||
参数：texts（中文内容列表），translations（对应的翻译结果列表，符合翻译模块返回值固定格式），languages（翻译的目标语言 JSON 字符串数组），cachePath（缓存文件存放地址）
|
||
职责：将新的翻译结果更新到指定路径的缓存文件中。
|
||
函数名：cleanCache
|
||
参数：validTexts（有效的中文内容列表），languages（翻译的目标语言 JSON 字符串数组），cachePath（缓存文件存放地址）
|
||
职责：清理指定路径缓存文件中无效的翻译结果。7. 日志管理模块
|
||
函数名：logInfo
|
||
参数：message（日志信息）
|
||
职责：记录普通日志信息。
|
||
函数名：logError
|
||
参数：error（错误信息）
|
||
职责：记录错误日志信息。8. 文件扫描模块
|
||
函数名：scanFiles
|
||
参数：projectPath（项目路径），templateRegex（检索模板变量的正则表达式），fileExtensions（支持的扫描文件后缀）
|
||
职责：扫描指定项目路径下符合后缀要求的文件，依据给定的正则表达式提取 $t 模板变量中的中文内容，并返回中文内容列表。
|
||
9. 文件监听模块
|
||
函数名：watchFiles
|
||
参数：projectPath（项目路径），interval（监听文件间隔时间），callback（文件变化时的回调函数）
|
||
职责：按指定的时间间隔监听项目路径下的文件变化，触发回调函数。
|
||
五、业务 / 系统流程
|
||
项目流程
|
||
启动 Vite 项目，插件开始工作。
|
||
状态管理模块同步缓存的状态配置，确保数据一致性。
|
||
文件扫描模块按配置的文件后缀扫描项目文件，依据配置的正则表达式提取 $t 模板变量中的中文内容。
|
||
缓存模块清理缓存文件中的无效数据，提高缓存的有效性。
|
||
检查缓存，过滤掉已缓存的中文内容，减少不必要的翻译请求。
|
||
翻译模块根据 translateMethod 选择对应翻译模块，通过适配器将请求和响应格式统一，以配置的并发数量对未缓存的中文内容进行翻译，控制请求间隔，处理请求失败重试，支持多个目标语言。
|
||
文件操作模块根据翻译结果和指定的语言列表生成翻译文件，若文件已存在则动态追加内容，处理文件操作过程中的错误。
|
||
缓存模块更新缓存文件，将新的翻译结果加入缓存，加速后续翻译。
|
||
状态管理模块更新插件的状态信息，反映当前运行状态。
|
||
日志管理模块记录插件运行过程中的关键信息，包括错误信息，方便调试和问题排查。
|
||
文件监听模块按配置的时间间隔监听文件变化，若有变化则重复步骤 2 - 10，实现实时更新。
|
||
交互流程
|
||
插件在 Vite 构建过程中自动运行，无需用户手动干预。
|
||
用户可以通过修改 config/config.json 文件调整插件的行为，如扫描路径、输出路径、翻译服务的 API 密钥、翻译的目标语言 JSON 字符串数组、并发数量、检索模板变量的正则表达式、缓存文件存放地址、支持的扫描文件后缀、监听文件间隔时间、请求间隔时间、最大重试次数、翻译方式等。
|
||
相关建议
|
||
在开发过程中，可提供配置文件的校验机制，确保用户输入的配置信息合法。
|
||
对于翻译结果的准确性，可提供人工审核和修正的接口，以提高翻译质量。
|
||
六、配置参数详细说明
|
||
配置文件（config/config.json）
|
||
json
|
||
{
|
||
"projectPath": "./src",
|
||
"outputPath": "./locales",
|
||
"apiKey": {
|
||
"zhipuAI": "your_zhipuAI_api_key",
|
||
"api1": "your_api1_api_key"
|
||
},
|
||
"cachePath": "./cache/translation_cache.json",
|
||
"languages": ["zhCN", "zhTW", "enUS", "jaJP", "koKR", "ruRU", "ptBR", "frFR", "esAR", "arDZ"],
|
||
"concurrency": 100,
|
||
"templateRegex": "/\\$t\\(['\"]([\u4e00-\u9fa5]+)['\"]\\)/g",
|
||
"fileExtensions": [".vue"],
|
||
"interval": 5000,
|
||
"requestInterval": 100,
|
||
"maxRetries": 3,
|
||
"translateMethod": "zhipuAI"
|
||
}
|
||
projectPath：项目扫描路径，插件将从该路径开始扫描文件。
|
||
outputPath：翻译文件的输出路径，生成的翻译文件将存放在此。
|
||
apiKey：包含不同翻译服务的 API 密钥，根据 translateMethod 选择使用。
|
||
cachePath：缓存文件的存放地址，用于存储已翻译的内容。
|
||
languages：翻译的目标语言列表，使用 JSON 字符串数组表示。
|
||
concurrency：并发翻译的数量上限，控制并发请求的数量。
|
||
templateRegex：检索 $t 模板变量中中文内容的正则表达式。
|
||
fileExtensions：支持扫描的文件后缀列表，只有符合这些后缀的文件才会被扫描。
|
||
interval：文件监听的时间间隔，单位为毫秒。
|
||
requestInterval：翻译请求的间隔时间，避免对翻译服务造成过大压力。
|
||
maxRetries：请求失败后的最大重试次数。
|
||
translateMethod：选择的翻译方式，如 "zhipuAI"、"api1" 等。
|
||
七、部署说明
|
||
项目部署
|
||
将插件代码复制到项目的 node_modules 目录下，或者使用 npm link 进行本地链接，使项目能够找到插件。
|
||
在 Vite 配置文件（vite.config.js）中引入插件：
|
||
javascript
|
||
const i18nAiTranslatePlugin = require('vite-plugin-i18n-ai-translate');
|
||
|
||
module.exports = {
|
||
plugins: [i18nAiTranslatePlugin()]
|
||
};
|
||
环境相关问题
|
||
确保项目中已安装 Vite、Vue 和 vue - i18n，并且版本符合要求，以保证插件正常运行。
|
||
确保网络连接正常，以便调用翻译服务的 API，否则翻译请求将失败。
|
||
若并发数量设置过高，可能会导致网络拥堵或触发翻译服务的限流机制，需根据实际情况调整，避免影响翻译效率。
|
||
监听文件间隔时间设置过短可能会增加系统开销，需根据项目规模和文件变更频率合理设置，平衡性能和实时性。
|
||
请求间隔时间和最大重试次数应根据网络状况和翻译服务的稳定性进行调整，提高翻译的成功率。
|
||
若使用不同的翻译方式，需确保相应的 API 密钥和配置正确，否则无法正常调用翻译服务。
|
||
八、总结
|
||
项目情况
|
||
该 Vite 插件实现了 i18n 自动化翻译功能，通过模块化设计，各个模块采用正交性设计，具备良好的扩展性和可维护性。插件在扫描文件前同步缓存的状态配置，增加了错误处理和重试机制，对并发请求进行更精细的控制。AI 子模块支持多个目标语言，入参和返回值采用固定格式。翻译模块采用适配器模式，兼容传统的 API 翻译和 AI 批量翻译，提高了系统的兼容性和灵活性。同时，支持文件监听，可及时响应文件变化，实现实时更新。
|
||
开发建议
|
||
持续优化各个翻译模块和适配器的性能，提高翻译效率和准确性，减少翻译时间。
|
||
增加更多的翻译服务支持，丰富翻译方式的选择，满足不同用户的需求。
|
||
完善缓存模块对不同翻译方式和目标语言的缓存管理策略，提高缓存的命中率和清理效率。
|
||
进一步细化错误处理和重试机制，针对不同翻译服务的错误类型进行更精准的处理，增强系统的稳定性。
|
||
对并发请求控制进行智能化优化，根据翻译服务的实时状态动态调整并发数量和请求间隔，提高资源利用率。
|
||
提供更友好的用户配置界面，方便用户调整插件的各项参数，降低使用门槛。
|
||
加强日志管理，记录更详细的翻译过程信息，便于问题排查和性能分析，提高开发和维护效率。
|