i18n-transformer 国际化转换工具技术文档

i18n-transformer 国际化转换工具技术文档

【免费下载链接】i18n-transformer 一个基于AST自动转换JS代码中的中文为i18n翻译函数的 Vite/Webpack 插件/loader。 项目地址: https://gitcode.com/y3213446/i18n-transformer

1. 安装指南

1.1 环境要求

• Node.js 版本需 ≥ 14

1.2 安装方式

Vite 项目安装

# 使用 pnpm
pnpm add -D @higgins-mmt/vite-plugin

# 使用 npm
npm install -D @higgins-mmt/vite-plugin

# 使用 yarn
yarn add -D @higgins-mmt/vite-plugin

Webpack 项目安装

# 使用 pnpm
pnpm add -D @higgins-mmt/webpack-plugin

# 使用 npm
npm install -D @higgins-mmt/webpack-plugin

# 使用 yarn
yarn add -D @higgins-mmt/webpack-plugin

2. 使用说明

2.1 Vite 项目配置

// vite.config.ts
import { defineConfig } from 'vite'
import { i18nTransformer } from '@higgins-mmt/vite-plugin'

export default defineConfig({
  plugins: [
    i18nTransformer({
      include: ['src/**/*.{js,jsx,ts,tsx}'],  // 处理文件范围
      exclude: ['node_modules/**'],           // 排除目录
      i18nCallee: 't',                       // i18n函数名
      // 可选翻译平台配置
      upload: {
        app: 'your-app-name',
        url: 'your-translation-platform-url',
        appType: 'FE_VUE3',
        uploadStrategy: 'INSERT_ONLY'
      }
    })
  ]
})

2.2 Webpack 项目配置

// webpack.config.js
const { I18nTransformerPlugin } = require('@higgins-mmt/webpack-plugin')

module.exports = {
  plugins: [
    new I18nTransformerPlugin({
      include: ['src/**/*.{js,jsx,ts,tsx}'],
      exclude: ['node_modules/**'],
      i18nCallee: 't',
      // 可选翻译平台配置
      upload: {
        app: 'your-app-name',
        url: 'your-translation-platform-url',
        appType: 'FE_VUE3',
        uploadStrategy: 'INSERT_ONLY'
      }
    })
  ]
}

3. API 使用文档

3.1 核心配置参数

参数	类型	必填	说明
include	string[]	是	文件匹配模式（如 ['src/**/*.ts']）
exclude	string[]	否	排除文件模式
i18nCallee	string	是	国际化函数名称（如 't'）
localePattern	RegExp	否	文本匹配正则（默认匹配中文）

3.2 翻译平台集成配置

upload: {
  app: string;            // 应用唯一标识
  url: string;            // 平台API地址
  appType: 'FE_VUE2' | 'FE_VUE3';  // 应用类型
  uploadStrategy: 'INSERT_ONLY' | 'INSERT_UPDATE' | 'INSERT_CLEAN' | 'UPSERT_CLEAN'; // 上传策略
}

3.3 高级功能API

忽略特定文本转换

import { ignoreAutoI18n } from '@higgins-mmt/core'
const text = ignoreAutoI18n('不需要转换的文本')

自定义转换规则

{
  generateKey: (text: string) => `custom.${text}`,
  localePattern: /.+/,
  i18nCallee: 'customTranslate'
}

4. 项目安装方式详解

4.1 新项目集成步骤

1. 通过对应包管理器安装插件
2. 在构建配置文件中添加插件配置
3. 确保项目中已安装对应的i18n库（如vue-i18n）
4. 运行项目时插件会自动处理文本转换

4.2 已有项目迁移建议

1. 先备份项目代码
2. 从少量文件开始逐步应用转换
3. 使用exclude参数排除不需要处理的文件
4. 检查生成的翻译键是否符合预期

4.3 开发模式调试

1. 在配置中开启调试模式（如添加debug: true）
2. 查看控制台输出的转换日志
3. 使用ignoreAutoI18n临时标记问题文本
4. 通过generateKey自定义键生成规则

5. 最佳实践

1. 动态文本处理：插件自动处理模板字符串

   // 转换前
   const text = `用户: ${username}`
   // 转换后
   const text = t('dynamic_user', { username })
   

2. JSX文本处理：自动转换JSX中的文本内容

   // 转换前
   <button>点击提交</button>
   // 转换后
   <button>{t('button_submit')}</button>
   

3. 翻译键管理：建议配合翻译平台使用上传功能，保持键值同步更新

【免费下载链接】i18n-transformer 一个基于AST自动转换JS代码中的中文为i18n翻译函数的 Vite/Webpack 插件/loader。 项目地址: https://gitcode.com/y3213446/i18n-transformer