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

git clone https://github.com/yourusername/i18n-key-sync.git
cd i18n-key-sync
pip install -e .

Using pip

pip install i18n-key-sync

Quick Start

Extract i18n keys from your code

i18n-key-sync extract ./src --patterns _,t,i18n.t --file-types py,js,ts

Validate keys against locale files

i18n-key-sync validate ./src --locale-dir ./locales

Sync missing keys to locale files

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

i18n-key-sync report ./src --locale-dir ./locales --format markdown -o report.md

Commands

extract

Extract i18n keys from source files.

i18n-key-sync extract <paths> [OPTIONS]

validate

Validate extracted keys against locale files.

i18n-key-sync validate <paths> [OPTIONS]

sync

Sync missing i18n keys to locale files.

i18n-key-sync sync <paths> [OPTIONS]

report

Generate i18n key coverage report.

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

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

git clone https://github.com/yourusername/i18n-key-sync.git
cd i18n-key-sync
pip install -e ".[dev]"

Running Tests

pytest tests/ -v
pytest tests/ --cov=i18n_key_sync

License

MIT License