i18next-turbo ⚡️

Blazing fast i18next translation key extractor - 10-100x faster with Rust + SWC

i18next-turbo is a blazing fast replacement for i18next-parser and i18next-cli. Built with Rust and SWC, it processes thousands of files in milliseconds.

⚠️ Under Development: Currently available as a Rust binary. npm package distribution is in preparation.

🚀 Why i18next-turbo?

Performance Comparison

| Tool | Engine | Processing Time (1k files) | Watch Mode | |:---|:---|:---|:---| | i18next-parser | Node.js (Babel/Regex) | 10-30s | Slow / High CPU | | i18next-cli | Node.js (SWC) | 2-5s | Moderate | | i18next-turbo | Rust + SWC | < 100ms ⚡️ | Instant / Low footprint |

Benchmark Results (MacBook Pro M3, 1,000 files):

i18next-parser:  ████████████████████ 12.5s
i18next-cli:     ████████ 2.3s
i18next-turbo:   ▏ 0.08s ⚡️ (~150x faster)

Key Features

• ⚡️ Blazing Fast: Instant processing even for large projects
• 🎯 High Accuracy: Full AST parsing with SWC for zero false positives
• 🔄 Real-time Updates: Watch mode updates JSON files the moment you save
• 🛡️ Preserves Translations: New keys are added without touching existing translations
• 📦 Lightweight: Low memory usage, comfortable background execution
• 🔧 i18next Compatible: Supports namespaces, plurals, context, and more

✨ Implemented Features

Basic Extraction Patterns

// ✅ Supported
t('hello.world')
i18n.t('greeting')
t('common:button.save')  // With namespace

React Components

// ✅ Trans component
<Trans i18nKey="welcome">Welcome</Trans>
<Trans i18nKey="common:greeting" defaults="Hello!" />

Plurals and Context

// ✅ Plurals
t('apple', { count: 5 })  // → apple_one, apple_other

// ✅ Context
t('friend', { context: 'male' })  // → friend_male

// ✅ Plurals + Context
t('friend', { count: 2, context: 'female' })  // → friend_female_one, friend_female_other

Other Features

• ✅ Magic Comments: // i18next-extract-disable-line
• ✅ Nested Keys: button.submit → {"button": {"submit": ""}}
• ✅ Auto-sorted Keys: Alphabetically sorted for consistent JSON
• ✅ TypeScript Type Generation: Autocomplete and type safety
• ✅ Dead Key Detection: Find unused keys after refactoring

📦 Installation

Method 1: Install via Cargo (Recommended)

cargo install i18next-turbo

Method 2: Build from Source

git clone https://github.com/your-username/i18next-turbo.git
cd i18next-turbo
cargo build --release
# Binary will be generated at target/release/i18next-turbo

📌 Note: npm package distribution is in preparation. For Node.js projects, Rust installation is currently required.

🛠️ Usage

1. Create Configuration File

Create i18next-turbo.json in your project root:

{
  "input": ["src/**/*.{ts,tsx,js,jsx}"],
  "output": "locales/$LOCALE/$NAMESPACE.json",
  "locales": ["en", "ja", "de"],
  "defaultNamespace": "translation",
  "functions": ["t", "i18n.t"],
  "types": {
    "output": "src/@types/i18next.d.ts",
    "defaultLocale": "en",
    "localesDir": "locales"
  }
}

Configuration Options

| Option | Description | Default | |:---|:---|:---| | input | File patterns to extract (glob) | ["src/**/*.{ts,tsx,js,jsx}"] | | output | Output path ($LOCALE and $NAMESPACE are replaced) | "locales" | | locales | List of target languages | ["en"] | | defaultNamespace | Default namespace | "translation" | | functions | Function names to extract | ["t"] | | types.output | Path for generated TypeScript definitions | "src/@types/i18next.d.ts" | | types.defaultLocale | Default locale for type generation | First entry in locales | | types.localesDir | Directory read when generating types | Same as output |

Use the optional types block to control where type definitions are written and which locale files i18next-turbo typegen or i18next-turbo extract --generate-types should use.

2. Extract Keys

Run once (e.g., for CI/CD):

i18next-turbo extract

Example Output

=== i18next-turbo extract ===

Configuration:
  Input patterns: ["src/**/*.{ts,tsx}"]
  Output: locales
  Locales: ["en", "ja"]
  Functions: ["t"]

Extracted keys by file:
------------------------------------------------------------

src/components/Button.tsx
  - button.submit
  - button.cancel

src/pages/Home.tsx
  - welcome.title
  - welcome.message

------------------------------------------------------------

