Initial upload: i18n-guardian v1.0.0
This commit is contained in:
343
README.md
343
README.md
@@ -1,3 +1,344 @@
|
|||||||
# i18n-guardian
|
# 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