Tranzy.js v1.0.8

Tranzy.js 是一个专业的网页国际化解决方案，让开发者能够轻松地为网站添加多语言支持。它提供了自动翻译、手动翻译词典、DOM变化监听等核心功能，同时内置了微软翻译API作为可选的翻译服务。

官网：https://www.tranzy.top/

核心优势

1. 开发友好

🚀 零配置即可使用，自动从浏览器语言设置获取目标语言
🛠️ 提供灵活的配置选项，满足各种定制需求
🔌 支持自定义翻译函数，可轻松替换默认翻译服务
📝 提供丰富的钩子函数，方便进行自定义处理

2. 性能优化

⚡ 使用 IndexedDB 进行翻译缓存，减少重复翻译
📦 支持批量翻译，提高翻译效率
🔄 智能的DOM变化监听，只翻译新增内容
💾 自动管理翻译缓存，优化内存使用

3. 功能强大

🌐 自动检测DOM变化并翻译新增内容
📚 支持手动翻译词典和术语处理
🎯 支持强制翻译和忽略特定元素
🔍 支持语言检测和浏览器语言识别

4. 使用灵活

🎨 支持自定义翻译样式和标记类
🔄 可随时开启/关闭DOM监听
📱 支持动态加载的内容翻译
🌍 支持多种语言和BCP 47语言代码

安装

使用 npm 安装：

npm install tranzy

或者使用 pnpm 安装：

pnpm add tranzy

快速开始

1. 使用 ES Module

import Tranzy from 'tranzy';

// 只需三行代码，即可自动将网站翻译为浏览器当前语言
const tranzy = new Tranzy();
tranzy.translatePage();    // 翻译整个页面
tranzy.startObserver();    // 监听DOM变化，自动翻译新内容

2. 使用 UMD 版本

<!-- 引入UMD版本的Tranzy -->
<script src="path/to/tranzy.umd.js"></script>
<script>
  // 只需三行代码，即可自动将网站翻译为浏览器当前语言
  const tranzy = new Tranzy.Translator();
  tranzy.translatePage();    // 翻译整个页面
  tranzy.startObserver();    // 监听DOM变化，自动翻译新内容
</script>

高级配置

如果需要更精细的控制，Tranzy还提供了丰富的配置选项：

import Tranzy from 'tranzy';

// 创建带有高级配置的Tranzy实例
const tranzy = new Tranzy({
  toLang: 'zh-Hans',           // 目标语言
  fromLang: 'en',             // 源语言（可选）
  ignore: ['.no-translate'],  // 忽略的选择器列表
  force: ['.must-translate'], // 强制翻译的选择器列表（优先级高于ignore）
  manualDict: {               // 手动翻译词典
    'zh-Hans': {
      'Tranzy': '全译'
    }
  },
  beforeTranslate: () => {    // 翻译开始前的钩子
    console.log('开始翻译');
  },
  afterTranslate: () => {     // 翻译结束后的钩子
    console.log('翻译完成');
  }
});

tranzy.translatePage();
tranzy.startObserver();

注意： 当fromLang和toLang相同时，translatePage()和startObserver()会自动跳过翻译过程。

1. 默认忽略的元素

Tranzy默认已经配置了以下元素不进行翻译：

// 这些元素及其内容默认不会被翻译
const DEFAULT_IGNORE_SELECTORS = [
  'style',            // 样式标签
  'script',           // 脚本标签
  'noscript',         // 无脚本标签
  'kbd',              // 键盘输入标签
  'code',             // 代码标签
  'pre',              // 预格式化文本标签
  'input',            // 输入框
  'textarea',         // 文本域
  '[contenteditable="true"]', // 可编辑元素
  '.tranzy-ignore'    // 自定义忽略类
];

您可以通过配置ignore选项添加更多忽略选择器，但使用force选择器可以覆盖忽略规则，因为force的优先级高于ignore。

2. 控制翻译范围

