@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

pnpm add @i18n-extractor/core

Quick Start

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

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:

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

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

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

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

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 for guidelines.