Initial upload of i18n-key-sync project

README.md

@@ -1,3 +1,146 @@
 # i18n-key-sync
 
-CLI tool for extracting, validating, and managing i18n translation keys
+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