i18n-guardian/README.md

# i18n-guardian

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
[![Tests](https://img.shields.io/badge/tests-67%2F67%20passing-green.svg)]()

A powerful CLI tool that automatically scans codebases for internationalization (i18n) issues like hardcoded strings, missing translation keys, and inconsistent locale patterns. It intelligently auto-detects i18n libraries in use, suggests proper translation key names following project conventions, and can auto-fix common issues with diff-based review before applying changes.

## Features

- **Auto i18n Library Detection**: Automatically detects react-intl, i18next, vue-i18n, gettext, python-gettext, and Flask-Babel
- **Hardcoded String Detection**: Scans source code for strings that should be translated, excluding URLs, emails, regex patterns, and existing i18n calls
- **Smart Translation Key Generation**: Generates proper translation keys following project naming conventions (snake_case, kebab-case, camelCase, PascalCase)
- **Diff-based Preview**: Shows exactly what changes will be made before applying fixes
- **Auto-fix Capability**: Automatically replaces hardcoded strings with proper i18n function calls
- **Custom Rules**: Configure exclusions, thresholds, and naming patterns via YAML configuration
- **CI/CD Integration**: JSON output format and appropriate exit codes for CI/CD pipeline integration
- **Multi-language Support**: Supports JavaScript, TypeScript, Python (extensible architecture)

## Installation

### From PyPI

```bash
pip install i18n-guardian
```

### From Source

```bash
git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/i18n-guardian.git
cd i18n-guardian
pip install -e ".[dev]"
```

### Verification

```bash
i18n-guardian --version
```

## Quick Start

### 1. Initialize Configuration

```bash
i18n-guardian init
```

This creates a `.i18n-guardian.yaml` configuration file in your project root.

### 2. Scan for Hardcoded Strings

```bash
i18n-guardian scan
```

### 3. Preview Changes (Dry Run)

```bash
i18n-guardian fix --dry-run
```

### 4. Apply Fixes

```bash
i18n-guardian fix
```

## Commands

### scan

Scan the codebase for hardcoded strings that should be translated.

```bash
i18n-guardian scan [OPTIONS]
```

**Options:**

| Option | Description |
|--------|-------------|
| `--output, -o` | Output format: `text` or `json` |
| `--exclude` | Additional exclude patterns (glob) |
| `--min-length` | Minimum string length to flag (default: 3) |
| `--verbose, -v` | Enable verbose output |
| `--path, -p` | Path to scan (defaults to current directory) |

### fix

Auto-fix i18n issues by replacing hardcoded strings with i18n function calls.

```bash
i18n-guardian fix [OPTIONS]
```

**Options:**

| Option | Description |
|--------|-------------|
| `--dry-run` | Preview changes without applying |
| `--output, -o` | Output format: `text` or `json` |
| `--verbose, -v` | Enable verbose output |
| `--path, -p` | Path to scan (defaults to current directory) |

### init

Initialize a new configuration file.

```bash
i18n-guardian init [OPTIONS]
```

**Options:**

| Option | Description |
|--------|-------------|
| `--output, -o` | Output file path (default: `.i18n-guardian.yaml`) |

### check

Check i18n compliance (ideal for CI/CD pipelines).

```bash
i18n-guardian check [OPTIONS]
```

**Options:**

| Option | Description |
|--------|-------------|
| `--fail-level` | Minimum level to fail: `error`, `warning`, or `info` |
| `--output, -o` | Output format: `text` or `json` |
| `--verbose, -v` | Enable verbose output |
| `--path, -p` | Path to scan (defaults to current directory) |

## Configuration

Create a `.i18n-guardian.yaml` file in your project root:

```yaml
# i18n Library Configuration
i18n_library: react-intl  # Optional: auto-detected if not specified
i18n_functions:
  - formatMessage
  - t
  - $t

# Scanning Options
min_string_length: 3  # Minimum string length to flag
key_style: snake_case  # snake_case, kebab-case, camelCase, PascalCase
key_prefix: null  # Optional prefix for all generated keys

# File Patterns
include_patterns:
  - "**/*.py"
  - "**/*.js"
  - "**/*.ts"
  - "**/*.jsx"
  - "**/*.tsx"

exclude_patterns:
  - "**/node_modules/**"
  - "**/.git/**"
  - "**/venv/**"
  - "**/__pycache__/**"
  - "**/dist/**"
  - "**/build/**"

# Output Options
output_format: text  # text or json
fail_level: error  # error, warning, or info
```

### Configuration Precedence

1. `--config` CLI option (highest priority)
2. `.i18n-guardian.yaml` in scan directory
3. `i18n-guardian.yaml` in scan directory
4. `~/.i18n-guardian.yaml` (home directory)
5. Default values (lowest priority)

## Supported i18n Libraries

| Library | Detected By | Key Format |
|---------|-------------|------------|
| react-intl | package.json, webpack config, imports | Object keys |
| i18next | i18n config, imports | Nested keys |
| vue-i18n | Vue imports, plugins | Dot notation |
| gettext | .po/.pot files | Message IDs |
| python-gettext | gettext imports | Message IDs |
| Flask-Babel | Flask app imports | Message IDs |

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Success (no violations) |
| 1 | Error (invalid config, missing files, etc.) |
| 2 | Violations found (for `check` command) |

## CI/CD Integration

### GitHub Actions

```yaml
- name: Check i18n Compliance
  run: i18n-guardian check --output json --fail-level error
```

### GitLab CI

```yaml
i18n-check:
  image: python:3.12
  script:
    - pip install i18n-guardian
    - i18n-guardian check --output json --fail-level error
```

### Jenkins

```groovy
pipeline {
    agent any
    stages {
        stage('Check i18n') {
            steps {
                sh 'pip install i18n-guardian && i18n-guardian check --output json'
            }
        }
    }
}
```

### Gitea Actions

```yaml
- name: i18n Check
  run: i18n-guardian check --output json --fail-level error
```

## Key Generation

i18n-guardian generates translation keys based on:

1. **Text Content**: The string text is normalized and converted to the chosen key style
2. **File Path**: Keys include path-based prefixes (e.g., `components_button_submit`)
3. **Context**: Optional context information can be included
4. **Uniqueness**: Duplicate keys are automatically numbered

### Key Styles

```yaml
# snake_case (default)
welcome_message

# kebab-case
welcome-message

# camelCase
welcomeMessage

# PascalCase
WelcomeMessage
```

## Architecture

```
i18n_guardian/
├── cli.py           # Click CLI entry point
├── config/          # Configuration loading and management
│   └── __init__.py
├── detectors/       # i18n library detection
│   ├── base.py
│   ├── react_intl.py
│   ├── i18next.py
│   ├── vue_i18n.py
│   ├── gettext.py
│   └── python_gettext.py
├── scanners/        # String scanning
│   ├── string_scanner.py
│   └── __init__.py
├── keygen/          # Key generation
│   └── key_generator.py
├── parsers/         # Code parsing (tree-sitter)
├── diff/            # Diff generation for preview
├── utils/           # Utility functions
└── version.py
```

## Development

### Setup

```bash
git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/i18n-guardian.git
cd i18n-guardian
pip install -e ".[dev]"
```

### Running Tests

```bash
# Run all tests
pytest tests/ -v

# Run with coverage
pytest tests/ -v --cov=i18n_guardian --cov-report=term-missing

# Run specific test file
pytest tests/test_cli.py -v
```

### Linting

```bash
ruff check i18n_guardian/ tests/
```

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for a list of changes.

## Support

- **Issues**: Report bugs and feature requests on the [issue tracker](https://7000pct.gitea.bloupla.net/7000pctAUTO/i18n-guardian/issues)
- **Documentation**: See this README and the [wiki](https://7000pct.gitea.bloupla.net/7000pctAUTO/i18n-guardian/wiki)