auto-i18n-translation-plugins 全自动国际化插件——常见问题汇总

auto-i18n-translation-plugins 全自动国际化插件------常见问题汇总

帮你零成本实现多语言支持，提升效率的国际化神器

🌐 前言

大家好！auto-i18n-translation-plugins 是一款基于 Babel 的自动化国际化解决方案插件，支持 Vite/Webpack/Rollup 构建工具，通过 零代码侵入 实现多语言翻译。经过迭代，现支持 全自动翻译、多服务集成、精准多义词处理 等功能，兼容 Vue/React 全家桶。

下面总结一下近期大家使用时常见的问题：

💡 仓库地址 ：
GitHub 仓库🔗

📖 相关文章 ：
组长说：公司的国际化就交给你了，下个星期给我
 前端国际化全场景支持方案，不入侵代码，一键完成 (vue2/3、react)。
三行代码完成国际化适配，别等错过了才后悔没收藏！
前端国际化终极方案------全自动翻译国际化（支持一键翻译多国语言，不入侵业务代码）
还在手写翻译文件？这个插件让你的前端国际化快10倍！

💡 常见问题解答

1. 怎么配置翻译对象？

1.1 支持的翻译服务

默认提供以下翻译器：

diff 复制代码

+ YoudaoTranslator（有道）  

+ BaiduTranslator（百度）  

+ GoogleTranslator（谷歌）

1.2 配置示例

javascript 复制代码

import vitePluginsAutoI18n, { YoudaoTranslator, BaiduTranslator, GoogleTranslator } from 'auto-i18n-translation-plugins';

// 🚀 有道翻译配置示例  
vitePluginsAutoI18n({  
  targetLangList: ['en', 'ko', 'ja', 'ru'], // 翻译成日语、韩语、俄语、英语  
  originLang: 'zh-cn',                     // 来源语言  
  translator: new YoudaoTranslator({       // 有道配置参数  
    appId: '6f7d97dd8dae', // 必填  
    appKey: 'T40Yki12aTYBh4LZIzH' // 必填  
  })  
});  

// 🚀 百度翻译配置示例  
vitePluginsAutoI18n({  
  targetLangList: ['en'],              // 翻译成英语  
  translator: new BaiduTranslator({  
    appId: '202503480', // 必填  
    appKey: ''          // 必填  
  })  
});  

// 🚀 谷歌翻译（需科学上网 + 代理）  
vitePluginsAutoI18n({  
  targetLangList: ['en'],                 // 翻译成英语  
  translator: new GoogleTranslator({  
    proxyOption: {  
      host: '127.0.0.1', // 本地代理IP  
      port: 7890,        // 代理端口  
      headers: {  
        'User-Agent': 'Node' // 推荐配置  
      }  
    }  
  })  
});

2. 怎么申请翻译的 app ID 和 key？

翻译服务	申请地址	免费额度
有道翻译	有道开放平台	50免费额度
百度翻译	百度翻译 API	每个月有数万字免费额度
谷歌翻译	无需账号，需科学上网	免费但频繁使用会失败

3. 怎么修改翻译内容？

3.1 修改入口

插件会自动生成 lang/ 目录下的index.json文件，需在此文件中直接修改翻译结果：

json 复制代码

{  
  "hash_key_1": {  
    "zh-cn": "中文原文",  
    "en": "EDIT THIS!" // 直接修改目标语言内容  
  },  
  "another_hash": {  
    "ja": "日本語を編集",  
    "ru": "Русский текст"  
  }  
}

3.2 注意事项

翻译键（如 hash_key_1）是基于语言生成的唯一哈希标识，不可修改！

4. 如何排除不需要翻译的文本？

4.1 排除语法

默认可通过包裹 $$t() 注释文本：

javascript 复制代码

// 需要翻译的内容  
const text = 'Hello World!'; // ✅ 自动收录  
// 不需要翻译的内容  
const name = $$t('Tom');     // ❌ 被排除，不会被翻译

5. 多义词如何处理？

5.1 现实场景示例

中文 天 的不同翻译场景：

html 复制代码

<!-- 场景1：表示"sky"（天空） -->  
<div>今天的 <span>天</span>很蓝</div>  

<!-- 场景2：表示"day"（时间单位） -->  
<div>距离今天还有 {{num}}天</div>

5.2 对应翻译修改

html 复制代码

<!-- 场景1：表示"sky"（天空） -->  
<div>今天的 <span>天</span>很蓝</div>  

