Find missing keys in i18n JSON translation files

Keep your translation files honest. Point this agent at a folder of per-language JSON catalogs (en.json, fr.json, es.json, …) and it tells you exactly what a release blocker looks like: missing keys, stale/orphan keys, and the placeholder drift ({name}, {count}, %s) that quietly breaks a UI in one language while every test still passes in another.

The audit and validation core is 100% deterministic — no LLM, no API key, no network. Connect a coding-agent CLI (Claude Code / Kimi Code / Codex) and the translate command additionally drafts the missing strings for you, with every placeholder verified before it's written. No LLM connected? You still get a full audit and safe TODO: stubs that keep placeholders intact.

Who it's for

Anyone shipping a product, app, or docs in more than one language and tired of "the French build shows {count} items literally" bug reports:

• Product/frontend teams maintaining i18next / vue-i18n / gettext-style JSON.
• Docs and marketing sites with parallel language folders.
• CI pipelines that should fail when a translation catalog goes out of sync.

What it is honest about

The LLM only ever writes to a side-car <locale>.draft.json for human review — it never overwrites your real translation files.

Quick start

# 1) install (Debian/Ubuntu VM) — deps + venv + optional systemd service
sudo bash install.sh          # or: bash install.sh --no-service

# 2) try it on the bundled sample catalog (en base, fr + es partial)
python agent.py audit
python agent.py validate ; echo "exit=$?"   # non-zero: catalog is out of sync

# 3) draft the strings missing from Spanish
python agent.py translate --locale es
cat catalog/es.draft.json                    # review, then merge into es.json

# 4) point it at your own catalog
python agent.py audit --dir /path/to/locales --base en

How it works (OODA drift monitor)

        ┌──────────────────────────────────────────────┐
        │  OBSERVE   load base + target JSON catalogs   │
        │  ORIENT    flatten keys, diff, check          │
        │            placeholders → coverage per lang   │
        │  DECIDE    OK | REPORT_DRIFT (worst language) │
        │  ACT       emit JSON event / exit code        │
        └──────────────────────────────────────────────┘
                    run once (CI) │ loop (systemd)

agent.py run runs this loop continuously (systemd unit provided by install.sh) so a catalog that drifts after a merge shows up in your logs without anyone remembering to check.

Commands

Reviewing a localization batch

agent.py review is a 100% deterministic gate for a batch of proposed translations (task_type: review_i18n_batch). It reads payload.items, compares the placeholder set of source_text against proposed_translation, and routes every item into one of three buckets — no LLM, no network, no invention:

python agent.py review --payload batch.json
# or: python agent.py review --input batch.json --output review.json

batch.json looks like:

{
  "items": [
    { "id": "I18N-001", "key": "cart.empty",
      "source_text": "Your cart is empty, {name}.",
      "proposed_translation": "Votre panier est vide, {name}." },
    { "id": "I18N-002", "key": "invoice.total",
      "source_text": "Total: %d items, %s",
      "proposed_translation": "Total: %d articles" },
    { "id": "I18N-003", "key": "errors.rate_limit",
      "source_text": "Too many requests.",
      "proposed_translation": null }
  ]
}

and the review output is:

{
  "mode": "deterministic",
  "valid_items": [
    { "id": "I18N-001", "key": "cart.empty", "decision": "valid",
      "placeholders": "{name}", "reason": "placeholder set matches source" }
  ],
  "blocked_items": [
    { "id": "I18N-002", "key": "invoice.total", "decision": "block",
      "placeholders": ["%d", "%s"], "reason": "placeholder drift; missing %s" }
  ],
  "manual_review": [
    { "id": "I18N-003", "key": "errors.rate_limit", "decision": "review",
      "placeholders": [], "reason": "missing explicit source_text or proposed_translation; manual source review required" }
  ]
}

Rules:

• valid_items — both fields present, placeholder sets equal.
• blocked_items — both fields present, placeholder sets differ.
• manual_review — source_text or proposed_translation missing.
• placeholders is a single string for one token, a sorted unique list otherwise.
• The reviewer never reads operator_note / not_provided and never invents missing content.

Configuration

All optional, via environment variables (see SPEC.md):

• I18N_CATALOG_DIR — catalog folder (default catalog).
• I18N_BASE_LOCALE — source-of-truth language (default en).
• I18N_COVERAGE_WARNING — coverage floor before "degraded" (default 0.90).
• PACK_LLM — pin a backend claude|kimi|codex (default: auto-detect).

See CUSTOMIZE.md to plug in your own catalog and PROMPTS.md to tune the translation prompt.

Use a local model (Ollama)

The optional LLM step can also run on your own machine through Ollama, so no text leaves your server. No account and no API key.

ollama pull <model>               # any chat model you like
export PACK_LLM=ollama            # prefer Ollama even if a coding-agent CLI is installed
export PACK_OLLAMA_MODEL=<model>  # optional: default is the first chat model the server lists
python3 -c "import llm_adapter; print(llm_adapter.detect())"   # prints: ollama

• PACK_OLLAMA_HOST points to another server (default http://127.0.0.1:11434); OLLAMA_HOST is also read when PACK_LLM=ollama.
• PACK_OLLAMA_NUM_CTX sets the context size if your reports or prompts are long.
• Without PACK_LLM, a local Ollama server is used only when no Claude Code, Kimi Code or Codex CLI is found.
• If the server is down or the model is missing, the pack keeps working in its deterministic mode.

Learning memory (local and private)

Every LLM call this pack makes is journaled in ./.pack_memory/ next to the code, so the pack can improve for you. Nothing is ever sent anywhere.

• What is kept: the task name, the masked input, the masked answer, status and latency. Keys, tokens, e-mails, phone numbers, IP addresses, card and IBAN numbers and personal paths are masked before writing; the system prompt is never stored.
• Teach it: python3 pack_memory.py feedback last ok confirms a result, python3 pack_memory.py feedback last bad --fix "the right answer" corrects it. Confirmed and corrected runs are reused as validated examples when a similar input comes in. Unrated runs are never injected into a prompt.
• Find similar cases: python3 pack_memory.py similar "some text" and python3 pack_memory.py clusters (groups of near-identical failures) work in plain Python, no model needed. Optional meaning-based matching uses an embedding model you already run locally: python3 pack_memory.py enable-semantic (Ollama on this machine only).
• Share, only if you want: python3 pack_memory.py export writes an anonymised summary (counts, statuses, size buckets, no text) for you to review.
• Control: PACK_MEMORY=0 turns it off, PACK_MEMORY_STORE_TEXT=0 keeps fingerprints only, python3 pack_memory.py purge --yes wipes it.