Extraction Summary:
  Files processed: 2
  Unique keys found: 4

Syncing to locale files...
  locales/en/translation.json - added 4 new key(s)

Done!

3. Watch Mode (Development)

Automatically extract and update keys on file save:

i18next-turbo watch

Example Behavior

=== i18next-turbo watch ===

Watching: src
Watching for changes... (Ctrl+C to stop)

--- Change detected ---
  Modified: src/components/Button.tsx
  Added 1 new key(s)
--- Sync complete ---

Run this command in the background during development to automatically update JSON files when you add translation keys.

4. Translation Status

Check translation progress for a specific locale:

i18next-turbo status --locale ja

Useful flags:

• --namespace <name>: limit the report to a single namespace
• --fail-on-incomplete: exit with a non-zero status when missing or dead keys are found (great for CI)

The summary includes a textual progress bar so you can instantly gauge completion status for the selected locale/namespace.

📝 Examples

Basic Usage

// src/components/Button.tsx
import { useTranslation } from 'react-i18next';

function Button() {
  const { t } = useTranslation();
  
  return (
    <button>
      {t('button.submit')}
    </button>
  );
}

After running, locales/en/translation.json will have:

{
  "button": {
    "submit": ""
  }
}

Using Namespaces

// Specify namespace
t('common:button.save')  // → Saved to locales/en/common.json

React Trans Component

import { Trans } from 'react-i18next';

function Welcome() {
  return (
    <Trans i18nKey="welcome.title" defaults="Welcome!">
      Welcome to our app!
    </Trans>
  );
}

Using Plurals

const count = 5;
t('apple', { count });  // → Generates apple_one, apple_other

Generated JSON:

{
  "apple_one": "",
  "apple_other": ""
}

🎯 Migration from i18next-parser

If you're using i18next-parser, you can migrate with minimal changes to your configuration.

Configuration Differences

| i18next-parser | i18next-turbo | |:---|:---| | input | input (same) | | output | output (same) | | locales | locales (same) | | defaultNamespace | defaultNamespace (same) | | functions | functions (same) |

Basically the same configuration works!

Migration Steps

1. Create i18next-turbo.json (copy your existing config)
2. Run i18next-turbo extract
3. Verify generated JSON files
4. Start development with watch mode

i18next-cli Config Compatibility

i18next-turbo can read i18next-cli config files and map a subset of extract options.

Supported mappings:

| i18next-cli (extract) | i18next-turbo | |:---|:---| | input | input | | output (string) | output (directory) | | functions | functions | | defaultNS | defaultNamespace | | keySeparator | keySeparator (false -> empty string) | | nsSeparator | nsSeparator (false -> empty string) | | contextSeparator | contextSeparator | | pluralSeparator | pluralSeparator | | extractFromComments | extractFromComments (default true) |

Not supported:

| i18next-cli (extract) | Reason | |:---|:---| | output (function) | Function output is not supported | | defaultNS = false | Namespace-less mode is not supported | | ignore | Not implemented in i18next-turbo | | transComponents | Not implemented in i18next-turbo | | useTranslationNames | Not implemented in i18next-turbo | | transKeepBasicHtmlNodesFor | Not implemented in i18next-turbo | | preservePatterns | Not implemented in i18next-turbo | | preserveContextVariants | Not implemented in i18next-turbo | | sort | Not implemented in i18next-turbo | | indentation | Not implemented in i18next-turbo | | defaultValue | Not implemented in i18next-turbo | | primaryLanguage / secondaryLanguages | Not implemented in i18next-turbo | | outputFormat | Not implemented in i18next-turbo | | mergeNamespaces | Not implemented in i18next-turbo | | removeUnusedKeys | Not implemented in i18next-turbo | | generateBasePluralForms | Not implemented in i18next-turbo | | disablePlurals | Not implemented in i18next-turbo | | nestingPrefix / nestingSuffix / nestingOptionsSeparator | Not implemented in i18next-turbo | | interpolationPrefix / interpolationSuffix | Not implemented in i18next-turbo |

Notes:

• Output templates like locales/{{language}}/{{namespace}}.json are reduced to a base directory.

🔧 Advanced Features

Magic Comments

Exclude specific lines from extraction:

// i18next-extract-disable-line
const dynamicKey = `user.${role}.permission`;
t(dynamicKey);  // This line won't be extracted

TypeScript Type Generation

# Generate once based on your config (honors the optional `types` block)
i18next-turbo typegen

# Or run extraction and type generation together
i18next-turbo extract --generate-types

Example generated type definitions:

interface Translation {
  button: {
    submit: string;
    cancel: string;
  };
  welcome: {
    title: string;
    message: string;
  };
}

