i18n-extractor 🌍

Intelligent i18n string extraction for modern web projects

Automatically detect, extract, classify, and translate UI strings from your codebase using AST analysis.

✨ Features

• 🎯 Smart Detection - Distinguishes UI strings from technical values (icons, CSS classes, IDs)
• 🔌 14 File Types - TypeScript, JavaScript, Vue, HTML, CSS, JSON, YAML, Python, and more
• 🤖 Auto Translation - Integrated Google Translate support
• 📊 Classification - Categorizes strings as UI, Error, Warning, Technical, etc.
• ⚡ Performance - Pre-classification skips irrelevant files
• 🔄 Safe Transform - Adds t() calls while preserving code structure

🚀 Quick Start

# Install globally
npm install -g i18n-extractor

# Or use npx
npx i18n-extractor smart ./my-project --languages he,es

📖 Commands

smart - Full Pipeline (Recommended)

The smart command analyzes your project and runs the complete i18n pipeline:

# Basic usage - extract and translate to Hebrew
i18n-extractor smart ./src --languages he

# Dry run - see what would happen without making changes
i18n-extractor smart ./src --dry-run

# Multiple languages
i18n-extractor smart ./src --languages he,es,de,fr

# Skip translation (extraction only)
i18n-extractor smart ./src --skip-translate

# Custom output directory
i18n-extractor smart ./src --output ./locales

extract - Extract Strings Only

# Extract strings to JSON
i18n-extractor extract "./src/**/*.ts" --output ./i18n

# Verbose output
i18n-extractor extract "./src/**/*.ts" -v

transform - Add i18n Function Calls

# Transform code to use t() function
i18n-extractor transform "./src/**/*.ts" --locale ./i18n/en.json

translate - Translate JSON Files

# Translate existing JSON to other languages
i18n-extractor translate ./i18n/en.json --languages he,es

init - Create Configuration

# Create i18n.config.json
i18n-extractor init --framework lit

📁 Supported File Types

| Category | Extensions | Features | |----------|------------|----------| | Code | .ts, .tsx, .js, .jsx | AST parsing, import injection | | Vue | .vue | SFC support, template extraction | | HTML | .html, .htm | Attribute extraction, data-i18n | | CSS | .css, .scss | Content property extraction | | Data | .json, .yaml, .yml | Value extraction | | Python | .py | Django/Flask/FastAPI support | | i18n | .po, .pot, .properties, .resx | Native format support |

🎯 Smart Classification

The tool automatically classifies strings:

| Category | Example | Action | |----------|---------|--------| | UI | "Save changes" | ✅ Translate | | Error | "Failed to load" | ✅ Translate | | Warning | "Are you sure?" | ✅ Translate | | Technical | "gitlens.show" | ❌ Skip | | CSS | "0 10px 20px" | ❌ Skip | | Icon | "$(folder)" | ❌ Skip |

📊 Output Format

For VS Code Extensions

./i18n/
├── bundle.l10n.json      # Main strings
├── bundle.l10n.he.json   # Hebrew translations
├── package.nls.json      # Package manifest strings
└── package.nls.he.json   # Package manifest Hebrew

For Web Projects

./i18n/
├── en.json               # Source language
├── he.json               # Hebrew
├── es.json               # Spanish
└── extraction-report.json

⚙️ Configuration

Create i18n.config.json in your project root:

{
  "framework": "lit",
  "sourceLanguage": "en",
  "targetLanguages": ["he", "es", "de"],
  "paths": {
    "source": "./src/**/*.ts",
    "translations": "./i18n"
  },
  "transformation": {
    "functionName": "t",
    "importFrom": "./i18n",
    "keyStrategy": "descriptive"
  }
}

🔧 Programmatic Usage

import { createExtractor, classifyStrings } from '@i18n-extractor/core';

const extractor = createExtractor({
  framework: 'lit',
  paths: {
    source: './src/**/*.ts',
    translations: './i18n'
  }
});

const result = await extractor.extract();
const classified = classifyStrings(result.matches.map(m => ({
  text: m.text,
  file: m.file,
  line: m.line
})));

console.log(`Found ${classified.summary.toTranslate} translatable strings`);

📈 Performance

On a large project (GitLens - 950+ files):

| Metric | Value | |--------|-------| | Files scanned | 915 | | Pre-filtered (skipped) | 52 (5%) | | Strings extracted | 3,620 | | Classification time | 122ms |

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

📄 License

MIT © i18n-extractor team