一键实现全站多语言化：translate.js 极简集成指南，支持Vue 、React 框架。 - 实践

文章目录

什么是 translate.js？
✨ 核心优势
三分钟快速集成（非npm包集成）
框架集成方案
- Vue 单文件组件
运行效果
性能优化建议
⚠️ 常见问题解决
总结

在这里插入图片描述

什么是 translate.js？

translate.js 是由 zvo.cn 团队开发的轻量级前端翻译库（仅 28KB），支持全站内容实时翻译。它通过智能解析 DOM 结构，结合云端翻译引擎和本地词库混合模式，为网站提供流畅的多语言体验。

官方地址：https://translate.zvo.cn/index.html
体验地址：https://res.wang.market/translate/demo.html

✨ 核心优势

✅ 支持 100+ 语言实时互译
✅ 智能缓存机制减少重复请求
✅ 自动保留 HTML 标签结构
✅ 支持 Google/DeepL 等多翻译引擎
✅ 免费版提供基础翻译能力（商用建议授权）

三分钟快速集成（非npm包集成）

1. 通过cdn js方式集成

只需在项目的 index.html 页底部添加如下代码

<!-- 在页面底部引入 -->
<script src="https://cdn.staticfile.net/translate.js/3.12.0/translate.js"></script>
  <script>
    translate.service.use('client.edge')
    translate.language.setDefaultTo('chinese_simplified') //设置默认翻译为的语种
    translate.language.setLocal('chinese_simplified')
    translate.listener.start()
    translate.selectLanguageTag.show = true
    //翻译自定义
    // translate.nomenclature.append(
    //   'chinese_simplified',
    //   'english',
    //   `吾码=WuMa`
    // )
    translate.execute();
  </script>

本人集成在 vue3 项目中, index.html 可以在根目录也可以在public目录，完整示例如下：

<!DOCTYPE html>
    <html lang="">
    <head>
      <meta charset="UTF-8" />
      <link rel="icon" href="/favicon.ico" />
      <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Vite App</title>
    </head>
    <body>
    <div id="app"></div>
    <script type="module" src="/src/main.js"></script>
      <!-- 全局配置-多语言切换-开始 -->
      <!-- <script src="<%= BASE_URL %>static/translate.js"></script> -->
      <script src="https://cdn.staticfile.net/translate.js/3.12.0/translate.js"></script>
        <script>
          //设置本地语种（当前网页的语种）。如果不设置，默认就是 'chinese_simplified' 简体中文
          // translate.language.setDefaultTo('english') //设置默认翻译为的语种
          // translate.language.setLocal('english')
          translate.service.use('client.edge')
          //翻译自定义
          // translate.nomenclature.append(
          //   'chinese_simplified',
          //   'english',
          //   `吾码=WuMa`
          // )
          //开启html页面变化的监控，对变化部分会进行自动翻译
          translate.listener.start()
          //不显示语言选择标签
          translate.selectLanguageTag.show = true
          //执行翻译初始化操作，显示出select语言选择
          //translate.execute();
          //VUE的渲染需要时间，所以留出一点点时间来进行翻译切换
          document.addEventListener('DOMContentLoaded', function () {
          // //页面 DOM 已渲染完毕，当然最好是能监控到整个vue渲染完毕后触发最好
          translate.execute()
          // //2秒后再一次，避免有遗漏
          // setTimeout(function () {
          //   translate.execute()
          // }, 2000)
          })
        </script>
      </body>
    </html>

2. 自定义样式（示例）

/* 自定义语言切换器样式 */
.translate_selectLanguage_tag {
position: fixed;
bottom: 20px;
right: 20px;
z-index: 9999;
background: #4a6cf7;
color: white;
padding: 8px 15px;
border-radius: 20px;
cursor: pointer;
box-shadow: 0 3px 10px rgba(74, 108, 247, 0.4);
}

3. 高级配置项

translate.setAutoDiscriminateLocalLanguage(); // 自动识别用户语言
translate.ignore.class.push('no-translate'); // 跳过指定 class 元素
// 使用 Google 引擎（需配置代理）
translate.setServiceProvider('google', {
proxyUrl: 'https://your-proxy-domain.com/translate'
});
// 自定义词汇映射（覆盖机器翻译）
translate.mapping.addVocabulary({
"首页": "HomePage",
"联系我们": "Contact Us"
});

