147 lines
2.8 KiB
Markdown
147 lines
2.8 KiB
Markdown
# i18n-key-sync
|
|
|
|
A CLI tool that scans source code to extract, validate, and manage i18n translation keys. It detects missing keys, finds unused translations, syncs with JSON/YAML locale files, and provides diff reports between code and translation files.
|
|
|
|
## Overview
|
|
|
|
`i18n-key-sync` solves the common problem of translation keys getting out of sync with code during development. It provides:
|
|
|
|
- **Extract**: Scan source code to find all i18n keys in use
|
|
- **Validate**: Compare extracted keys against locale files to find missing/unused keys
|
|
- **Sync**: Automatically add missing keys to locale files
|
|
- **Report**: Generate detailed reports on translation key coverage
|
|
|
|
## Installation
|
|
|
|
### From Source
|
|
|
|
```bash
|
|
git clone https://github.com/yourusername/i18n-key-sync.git
|
|
cd i18n-key-sync
|
|
pip install -e .
|
|
```
|
|
|
|
### Using pip
|
|
|
|
```bash
|
|
pip install i18n-key-sync
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
### Extract i18n keys from your code
|
|
|
|
```bash
|
|
i18n-key-sync extract ./src --patterns _,t,i18n.t --file-types py,js,ts
|
|
```
|
|
|
|
### Validate keys against locale files
|
|
|
|
```bash
|
|
i18n-key-sync validate ./src --locale-dir ./locales
|
|
```
|
|
|
|
### Sync missing keys to locale files
|
|
|
|
```bash
|
|
i18n-key-sync sync ./src --locale-dir ./locales --dry-run # Preview first
|
|
i18n-key-sync sync ./src --locale-dir ./locales # Apply changes
|
|
```
|
|
|
|
### Generate a coverage report
|
|
|
|
```bash
|
|
i18n-key-sync report ./src --locale-dir ./locales --format markdown -o report.md
|
|
```
|
|
|
|
## Commands
|
|
|
|
### extract
|
|
|
|
Extract i18n keys from source files.
|
|
|
|
```bash
|
|
i18n-key-sync extract <paths> [OPTIONS]
|
|
```
|
|
|
|
### validate
|
|
|
|
Validate extracted keys against locale files.
|
|
|
|
```bash
|
|
i18n-key-sync validate <paths> [OPTIONS]
|
|
```
|
|
|
|
### sync
|
|
|
|
Sync missing i18n keys to locale files.
|
|
|
|
```bash
|
|
i18n-key-sync sync <paths> [OPTIONS]
|
|
```
|
|
|
|
### report
|
|
|
|
Generate i18n key coverage report.
|
|
|
|
```bash
|
|
i18n-key-sync report <paths> [OPTIONS]
|
|
```
|
|
|
|
## Exit Codes
|
|
|
|
| Code | Description |
|
|
|------|-------------|
|
|
| 0 | Success (all keys valid) |
|
|
| 1 | Missing keys found (with --fail-missing) |
|
|
| 2 | Unused keys found (with --fail-unused) |
|
|
| 3 | Both missing and unused keys (with --strict) |
|
|
| 1 | Error (file not found, invalid format, etc.) |
|
|
|
|
## CI/CD Integration
|
|
|
|
### Gitea Actions
|
|
|
|
```yaml
|
|
name: i18n Check
|
|
|
|
on:
|
|
push:
|
|
branches: [main]
|
|
pull_request:
|
|
branches: [main]
|
|
|
|
jobs:
|
|
i18n:
|
|
runs-on: ubuntu-latest
|
|
steps:
|
|
- uses: actions/checkout@v4
|
|
- uses: actions/setup-python@v5
|
|
with:
|
|
python-version: '3.11'
|
|
- run: pip install -e ".[dev]"
|
|
- run: pytest tests/ -v
|
|
- run: ruff check .
|
|
```
|
|
|
|
## Development
|
|
|
|
### Setup
|
|
|
|
```bash
|
|
git clone https://github.com/yourusername/i18n-key-sync.git
|
|
cd i18n-key-sync
|
|
pip install -e ".[dev]"
|
|
```
|
|
|
|
### Running Tests
|
|
|
|
```bash
|
|
pytest tests/ -v
|
|
pytest tests/ --cov=i18n_key_sync
|
|
```
|
|
|
|
## License
|
|
|
|
MIT License
|