Dead Key Detection

# Will be available as i18next-turbo cleanup command in the future
# Detects keys not found in code

📊 Performance

Benchmark Results

| Files | i18next-parser | i18next-cli | i18next-turbo | |:---|:---:|:---:|:---:| | 100 | 1.2s | 0.3s | 0.01s | | 1,000 | 12.5s | 2.3s | 0.08s | | 10,000 | 125s | 23s | 0.8s |

Memory Usage

• i18next-parser: ~200MB
• i18next-cli: ~150MB
• i18next-turbo: ~50MB (~4x lighter)

🗺️ Roadmap

✅ Implemented

• [x] Basic t() function extraction
• [x] <Trans> component support
• [x] Namespace support
• [x] Plurals (basic _one, _other)
• [x] Context support
• [x] Watch mode
• [x] JSON synchronization (preserves existing translations)
• [x] TypeScript type generation
• [x] Dead key detection

🚧 In Development

• [ ] npm package distribution
• [ ] Full useTranslation hook support (keyPrefix, etc.)
• [ ] Language-specific plural categories (zero, few, many, etc.)
• [ ] JS/TS config file loading

📅 Planned

• [ ] Locize integration

See TODO.md for details.

🤝 Contributing

Pull requests and issue reports are welcome!

1. Fork this repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Please read CONTRIBUTING.md for details on our code of conduct.

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• i18next - Amazing internationalization framework
• SWC - Fast JavaScript/TypeScript compiler
• i18next-parser - Source of inspiration

⚠️ Disclaimer

• This tool is an unofficial i18next tool
• Currently under development, APIs may change
• npm package distribution is in preparation (Rust installation required)

Questions or issues? Please open an Issue!

i18next-turbo ⚡️

超高速な i18next 翻訳キー抽出ツール - Rust + SWC で実現する 10-100倍の速度向上

i18next-turbo は、既存の i18next-parser や i18next-cli の超高速な代替品です。Rust と SWC を使用して、数千ファイルをミリ秒単位で処理します。

⚠️ 開発中: 現在は Rust バイナリとして利用可能です。npm パッケージとしての配布は準備中です。

🚀 なぜ i18next-turbo なのか？

速度比較

| ツール | エンジン | 1,000ファイルの処理時間 | Watch モード | |:---|:---|:---|:---| | i18next-parser | Node.js (Babel/Regex) | 10-30秒 | 遅い / CPU使用率高 | | i18next-cli | Node.js (SWC) | 2-5秒 | 中程度 | | i18next-turbo | Rust + SWC | < 100ms ⚡️ | 即座に反応 / 低負荷 |

実測値（MacBook Pro M3、1,000ファイル）:

i18next-parser:  ████████████████████ 12.5s
i18next-cli:     ████████ 2.3s
i18next-turbo:   ▏ 0.08s ⚡️ (約150倍高速)

主な特徴

• ⚡️ 圧倒的な速度: 大規模プロジェクトでも瞬時に処理完了
• 🎯 高精度な抽出: SWC による完全な AST 解析で誤検知ゼロ
• 🔄 リアルタイム更新: Watch モードでファイル保存と同時に JSON を更新
• 🛡️ 既存翻訳を保護: 新しいキーを追加しても、既存の翻訳は完全に保持
• 📦 軽量: 低メモリ使用量、バックグラウンド実行も快適
• 🔧 i18next 完全対応: 名前空間、複数形、コンテキストなど主要機能をサポート

✨ 実装済み機能

基本的な抽出パターン

// ✅ サポート済み
t('hello.world')
i18n.t('greeting')
t('common:button.save')  // 名前空間付き

React コンポーネント

// ✅ Trans コンポーネント
<Trans i18nKey="welcome">Welcome</Trans>
<Trans i18nKey="common:greeting" defaults="Hello!" />

複数形とコンテキスト

// ✅ 複数形
t('apple', { count: 5 })  // → apple_one, apple_other

// ✅ コンテキスト
t('friend', { context: 'male' })  // → friend_male

// ✅ 複数形 + コンテキスト
t('friend', { count: 2, context: 'female' })  // → friend_female_one, friend_female_other

その他の機能

• ✅ マジックコメント: // i18next-extract-disable-line
• ✅ ネストされたキー: button.submit → {"button": {"submit": ""}}
• ✅ キーの自動ソート: アルファベット順で一貫性のある JSON
• ✅ TypeScript 型定義生成: 自動補完と型安全性
• ✅ 未使用キーの検知: リファクタリングで不要になったキーを発見

📦 インストール

方法 1: Cargo からインストール（推奨）

