# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

i18n-log is a TypeScript CLI tool that works as a linter for internationalization (i18n) issues in JavaScript/TypeScript projects. It scans source code and translation files to detect missing translations, unused keys, hardcoded text, and other i18n problems.

## Development Commands

```bash
# Build the project (required before testing)
npm run build

# Type checking
npm run lint

# Development mode (runs directly from source)
npm start [command] [options]

# Clean build artifacts
npm run clean

# Test with example app
cd example && npm install && npm run i18n:lint
```

## Architecture Overview

The codebase is organized into several key modules:

### Core Scanning Pipeline
- **scanner.ts**: Main analysis engine that uses Babel AST parsing to find translation usage and hardcoded text
- **config.ts**: Configuration loading with auto-discovery of config files (i18log.config.ts/js/json)
- **detector.ts**: Automatically detects translation paths by scanning for common i18n directory patterns

### Linter System
- **linter/**: Complete linting framework modeled after ESLint
  - **linter.ts**: Main linter class that processes scan reports and applies rules
  - **rules.ts**: Individual lint rules with configurable severity levels
  - **types.ts**: Type definitions for lint config, issues, and reports
  - **formatters/**: Output formatting (stylish, json, compact)

### CLI Interface
- **cli.ts**: Command-line interface with `init` and `lint` commands
- **report.ts**: Report generation and output formatting

### Key Data Flow
1. **Config Loading**: Auto-discover or load user config file
2. **Translation Discovery**: Load all translation JSON files and flatten keys
3. **Source Analysis**: Parse source files with Babel to find `t()` calls and text content
4. **Cross-Reference**: Compare used keys vs defined keys to find missing/unused
5. **Lint Processing**: Apply configurable rules with severity levels
6. **Output**: Format results for console or JSON output

## Framework Support

i18n-log supports translation patterns across all major frontend frameworks:

### React Ecosystem
- **Next.js intl**: `useTranslations('namespace')`, `useMessages()`, `useLocale()`
- **react-i18next**: `useTranslation()`, `useTranslation('namespace')`, `<Trans>`
- **react-intl/formatjs**: `useIntl()`, `intl.formatMessage({ id: 'key' })`
- **Lingui**: `useLingui()`, `_('key')`, `<Trans>`

### Vue Ecosystem
- **vue-i18n Composition API**: `useI18n()`, `t()`, `tc()`, `te()`, `d()`, `n()`
- **Vue Options API**: `this.$t()`, `this.$tc()`, `this.$te()`, `this.$d()`, `this.$n()`
- **Nuxt i18n**: `$t()`, `useI18n()`

### Angular Ecosystem
- **ngx-translate**: `TranslateService.get()`, `TranslateService.instant()`
- **Angular Localize**: `$localize\`key\``, `$localize\`:@@id:text\``

### Svelte Ecosystem
- **svelte-i18n**: `_('key')`, `$_('key')`, store-based translations
- **SvelteKit i18n**: `t('key')`

### Framework Agnostic
- **i18next**: `i18next.t()`, direct usage
- **Polyglot.js**: `polyglot.t('key', params)`
- **Generic patterns**: `t()`, `translate()`, `tr()`, `__()`

## Translation File Handling

The tool expects translation files to be JSON with nested objects:
```json
{
  "header": {
    "title": "My App",
    "nav": {
      "home": "Home"
    }
  }
}
```

Keys are flattened to dot notation (`header.title`, `header.nav.home`) for analysis.

## AST Parsing Strategy

Uses Babel parser to handle modern JS/TS syntax:
- Detects `t('key')` function calls (configurable function name)
- Identifies JSX text nodes and string literals as potential hardcoded text
- Extracts location information (file, line, column) for precise error reporting

## Linter Rules System

Rules are configurable with severity levels (error/warning/info):
- **missing-translation**: Keys used in code but not defined
- **unused-translation**: Keys defined but never used
- **hardcoded-text**: Text that should likely be translated
- **empty-translation**: Translation keys with empty values
- **duplicate-translation**: Same text across multiple keys
- **inconsistent-placeholders**: Mismatched interpolation variables
- **missing-plural-forms**: Keys that need plural handling

## Example App Testing

The `example/` folder contains a React app with i18next integration for testing:
- Multiple languages (EN/ES/FR)
- Various translation patterns (nested keys, interpolation)
- Intentional issues for testing linter rules

Always run `npm run build` in the root before testing the example app.

## Exit Codes and CI Integration

The linter returns proper exit codes for CI/CD:
- 0: Success (no errors)
- 1: Linting errors found or thresholds exceeded

Supports `--max-errors` and `--max-warnings` for threshold-based builds.