i18n-guardian/README.md

i18n-guardian

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

pip install i18n-guardian

From Source

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

Verification

i18n-guardian --version

Quick Start

1. Initialize Configuration

i18n-guardian init

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

2. Scan for Hardcoded Strings

i18n-guardian scan

3. Preview Changes (Dry Run)

i18n-guardian fix --dry-run

4. Apply Fixes

i18n-guardian fix

Commands

scan

Scan the codebase for hardcoded strings that should be translated.

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.

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.

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).

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:

# 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

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

GitLab CI

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

Jenkins

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

Gitea Actions

- 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

# 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

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

Running Tests

# 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

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 file for details.

Changelog

See CHANGELOG.md for a list of changes.

Support

• Issues: Report bugs and feature requests on the issue tracker
• Documentation: See this README and the wiki