# 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