npm package: @shmaha_kuparbarg/i18n-extractor-core
Description: Core extraction engine for i18n-extractor - AST-based string extraction with smart classification
Author: i18n-extractor team
Latest version: 0.1.0

# @i18n-extractor/core

Core extraction engine for intelligent i18n string detection and transformation.

## Features

- 🎯 **Smart Detection** - Distinguishes UI strings from technical values using AST analysis
- 🔍 **TypeScript-First** - Built on TypeScript Compiler API for accurate parsing
- 🚀 **Zero Config** - Works out of the box with sensible defaults
- 🎨 **Framework Agnostic** - Plugin architecture for React, Vue, Angular, Lit, and more
- 🔑 **Meaningful Keys** - Generates descriptive translation keys from context
- 🔄 **Incremental** - Safely merges with existing translations
- 📦 **Modular** - Use individual components or the complete pipeline

## Installation

```bash
pnpm add @i18n-extractor/core
```

## Quick Start

```typescript
import { createExtractor } from '@i18n-extractor/core';

// Create extractor with configuration
const extractor = createExtractor({
  framework: 'lit',
  paths: {
    source: 'src/**/*.ts',
    translations: 'src/i18n',
  },
  transformation: {
    functionName: 't',
    importFrom: './i18n',
  },
});

// Run extraction
const result = await extractor.extract();

// Review results
console.log(`Found ${result.stats.stringsFound} translatable strings`);
console.log(`Generated ${result.stats.keysGenerated} unique keys`);

// Apply transformations
await extractor.applyTransformations(result);

// Save translation files
await extractor.saveTranslations(result);
```

## API

### `createExtractor(config: ExtractorConfig)`

Creates a new extractor instance with the provided configuration.

#### Configuration Options

```typescript
interface ExtractorConfig {
  // Framework plugin to use
  framework: 'lit' | 'react' | 'vue' | 'angular' | 'vanilla';

  // Source and target languages
  sourceLanguage?: string; // default: 'en'
  targetLanguages?: string[]; // default: []

  // File paths
  paths: {
    source: string | string[]; // Glob patterns
    translations: string; // Output directory
  };

  // Extraction rules
  extraction?: {
    skipPatterns?: RegExp[]; // Additional skip patterns
    includeKeys?: string[]; // Property names to include
    excludeKeys?: string[]; // Property names to exclude
    skipTranslated?: boolean; // Skip already translated strings
  };

  // Transformation settings
  transformation?: {
    functionName: string; // default: 't'
    importFrom: string; // Import path for function
    keyPrefix?: string; // Prefix for all keys
    keyStrategy?: 'descriptive' | 'hash' | 'sequential'; // default: 'descriptive'
  };

  // Output format
  output?: {
    format: 'json' | 'yaml' | 'po'; // default: 'json'
    nested?: boolean; // Use nested structure, default: true
    sortKeys?: boolean; // Sort keys alphabetically, default: true
  };
}
```

### `Extractor Methods`

#### `extract(): Promise<ExtractorResult>`

Scans source files and extracts translatable strings.

Returns:
```typescript
interface ExtractorResult {
  matches: StringMatch[]; // All detected strings
  translationKeys: Record<string, string>; // Key -> Text mapping
  modifiedFiles: Map<string, string>; // File -> Transformed code
  stats: {
    filesScanned: number;
    filesModified: number;
    stringsFound: number;
    keysGenerated: number;
  };
}
```

#### `applyTransformations(result: ExtractorResult, dryRun?: boolean): Promise<void>`

Applies code transformations to source files. Set `dryRun: true` to preview without writing.

#### `saveTranslations(result: ExtractorResult): Promise<void>`

Saves extracted translation keys to file(s), merging with existing translations.

## Advanced Usage

### Custom Detection Rules

```typescript
import { StringDetector } from '@i18n-extractor/core';

const detector = new StringDetector();

// Add custom skip pattern
detector.addSkipPattern(/^icon-/);

// Add custom UI property name
detector.addUIKey('ariaLabel');

// Add custom technical property name
detector.addTechnicalKey('dataTestId');
```

### Custom Key Generation

```typescript
import { KeyGenerator } from '@i18n-extractor/core';

const keyGen = new KeyGenerator({
  prefix: 'app',
  strategy: 'descriptive',
  maxLength: 60,
});

const key = keyGen.generateKey(
  'Welcome to our app',
  'home/hero-section.ts',
  'title'
);
// Result: "app.hero-section.title-welcome-to-our-app"
```

### Manual Parsing

```typescript
import { ASTParser, StringDetector, KeyGenerator } from '@i18n-extractor/core';
import * as ts from 'typescript';

const detector = new StringDetector();
const keyGen = new KeyGenerator({ strategy: 'descriptive' });
const parser = new ASTParser(detector, keyGen);

// Create TypeScript program
const program = ts.createProgram(['src/app.ts'], {});
const sourceFile = program.getSourceFile('src/app.ts');

// Parse for matches
const matches = parser.parseFile('src/app.ts', sourceFile!);

console.log(`Found ${matches.length} strings to translate`);
```

### Custom Transformation

```typescript
import { CodeTransformer } from '@i18n-extractor/core';

const transformer = new CodeTransformer({
  transformation: {
    functionName: 'i18n.t',
    importFrom: '@/i18n',
  },
  // ... other config
});

const transformed = transformer.transformFile(filePath, sourceFile, matches);
```

## Default Behavior

### Strings Automatically Skipped

- Icon names (`icon-*`, `codicon-*`)
- CSS classes (kebab-case like `bg-primary`)
- Technical IDs and constants
- URLs and file paths
- Already translated strings (wrapped in `t()`)
- Import/export statements
- CSS/style blocks

### Strings Automatically Included

- Strings with spaces (likely sentences)
- Strings in UI properties (`label`, `title`, `placeholder`, `description`)
- Strings starting with capital letter (> 5 chars)
- Common UI words (`yes`, `no`, `ok`, `cancel`, `save`, `delete`)

### Key Generation

**Descriptive Strategy** (default):
- Combines: prefix + namespace + property + normalized-text
- Example: `search.placeholder-enter-commit-message`

**Hash Strategy**:
- SHA-based hash of text + context
- Example: `k_a3f2b9c`

**Sequential Strategy**:
- Auto-incrementing numbers
- Example: `key_1`, `key_2`, `key_3`

## Examples

See the `examples/` directory for complete working examples:

- `examples/lit-app` - Lit web components
- `examples/react-app` - React application
- `examples/vue-app` - Vue.js application

## Architecture

```
┌─────────────────┐
│  ExtractorConfig │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   I18nExtractor  │ ◄─── Main orchestrator
└────────┬────────┘
         │
    ┌────┴────┬─────────┬──────────┐
    ▼         ▼         ▼          ▼
┌──────┐ ┌────────┐ ┌───────┐ ┌────────────┐
│Parser│ │Detector│ │KeyGen │ │Transformer │
└──────┘ └────────┘ └───────┘ └────────────┘
   │         │          │           │
   ▼         ▼          ▼           ▼
  AST    IsUIString  GenerateKey TransformCode
```

## License

MIT

## Contributing

See [CONTRIBUTING.md](../../CONTRIBUTING.md) for guidelines.