<!-- 场景2：表示"day"（时间单位） -->  
<div>距离今天还有 {{num}}{{ $t(自定义hash, '天', namespace) }}</div>   // 其中 $t 是translatekey 的值

json 复制代码

{  
  // 默认命名空间下的翻译（翻译成"天空"）  
  "天": {  
    "zh-cn": "天",  
    "en": "sky"  
  },  
  //自定义hash 命名空间下的翻译（翻译成"天数"）  
  "自定义hash": {  
    "zh-cn": "天",  
    "en": "day"  //  sky 改成day即可
  }  
}

5.3 核心机制

命名空间规则 ：键名格式为 translatekey(hash, 原文，命名空间)
灵活配置：同一原文可以在不同命名空间下拥有不同翻译

6. 能否翻译英文项目？

注意：中日韩俄四国语言的key 必须是 zh-cn/ja/ko/ru，无论来源语言还是目标语言

6.1 核心规则对比表

模式类型	源语言限制	目标语言约束	必需的操作
全自动(full-auto)	必须为中日韩俄（zh-cn/ja/ko/ru）	目标语言必须来自四国	无需人工标记
半自动(semi-auto)	支持任意语言	四国语言需使用标准Key	必须人工标记翻译文本

6.2 配置英文项目的步骤

javascript 复制代码

// 配置半自动模式支持英文源语言  
vitePluginsAutoI18n({  
  translateType: 'semi-auto', // 🔴 必选半自动模式  
  originLang: 'en',           // 源语言设为英文  
  targetLangList: ['zh-cn', 'ja'],  
  translator: new YoudaoTranslator({  
    appId: 'YOUR_ID',  
    appKey: 'YOUR_KEY'  
  })  
});

6.3 开发者操作流程

人工标记需要翻译的文本：

html 复制代码

<!-- 原始英文文案 -->  
<div>Hello bro</div>  

<!-- 手动包裹 `$t()` 注释 -->  
<div>{{ $t('Hello bro') }}</div>

首次构建生成翻译文件 ：
插件会自动生成如下的中日翻译：

json 复制代码

// lang/en.json  
{  
  "key_123": {  
    "en": "Hello bro",  
    "zh-cn": "你好兄弟",  
    "ja": "こんにちは"  
  }  
}

6.4 疑难问题

问：为什么不能用全自动模式？

答： 全自动模式需要依赖源语言的正则规则扫描文本，中日韩俄都有特色的正则匹配规则。
英文原文的语言，没有具有特色的正则匹配规则，因此扫描逻辑需人工标注后触发（见标记语法）。

7. 全自动模式的源语言限制

7.1 配置约束

diff 复制代码

+ 当选择 `full-auto` 模式时：  
  ```json  
  "originLang": "zh-cn" | "ja" | "ko" | "ru"  // 来源语言只能选这些

中日韩俄语言在配置中必须使用标准化Key（禁止使用 zh-CN、japanese 等非标准值）

8. 兼容 Vue-i18n

8.1 解决命名冲突

若原来的Vue-i18n项目已存在 $t() 函数，需修改插件的翻译标识符：

javascript 复制代码

vitePluginsAutoI18n({  
  translateKey: '$a18n',  // 新的翻译函数名  
  excludedCall: ['$t']    // 过滤 Vue-i18n 的原始函数  
});

8.2 在 Vue 中并存使用

vue 复制代码

<template>  
  <!-- 使用 Vue-i18n 的本地化文本 -->  
  <h1>{{ $t('greeting') }}</h1>  

  <!-- 半自动情况下，使用插件翻译的通用文本 -->  
  <div>{{ $a18n('大家好') }}</div>  
  
  <!-- 全自动情况下，使用插件翻译的通用文本 -->  
  <div>大家好</div>  
</template>

⚠️ 关键注意事项

服务稳定性
- 谷歌翻译需确保代理稳定
- 百度/有道超出免费额度将导致翻译错误
文件管理规范
- 请将翻译文件纳入版本控制（如 Git）
功能限制
- 全自动模式仅支持中日韩俄为源语言，禁止修改
- 半自动模式下，若翻译目标包含中日韩俄，必须使用标准语言代码

✨ 项目仓库

❓ 技术讨论 ：遇到未涵盖问题？欢迎在Github Issues 提出，或关注仓库最新版本更新！
💡 仓库地址 ：
GitHub 仓库🔗

欢迎点🌟

auto-i18n-translation-plugins 全自动国际化插件——常见问题汇总