lang-natural 0.1.0

Detect unnatural / broken translations in locale files with ZERO LLM. Placeholders, untranslated strings, wrong script, repeats and more. Optional AI layer for fix suggestions. Works in any Python backend.

lang-natural (Python)

Detect unnatural / broken translations in your locale files — with zero LLM. Catches dropped placeholders, untranslated strings, wrong script, repeated words, markup drift and length anomalies. Runs fully offline, no API key. An optional AI layer (--fix) suggests natural rewrites only when you ask.

For Python backends (Django, FastAPI, Flask) that keep user-facing strings in JSON.

Install

pip install lang-natural

Configure — lang-natural.config.json

{
  "localesDir": "./locales",
  "sourceLocale": "en",
  "targetLocales": ["ar", "es", "hi"],
  "failOn": "error"
}

Run

lang-natural                 # scan and print the report
lang-natural --json          # machine-readable output
lang-natural --fix           # LLM fix suggestions (needs GEMINI_API_KEY)

Exit code is 1 when blocking issues are found — so it fails CI.

Use in code

from lang_natural import detect

issues = detect("cart.itemCount", "ar",
                "You have {count} items", "لديك عناصر")
for i in issues:
    print(i.severity, i.message)

What the local (no-LLM) detector catches

• Empty translations
• Missing / extra placeholders ({count}, {{name}}, %s)
• Strings identical to the source (untranslated)
• Wrong script (Latin text in an Arabic/Hindi/… locale)
• Repeated words
• HTML/markup that differs from the source
• Length outliers vs. the locale's typical ratio

Subtle word-order naturalness and rewrite suggestions require the optional LLM layer (--fix).

MIT