npm package: @shmaha_kuparbarg/i18n-extractor
Description: Intelligent i18n string extraction CLI for TypeScript projects - Extract, classify, and translate strings automatically
Latest version: 0.1.1

# i18n-extractor 🌍

> **Intelligent i18n string extraction for modern web projects**

Automatically detect, extract, classify, and translate UI strings from your codebase using AST analysis.

[![npm version](https://img.shields.io/npm/v/i18n-extractor.svg)](https://www.npmjs.com/package/i18n-extractor)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## ✨ 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

```bash
# 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:

```bash
# 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

```bash
# Extract strings to JSON
i18n-extractor extract "./src/**/*.ts" --output ./i18n

# Verbose output
i18n-extractor extract "./src/**/*.ts" -v
```

### `transform` - Add i18n Function Calls

```bash
# Transform code to use t() function
i18n-extractor transform "./src/**/*.ts" --locale ./i18n/en.json
```

### `translate` - Translate JSON Files

```bash
# Translate existing JSON to other languages
i18n-extractor translate ./i18n/en.json --languages he,es
```

### `init` - Create Configuration

```bash
# 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:

```json
{
  "framework": "lit",
  "sourceLanguage": "en",
  "targetLanguages": ["he", "es", "de"],
  "paths": {
    "source": "./src/**/*.ts",
    "translations": "./i18n"
  },
  "transformation": {
    "functionName": "t",
    "importFrom": "./i18n",
    "keyStrategy": "descriptive"
  }
}
```

## 🔧 Programmatic Usage

```typescript
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](https://github.com/i18n-extractor/i18n-extractor/blob/main/CONTRIBUTING.md) for guidelines.

## 📄 License

MIT © i18n-extractor team