cargo install i18next-turbo

方法 2: ソースからビルド

git clone https://github.com/your-username/i18next-turbo.git
cd i18next-turbo
cargo build --release
# バイナリは target/release/i18next-turbo に生成されます

📌 注意: npm パッケージとしての配布は準備中です。Node.js プロジェクトでの使用は、Rust がインストールされている環境が必要です。

🛠️ 使い方

1. 設定ファイルの作成

プロジェクトのルートに i18next-turbo.json を作成します：

{
  "input": ["src/**/*.{ts,tsx,js,jsx}"],
  "output": "locales/$LOCALE/$NAMESPACE.json",
  "locales": ["en", "ja", "de"],
  "defaultNamespace": "translation",
  "functions": ["t", "i18n.t"],
  "types": {
    "output": "src/@types/i18next.d.ts",
    "defaultLocale": "en",
    "localesDir": "locales"
  }
}

設定オプション

| オプション | 説明 | デフォルト | |:---|:---|:---| | input | 抽出対象のファイルパターン（glob） | ["src/**/*.{ts,tsx,js,jsx}"] | | output | 出力先のパス（$LOCALE と $NAMESPACE が置換される） | "locales" | | locales | 対象言語のリスト | ["en"] | | defaultNamespace | デフォルトの名前空間 | "translation" | | functions | 抽出対象の関数名 | ["t"] | | types.output | 型定義ファイルの出力パス | "src/@types/i18next.d.ts" | | types.defaultLocale | 型生成時に使用するデフォルトロケール | locales の先頭 | | types.localesDir | 型生成時に読むロケールディレクトリ | output と同じ |

types ブロックを設定すると、i18next-turbo typegen や i18next-turbo extract --generate-types が参照する出力パスやロケールを制御できます。

2. キーの抽出

一度だけ実行する場合（CI/CD など）：

i18next-turbo extract

出力例

=== i18next-turbo extract ===

Configuration:
  Input patterns: ["src/**/*.{ts,tsx}"]
  Output: locales
  Locales: ["en", "ja"]
  Functions: ["t"]

Extracted keys by file:
------------------------------------------------------------

src/components/Button.tsx
  - button.submit
  - button.cancel

src/pages/Home.tsx
  - welcome.title
  - welcome.message

------------------------------------------------------------

Extraction Summary:
  Files processed: 2
  Unique keys found: 4

Syncing to locale files...
  locales/en/translation.json - added 4 new key(s)

Done!

3. Watch モード（開発時）

ファイルを保存するたびに自動でキーを抽出・更新します：

i18next-turbo watch

動作例

=== i18next-turbo watch ===

Watching: src
Watching for changes... (Ctrl+C to stop)

--- Change detected ---
  Modified: src/components/Button.tsx
  Added 1 new key(s)
--- Sync complete ---

開発中はこのコマンドをバックグラウンドで実行しておくと、翻訳キーを追加するたびに自動で JSON ファイルが更新されます。

📝 使用例

基本的な使用例

// src/components/Button.tsx
import { useTranslation } from 'react-i18next';

function Button() {
  const { t } = useTranslation();
  
  return (
    <button>
      {t('button.submit')}
    </button>
  );
}

実行後、locales/en/translation.json に以下が追加されます：

{
  "button": {
    "submit": ""
  }
}

名前空間の使用

// 名前空間を指定
t('common:button.save')  // → locales/en/common.json に保存

React Trans コンポーネント

import { Trans } from 'react-i18next';

function Welcome() {
  return (
    <Trans i18nKey="welcome.title" defaults="Welcome!">
      Welcome to our app!
    </Trans>
  );
}

複数形の使用

const count = 5;
t('apple', { count });  // → apple_one, apple_other が生成される

生成される JSON:

{
  "apple_one": "",
  "apple_other": ""
}

🎯 i18next-parser からの移行

既存の i18next-parser を使用している場合、設定ファイルを少し変更するだけで移行できます。

設定ファイルの違い

| i18next-parser | i18next-turbo | |:---|:---| | input | input (同じ) | | output | output (同じ) | | locales | locales (同じ) | | defaultNamespace | defaultNamespace (同じ) | | functions | functions (同じ) |

基本的に同じ設定が使えます！

移行手順

1. i18next-turbo.json を作成（既存の設定をコピー）
2. i18next-turbo extract を実行
3. 生成された JSON ファイルを確認
4. Watch モードで開発を開始

i18next-cli 設定との互換性

i18next-turbo は i18next-cli の設定ファイルを読み込み、一部の extract 設定をマッピングします。

対応するマッピング:

