Initial upload: i18n-guardian v1.0.0
This commit is contained in:
343
README.md
343
README.md
@@ -1,3 +1,344 @@
|
||||
# i18n-guardian
|
||||
|
||||
Automated i18n linter and fixer CLI tool
|
||||
[](https://opensource.org/licenses/MIT)
|
||||
[](https://www.python.org/downloads/)
|
||||
[]()
|
||||
|
||||
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)
|
||||
|
||||
Reference in New Issue
Block a user