// ES6模式
import Tranzy from 'tranzy';
const tranzy = new Tranzy({
  // 忽略特定元素
  ignore: [
    '.no-translate',      // 忽略特定类
    '#header',           // 忽略特定ID
    '[data-no-trans]'    // 忽略特定属性
  ],
  // 强制翻译特定元素
  force: [
    '.must-translate',   // 强制翻译特定类
    '#content'          // 强制翻译特定ID
  ]
});

3. 使用手动翻译词典

// ES6模式
import Tranzy from 'tranzy';
const tranzy = new Tranzy({
  toLang: 'zh-Hans',
  manualDict: {
    // 全局词典，适用于所有目标语言
    'all': {
      // 品牌名称、专有名词等不需要翻译的词汇
      'tranzy': {           
        to: 'tranzy',       // 保证首字母大小写保持不变
        standalone: false,  // 在句子中也进行匹配
      },
      'Tranzy': {
        to: 'Tranzy',       // 大写形式也保持不变
        standalone: false,  // 在句子中也进行匹配
      },
      // 简化形式，默认 standalone: true, case: true
      'Copyright': 'Copyright'
    },
    // 特定语言的词典
    'zh-Hans': {
      // 完整形式
      'Hello World': {
        to: '你好，世界',    
      },
      // 简化形式
      'JavaScript': 'JavaScript (JS脚本语言)',
      // 支持正则表达式形式的匹配
      '\\d+ years old': {
        to: '岁',
      },
      'tranzy': {
        to: '全译',         // 中文特别处理为"全译"
        standalone: false,  // 在句子中也进行匹配
        case: false         // 忽略大小写
      }
    }
  }
});

注意： 特定语言的词典条目（如'zh-Hans'）优先级高于全局词典('all')中的同名条目。这种设计使得您可以在全局词典中定义通用翻译，同时在特定语言中进行个性化覆盖，增强了翻译的灵活性和精确性。

4. 使用钩子函数

// ES6模式
import Tranzy from 'tranzy';
const tranzy = new Tranzy({
  // 翻译开始前的钩子
  beforeTranslate: () => {
    console.log('开始翻译');
  },
  // 翻译结束后的钩子
  afterTranslate: () => {
    console.log('翻译完成');
  }
});

5. 动态内容处理

// 在动态加载内容后手动触发翻译
const loadContent = () => {
  loadDynamicContent();
  tranzy.translatePage('.dynamic-content'); // 可以指定要翻译的元素，不传则默认翻译body
};

高级功能

1. 内置翻译API

除了核心的多语言功能外，Tranzy 还内置了微软翻译API，提供以下功能：

import { translateText, detectLang, getSupportedLangs, getBrowserLang } from 'tranzy';

// 翻译文本
const result = await translateText(['Hello world'], 'zh-Hans', 'en');
console.log(result); // ['你好世界']

// 检测语言
const langResult = await detectLang('Hello world');
console.log(langResult); // [{ language: 'en', score: 1.0, isTranslationSupported: true, isTransliterationSupported: true }]

// 获取支持的语言列表
const langs = await getSupportedLangs('zh-Hans');
console.log(langs); // { en: { name: '英语', nativeName: 'English', dir: 'ltr' }, ... }

// 获取浏览器语言对应的支持语言代码
const browserLang = await getBrowserLang();
console.log(browserLang); // 'zh-Hans' 或 'en' 等

2. 自定义翻译函数

// ES6模式
import Tranzy from 'tranzy';
const tranzy = new Tranzy({
  toLang: 'zh-Hans',
  // 使用自定义翻译函数
  translateFn: async (texts, toLang, fromLang) => {
    // 实现自定义翻译逻辑
    return texts.map(text => `[${toLang}] ${text}`);
  }
});

作者

Fts Cloud ftsuperb@vip.qq.com

许可证

MIT

仓库

https://github.com/FtsCloud/Tranzy

Tranzy

Install / Use

README