@fallegahq/i18n-scanner

Advanced i18n translation key scanner with enum and type inference support for TypeScript/React projects.

Features

• 🔍 Smart Type Inference: Automatically resolves types from React.FC, useState, and function parameters
• 🎯 Enum Support: Expands template literals with enum values and string literal unions
• 📦 Property Literal Collection: Scans codebase for actual string values used in properties
• 🔄 Array Type Tracking: Follows types through .map(), .filter(), .sort(), and other array methods
• 🎨 React Patterns: Supports React.FC, destructured props, and useState generics
• 🤖 Automation Ready: -y, -n, and --ci/--cd flags for CI/CD pipelines
• 📊 Barrel Export Support: Resolves types through barrel exports and re-exports

Installation

npm install @fallegahq/i18n-scanner

Or install globally:

npm install -g @fallegahq/i18n-scanner

Usage

Basic Usage

# Scan src/i18n and prompt for missing keys
i18n-scanner

# Scan custom directories
i18n-scanner src locales

# Auto-add missing keys without prompting
i18n-scanner -y

# Scan only, don't add keys
i18n-scanner -n

# CI/CD mode (never prompts, never writes; exits non-zero if missing keys are found)
i18n-scanner --ci
i18n-scanner --cd

# Show help
i18n-scanner --help

Command Line Options

Usage: i18n-scanner [sourceDir] [i18nFolder] [options]

Arguments:
  sourceDir    Source directory to scan (default: "src")
  i18nFolder   i18n folder name (default: "i18n")

Options:
  -y, --yes    Automatically add missing keys without prompting
  -n, --no     Skip adding missing keys without prompting
  --ci, --cd   CI mode: never prompt, never write, fail if missing keys are found
  -h, --help   Show this help message

Examples

# Interactive mode (prompts user)
i18n-scanner

# Auto-add missing keys without prompting
i18n-scanner -y

# Scan only, don't add keys
i18n-scanner -n

# CI/CD mode: fail the pipeline if there are missing keys
i18n-scanner --ci

# Custom paths with auto-add
i18n-scanner src i18n -y

CI/CD Usage

Use --ci (or --cd) in your pipeline when you want the job to fail if missing keys are detected.

• No prompts
• No file writes (acts like -n)
• Exit codes
  • 0: no missing keys found
  • 2: missing keys found (CI/CD failure)

Example:

i18n-scanner --ci

How It Works

The scanner analyzes your TypeScript/React codebase to find translation keys used in t() function calls. It supports:

Template Literals with Variables

// Automatically expands to all possible values
t(`messages.${message.type}`)
// Resolves: messages.info, messages.warning, messages.error, etc.

React Component Props

interface UserListProps {
    users: User[];
}

const UserList: React.FC<UserListProps> = ({ users }) => {
    // Scanner knows 'users' is User[]
    users.map(user => t(`user.role.${user.role}`))
}

useState Generics

const [selectedItem, setSelectedItem] = useState<Item|null>(null);
// Scanner knows selectedItem is Item
t(`item.status.${selectedItem.status}`)

Enum Values

enum UserRole {
    Admin = "admin",
    User = "user",
    Guest = "guest"
}

// Automatically expands to all enum values
t(`user.role.${userRole}`)
// Resolves: user.role.admin, user.role.user, user.role.guest

Project Structure

Your i18n folder should contain locale files:

src/
  i18n/
    index.ts      # Main i18n configuration
    en.ts         # English translations
    fr.ts         # French translations
    ...

Each locale file should export a default object with translation keys:

export default {
    "common.welcome": "Welcome",
    "common.loading": "Loading...",
    "user.role.admin": "Administrator",
    "user.role.user": "User",
    "messages.error": "An error occurred",
    // ...
}

Requirements

• Node.js >= 22.0.0
• TypeScript project with i18n translation files

Development

Run tests:

npm test

License

MIT