| i18next-cli (extract) | i18next-turbo | |:---|:---| | input | input | | output (文字列) | output (ディレクトリ) | | functions | functions | | defaultNS | defaultNamespace | | keySeparator | keySeparator (false -> 空文字) | | nsSeparator | nsSeparator (false -> 空文字) | | contextSeparator | contextSeparator | | pluralSeparator | pluralSeparator | | extractFromComments | extractFromComments（デフォルト true） |

未対応:

| i18next-cli (extract) | 理由 | |:---|:---| | output (関数) | 関数出力は未対応 | | defaultNS = false | namespace 無効は未対応 | | ignore | 未実装 | | transComponents | 未実装 | | useTranslationNames | 未実装 | | transKeepBasicHtmlNodesFor | 未実装 | | preservePatterns | 未実装 | | preserveContextVariants | 未実装 | | sort | 未実装 | | indentation | 未実装 | | defaultValue | 未実装 | | primaryLanguage / secondaryLanguages | 未実装 | | outputFormat | 未実装 | | mergeNamespaces | 未実装 | | removeUnusedKeys | 未実装 | | generateBasePluralForms | 未実装 | | disablePlurals | 未実装 | | nestingPrefix / nestingSuffix / nestingOptionsSeparator | 未実装 | | interpolationPrefix / interpolationSuffix | 未実装 |

注意点:

• locales/{{language}}/{{namespace}}.json のようなテンプレート出力はベースディレクトリに変換します。

🔧 高度な機能

マジックコメント

特定の行を抽出対象から除外：

// i18next-extract-disable-line
const dynamicKey = `user.${role}.permission`;
t(dynamicKey);  // この行は抽出されません

TypeScript 型定義の生成

# `types` 設定に基づいて一度だけ型定義を生成
i18next-turbo typegen

# もしくは抽出と同時に生成
i18next-turbo extract --generate-types

生成される型定義例：

interface Translation {
  button: {
    submit: string;
    cancel: string;
  };
  welcome: {
    title: string;
    message: string;
  };
}

未使用キーの検知

# 将来的に i18next-turbo cleanup コマンドで利用可能
# コードから見つからないキーを検出

📊 パフォーマンス

ベンチマーク結果

| ファイル数 | i18next-parser | i18next-cli | i18next-turbo | |:---|:---:|:---:|:---:| | 100 | 1.2s | 0.3s | 0.01s | | 1,000 | 12.5s | 2.3s | 0.08s | | 10,000 | 125s | 23s | 0.8s |

メモリ使用量

• i18next-parser: ~200MB
• i18next-cli: ~150MB
• i18next-turbo: ~50MB (約4倍軽量)

🗺️ ロードマップ

✅ 実装済み

• [x] 基本的な t() 関数の抽出
• [x] <Trans> コンポーネントのサポート
• [x] 名前空間のサポート
• [x] 複数形（基本的な _one, _other）
• [x] コンテキストのサポート
• [x] Watch モード
• [x] JSON 同期（既存翻訳の保持）
• [x] TypeScript 型定義生成
• [x] 未使用キーの検知

🚧 開発中

• [ ] npm パッケージとしての配布
• [ ] useTranslation hook の完全サポート（keyPrefix など）
• [ ] 言語別複数形カテゴリの生成（zero, few, many など）
• [ ] JS/TS 設定ファイルの読み込み

📅 計画中

• [ ] status コマンド（翻訳完了率の表示）
• [ ] sync コマンド（ロケール間の同期）
• [ ] lint コマンド（ハードコードされた文字列の検出）
• [ ] rename-key コマンド（キーの一括リネーム）
• [ ] Locize 統合

詳細は TODO.md を参照してください。

🤝 貢献

プルリクエストやイシューの報告を歓迎します！

1. このリポジトリをフォーク
2. フィーチャーブランチを作成 (git checkout -b feature/amazing-feature)
3. 変更をコミット (git commit -m 'Add some amazing feature')
4. ブランチにプッシュ (git push origin feature/amazing-feature)
5. プルリクエストを開く

詳細は CONTRIBUTING.md を参照してください。

📄 ライセンス

MIT License - 詳細は LICENSE を参照してください。

🙏 謝辞

• i18next - 素晴らしい国際化フレームワーク
• SWC - 高速な JavaScript/TypeScript コンパイラ
• i18next-parser - インスピレーションの源

⚠️ 注意事項

• このツールは i18next の非公式ツールです
• 現在は 開発中 のため、API が変更される可能性があります
• npm パッケージとしての配布は準備中です（Rust のインストールが必要です）

質問や問題があれば、Issues でお知らせください！