tolgee-i18next-extractor

Tolgee CLI 的自定义提取器（Custom Extractor），用于从使用 i18next 的项目中提取翻译 key。

基于已废弃的 i18next-parser 项目的解析逻辑，用 TypeScript 重写。

支持的文件类型

| 文件类型 | 解析方式 | |---------|---------| | .vue | @vue/compiler-sfc + @vue/compiler-dom AST | | .ts / .js / .mjs | TypeScript Compiler API | | .tsx / .jsx | TypeScript Compiler API + <Trans> 组件支持 | | .html / .htm | cheerio（data-i18n 属性） | | .hbs / .handlebars | 正则匹配 |

支持提取的模式

// 函数调用
t('key')
$t('key')
t('ns:key')
t('key', 'default value')
t('key', { defaultValue: 'default value' })

// 命名空间检测
const { t } = useTranslation('namespace')

// Vue 模板
{{ $t('key') }}
<div :title="$t('key')">

// JSX 组件
<Trans i18nKey="key">Default content</Trans>

安装

作为 npm 包安装（推荐）

pnpm add -D tolgee-i18next-extractor

从源码构建

pnpm install
pnpm build

在 Tolgee CLI 中使用

方式一：直接使用（推荐）

默认配置使用 t 和 $t 作为翻译函数，适合大多数 i18next + Vue 项目。

安装后在项目根目录创建 .tolgeerc 文件：

{
  "extractor": "node_modules/tolgee-i18next-extractor/dist/index.js",
  "patterns": ["src/**/*.{vue,ts,tsx}"]
}

方式二：自定义配置

如果默认配置不满足需求，可以在项目中创建自己的 extractor 文件，按需配置参数：

// my-extractor.ts
import { I18NextExtractor } from 'tolgee-i18next-extractor'

const extractor = new I18NextExtractor({
  // 翻译函数名（默认 ['t']）
  functions: ['t', '$t', 'i18n.t'],
  // 命名空间分隔符（默认不开启，传 ':' 启用）
  namespaceSeparator: ':',
  // 命名空间函数（默认 ['useTranslation', 'withTranslation']）
  namespaceFunctions: ['useTranslation'],
  // 默认命名空间
  defaultNamespace: 'common',
  // JSX 组件名（默认 ['Trans']）
  componentFunctions: ['Trans'],
})

export default function (code: string, fileName: string) {
  return extractor.extract(code, fileName)
}

然后 .tolgeerc 指向你自己的文件：

{
  "extractor": "./my-extractor.ts",
  "patterns": ["src/**/*.{vue,ts,tsx}"]
}

方式三：本地路径

也可以直接从源码构建后使用：

tolgee extract print \
  --extractor ./path/to/tolgee-i18next-extractor/dist/index.js \
  --patterns 'src/**/*.{vue,ts,tsx}'

常用命令

# 打印提取结果（调试用）
tolgee extract print

# 检查提取警告
tolgee extract check

# 对比本地与平台的差异
tolgee compare

# 同步到 Tolgee 平台
tolgee sync

项目结构

src/
├── index.ts              # Tolgee custom extractor 入口
├── extractor.ts          # I18NextExtractor 类
├── parser.ts             # 按文件扩展名分发 Lexer
├── helpers.ts            # 工具函数
└── lexers/
    ├── base-lexer.ts     # 基类
    ├── javascript-lexer.ts   # JS/TS（TypeScript Compiler API）
    ├── jsx-lexer.ts          # JSX/TSX
    ├── vue-lexer.ts          # Vue SFC
    ├── html-lexer.ts         # HTML
    └── handlebars-lexer.ts   # Handlebars