框架集成方案

Vue 单文件组件

npm 引用

npm install i18n-jsautotranslate

main.js 引用

// main.js
import './assets/main.css'
import { createApp } from 'vue'
import App from './App.vue'
// import translate from 'i18n-jsautotranslate';
// // 是否显示语言切换栏
// translate.selectLanguageTag.show = true;
// // 监控页面动态渲染的文本进行自动翻译
// translate.listener.start();
const app = createApp(App);
// app.config.globalProperties.$translate = translate;
app.mount('#app');

app页面引用

// App.vue
  <script setup>
  import HelloWorld from './components/HelloWorld.vue'
  import TheWelcome from './components/TheWelcome.vue'
  import { ref, getCurrentInstance, nextTick } from 'vue'
  const instance = getCurrentInstance()
  const translate = instance.appContext.config.globalProperties.$translate
  const language = ref('en')
  function languageAuto() {
  // language.value === 'zh' ? (language.value = 'en') : (language.value = 'zh')
  // localStorage.setItem('language', JSON.stringify({ language: language.value }))
  // if (language.value === 'zh') {
  //   translate.changeLanguage('chinese_simplified')
  // } else {
  //   translate.changeLanguage('english')
  // }
  nextTick(() => {
  translate.execute() // 执行翻译
  })
  }
  // languageAuto()
</script>
<template>
  <header>
    <img
      alt="Vue logo"
      class="logo"
      src="./assets/logo.svg"
      width="125"
      height="125"
    />
      <div class="wrapper">
      <HelloWorld msg="You did it!" />
    </div>
  </header>
  <main>
    <TheWelcome />
  </main>
</template>
  <style scoped>
  header {
  line-height: 1.5;
  }
  .logo {
  display: block;
  margin: 0 auto 2rem;
  }
  @media (min-width: 1024px) {
  header {
  display: flex;
  place-items: center;
  padding-right: calc(var(--section-gap) / 2);
  }
  .logo {
  margin: 0 2rem 0 0;
  }
  header .wrapper {
  display: flex;
  place-items: flex-start;
  flex-wrap: wrap;
  }
  }
</style>

运行效果

在这里插入图片描述

性能优化建议

本地缓存加速
translate.setCache(true); 启用 localStorage 缓存翻译结果
预加载语言包
translate.loadLanguage('english'); 用户访问时提前加载
排除动态内容
translate.execute(); 在 AJAX 加载后手动执行翻译
CDN 加速
自托管库文件：<script src="/path/to/local/translate.js">

⚠️ 常见问题解决

Q: 翻译后页面布局错乱？
A: 添加 CSS 规则：[translate] { display: inherit !important; }

Q: 图片内容如何翻译？
A: 使用数据属性方案：

<img src="about.png"
  data-translate_attr="src"
  data-chinese_simplified="about_zh.png"
  data-english="about_en.png">

Q: SEO 如何优化？
A: 结合服务端渲染，使用声明语言

###  最佳实践案例
```javascript
// 双语混合模式（专业术语保留英文）
translate.specialTag.setKeepTexts({
    tags: ['h2', 'h3'],  // 标题保留原文
    words: ['API', 'JSON']  // 特定术语保留
});
// 配合 i18n 实现精准控制
if (user.isProfessional) {
    translate.mapping.addVocabulary(professionalTerms); // 导入专业词库
}
// 翻译事件监听
document.addEventListener('translate.onSuccess', (e) => {
    console.log(`已翻译 ${e.detail.total} 个字符`);
});

总结

translate.js 以极低的集成成本解决了网站国际化核心痛点。据官方数据，集成后平均提升：

海外流量 170%+
用户停留时长 40%+
转化率 25%+

最后提醒：虽然免费版功能强大，但商业项目请遵循授权政策。对于高级需求（如 PDF 翻译、私有化部署），建议联系官方获取企业版支持。

让世界没有语言障碍，translate.js 正在重新定义网站全球化标准！

---