lang-natural 0.1.0__tar.gz

lang_natural-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+dist/
+build/
+*.egg-info/
+.venv/

lang_natural-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 diwakarbhatt1983
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

lang_natural-0.1.0/PKG-INFO

@@ -0,0 +1,71 @@
+Metadata-Version: 2.4
+Name: lang-natural
+Version: 0.1.0
+Summary: 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.
+Project-URL: Homepage, https://github.com/diwakarbhatt1983/lang-natural
+Author: diwakarbhatt1983
+License: MIT
+License-File: LICENSE
+Keywords: detector,django,fastapi,i18n,internationalization,linter,localization,naturalness,translation
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Localization
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# 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
+```bash
+pip install lang-natural
+```
+
+## Configure — `lang-natural.config.json`
+```json
+{
+  "localesDir": "./locales",
+  "sourceLocale": "en",
+  "targetLocales": ["ar", "es", "hi"],
+  "failOn": "error"
+}
+```
+
+## Run
+```bash
+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
+```python
+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

lang_natural-0.1.0/README.md

@@ -0,0 +1,55 @@
+# 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
+```bash
+pip install lang-natural
+```
+
+## Configure — `lang-natural.config.json`
+```json
+{
+  "localesDir": "./locales",
+  "sourceLocale": "en",
+  "targetLocales": ["ar", "es", "hi"],
+  "failOn": "error"
+}
+```
+
+## Run
+```bash
+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
+```python
+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

lang_natural-0.1.0/lang-natural.config.json

@@ -0,0 +1,6 @@
+{
+  "localesDir": "../../examples/messages",
+  "sourceLocale": "en",
+  "targetLocales": ["ar", "es"],
+  "failOn": "error"
+}

lang_natural-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "lang-natural"
+version = "0.1.0"
+description = "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."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "diwakarbhatt1983" }]
+keywords = ["i18n", "internationalization", "translation", "localization", "linter", "naturalness", "detector", "django", "fastapi"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Topic :: Software Development :: Localization",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/diwakarbhatt1983/lang-natural"
+
+[project.scripts]
+lang-natural = "lang_natural.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/lang_natural"]

lang_natural-0.1.0/src/lang_natural/__init__.py

@@ -0,0 +1,19 @@
+"""lang-natural — local (no-LLM) translation naturalness/quality detector."""
+from .detector import detect, Issue
+from .placeholders import check_placeholders, extract_placeholders
+from .script import expected_script, script_ratio, is_non_latin_locale
+from .files import load_locale, pair_locale, flatten
+from .config import Config, load_config_file, find_config, resolve_config
+from .report import run, render_report, RunSummary, Finding
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "detect", "Issue",
+    "check_placeholders", "extract_placeholders",
+    "expected_script", "script_ratio", "is_non_latin_locale",
+    "load_locale", "pair_locale", "flatten",
+    "Config", "load_config_file", "find_config", "resolve_config",
+    "run", "render_report", "RunSummary", "Finding",
+    "__version__",
+]

lang_natural-0.1.0/src/lang_natural/__main__.py

@@ -0,0 +1,6 @@
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

lang_natural-0.1.0/src/lang_natural/cli.py

@@ -0,0 +1,84 @@
+"""Command-line entry point: `lang-natural`."""
+import argparse
+import json
+import sys
+
+from .config import find_config, load_config_file, resolve_config
+from .report import run, render_report
+
+
+def _summary_to_dict(summary) -> dict:
+    return {
+        "ok": summary.ok,
+        "stats": summary.stats,
+        "reports": [
+            {
+                "locale": r.locale,
+                "file": r.file,
+                "missingKeys": r.missing_keys,
+                "extraKeys": r.extra_keys,
+                "findings": [
+                    {
+                        "key": f.key,
+                        "source": f.source,
+                        "candidate": f.candidate,
+                        "issues": [
+                            {"rule": i.rule, "severity": i.severity, "message": i.message}
+                            for i in f.issues
+                        ],
+                        "suggestion": f.suggestion,
+                    }
+                    for f in r.findings
+                ],
+            }
+            for r in summary.reports
+        ],
+    }
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="lang-natural",
+        description="Detect unnatural / broken translations locally (no LLM required).",
+    )
+    parser.add_argument("-c", "--config", help="Path to config JSON (default: auto-detect)")
+    parser.add_argument("--json", action="store_true", help="Machine-readable JSON output")
+    parser.add_argument("--fix", action="store_true", help="LLM fix suggestions (needs GEMINI_API_KEY)")
+    parser.add_argument("-v", "--version", action="store_true", help="Show version")
+    args = parser.parse_args(argv)
+
+    if args.version:
+        from . import __version__
+        print(__version__)
+        return 0
+
+    try:
+        if args.config:
+            config = load_config_file(args.config)
+        else:
+            path = find_config()
+            if not path:
+                sys.stderr.write("No lang-natural.config.json found in this directory.\n")
+                return 2
+            config = load_config_file(path)
+    except Exception as err:  # noqa: BLE001
+        sys.stderr.write(f"Config error: {err}\n")
+        return 2
+
+    try:
+        summary = run(config)
+        if args.fix:
+            from .llm import suggest_fixes
+            suggest_fixes(summary)
+        if args.json:
+            print(json.dumps(_summary_to_dict(summary), ensure_ascii=False, indent=2))
+        else:
+            print(render_report(summary))
+        return 0 if summary.ok else 1
+    except Exception as err:  # noqa: BLE001
+        sys.stderr.write(f"\nError: {err}\n")
+        return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

lang_natural-0.1.0/src/lang_natural/config.py

@@ -0,0 +1,50 @@
+"""Config loading. Uses a JSON config so it stays language-agnostic."""
+import json
+import os
+from dataclasses import dataclass, field
+
+_NAMES = ["lang-natural.config.json", "langnatural.config.json"]
+
+
+@dataclass
+class Config:
+    locales_dir: str
+    source_locale: str
+    target_locales: list[str]
+    disable_rules: list[str] = field(default_factory=list)
+    fail_on: str = "error"
+
+
+def find_config(cwd: str | None = None) -> str | None:
+    cwd = cwd or os.getcwd()
+    for n in _NAMES:
+        p = os.path.join(cwd, n)
+        if os.path.exists(p):
+            return p
+    return None
+
+
+def load_config_file(path: str) -> Config:
+    with open(path, encoding="utf-8") as fh:
+        raw = json.load(fh)
+    return resolve_config(raw)
+
+
+def resolve_config(raw: dict) -> Config:
+    # Accept both camelCase (shared with the JS config) and snake_case.
+    locales_dir = raw.get("localesDir") or raw.get("locales_dir")
+    source = raw.get("sourceLocale") or raw.get("source_locale")
+    targets = raw.get("targetLocales") or raw.get("target_locales")
+    if not locales_dir:
+        raise ValueError("config.localesDir is required.")
+    if not source:
+        raise ValueError("config.sourceLocale is required.")
+    if not targets:
+        raise ValueError("config.targetLocales must be a non-empty list.")
+    return Config(
+        locales_dir=locales_dir,
+        source_locale=source,
+        target_locales=list(targets),
+        disable_rules=list(raw.get("disableRules") or raw.get("disable_rules") or []),
+        fail_on=raw.get("failOn") or raw.get("fail_on") or "error",
+    )

lang_natural-0.1.0/src/lang_natural/detector.py

@@ -0,0 +1,88 @@
+"""The LOCAL detector — zero LLM, zero network, deterministic.
+
+Identical checks to the npm version so both packages behave the same.
+"""
+import re
+from dataclasses import dataclass
+
+from .placeholders import check_placeholders
+from .script import expected_script, script_ratio, is_non_latin_locale
+
+_HTML_TAG = re.compile(r"</?[a-zA-Z][^>]*>")
+
+
+@dataclass
+class Issue:
+    rule: str
+    severity: str  # "error" | "warning" | "info"
+    message: str
+
+
+def detect(
+    key: str,
+    locale: str,
+    source: str,
+    candidate: str,
+    median_len_ratio: float = 0.0,
+    disabled: set[str] | None = None,
+) -> list[Issue]:
+    disabled = disabled or set()
+    issues: list[Issue] = []
+
+    def add(rule: str, severity: str, message: str) -> None:
+        if rule not in disabled:
+            issues.append(Issue(rule, severity, message))
+
+    trimmed = candidate.strip()
+
+    # 1. Empty translation.
+    if trimmed == "":
+        add("empty", "error", "Translation is empty")
+        return issues
+
+    # 2. Placeholders must survive.
+    ph = check_placeholders(source, candidate)
+    if ph["missing"]:
+        add("placeholder", "error",
+            f"Missing placeholder(s): {', '.join(ph['missing'])} — this can crash the UI")
+    if ph["extra"]:
+        add("placeholder", "warning", f"Unexpected placeholder(s): {', '.join(ph['extra'])}")
+
+    # 3. Identical to source → likely untranslated.
+    if trimmed == source.strip() and any(c.isalpha() for c in source):
+        add("untranslated", "warning", "Identical to the source string (untranslated?)")
+
+    # 4. Wrong script for non-Latin locales.
+    if is_non_latin_locale(locale):
+        ratio = script_ratio(candidate, expected_script(locale))
+        if ratio < 0.4:
+            add("wrong-script", "error",
+                f"Mostly non-{expected_script(locale)} characters — looks untranslated or wrong script")
+
+    # 5. Repeated word (works for any script).
+    words = [w for w in re.split(r"\s+", candidate) if w]
+    for i in range(1, len(words)):
+        w = words[i]
+        if len(w) >= 2 and w == words[i - 1] and any(c.isalpha() for c in w):
+            add("repeated-word", "warning", f'Repeated word: "{w}"')
+            break
+
+    # 6. HTML/markup tags must match.
+    src_tags = sorted(_HTML_TAG.findall(source))
+    cand_tags = sorted(_HTML_TAG.findall(candidate))
+    if src_tags != cand_tags:
+        add("markup", "error", "HTML tags differ from the source string")
+
+    # 7. Length outlier vs the locale's typical translation length.
+    if median_len_ratio and len(source.strip()) >= 8:
+        ratio = len(candidate.strip()) / max(1, len(source.strip()))
+        m = median_len_ratio
+        if m > 0 and (ratio > m * 3 or ratio < m / 3):
+            add("length-outlier", "info",
+                f"Unusual length vs source ({ratio:.2f}x, locale typical ~{m:.2f}x) — possible mistranslation")
+
+    # 8. Doubled / stray whitespace.
+    if re.search(r"\s{2,}", candidate) or candidate != candidate.strip():
+        add("whitespace", "info", "Extra or trailing whitespace")
+
+    return issues

lang_natural-0.1.0/src/lang_natural/files.py

@@ -0,0 +1,79 @@
+"""Locale file loading, flattening and pairing."""
+import json
+import os
+from dataclasses import dataclass, field
+from statistics import median
+
+
+@dataclass
+class LoadedLocale:
+    locale: str
+    file: str
+    strings: dict[str, str]
+
+
+def flatten(obj, prefix: str = "", out: dict[str, str] | None = None) -> dict[str, str]:
+    if out is None:
+        out = {}
+    if not isinstance(obj, dict):
+        return out
+    for k, v in obj.items():
+        key = f"{prefix}.{k}" if prefix else k
+        if isinstance(v, str):
+            out[key] = v
+        elif isinstance(v, dict):
+            flatten(v, key, out)
+    return out
+
+
+def locale_file_path(locales_dir: str, locale: str) -> str:
+    d = os.path.abspath(locales_dir)
+    candidates = [
+        os.path.join(d, f"{locale}.json"),
+        os.path.join(d, locale, "index.json"),
+        os.path.join(d, locale, f"{locale}.json"),
+    ]
+    for c in candidates:
+        if os.path.exists(c):
+            return c
+    return candidates[0]
+
+
+def load_locale(locales_dir: str, locale: str) -> LoadedLocale:
+    path = locale_file_path(locales_dir, locale)
+    if not os.path.exists(path):
+        raise FileNotFoundError(f'Locale file not found for "{locale}": {path}')
+    with open(path, encoding="utf-8") as fh:
+        parsed = json.load(fh)
+    return LoadedLocale(locale=locale, file=path, strings=flatten(parsed))
+
+
+@dataclass
+class PairingResult:
+    pairs: list[dict] = field(default_factory=list)
+    missing_keys: list[str] = field(default_factory=list)
+    extra_keys: list[str] = field(default_factory=list)
+    median_len_ratio: float = 0.0
+
+
+def pair_locale(source: LoadedLocale, target: LoadedLocale) -> PairingResult:
+    pairs: list[dict] = []
+    missing: list[str] = []
+    ratios: list[float] = []
+
+    for key, src in source.strings.items():
+        candidate = target.strings.get(key)
+        if candidate is None:
+            missing.append(key)
+            continue
+        pairs.append({"key": key, "source": src, "candidate": candidate})
+        if len(src.strip()) >= 8 and len(candidate.strip()) > 0:
+            ratios.append(len(candidate.strip()) / len(src.strip()))
+
+    extra = [k for k in target.strings if k not in source.strings]
+    return PairingResult(
+        pairs=pairs,
+        missing_keys=missing,
+        extra_keys=extra,
+        median_len_ratio=median(ratios) if ratios else 0.0,
+    )

lang_natural-0.1.0/src/lang_natural/llm.py

@@ -0,0 +1,69 @@
+"""OPTIONAL LLM layer for --fix. Uses stdlib urllib (no extra deps).
+
+The detector never needs this; it only runs on --fix with GEMINI_API_KEY set.
+"""
+import json
+import os
+import urllib.request
+
+
+def suggest_fixes(summary) -> None:
+    key = os.environ.get("GEMINI_API_KEY")
+    if not key:
+        raise RuntimeError("--fix needs an LLM key. Set GEMINI_API_KEY in your environment.")
+
+    findings = [f for r in summary.reports for f in r.findings]
+    if not findings:
+        return
+
+    model = os.environ.get("LANG_NATURAL_MODEL", "gemini-2.5-flash")
+    url = f"https://generativelanguage.googleapis.com/v1beta/models/{model}:generateContent"
+
+    items = [
+        {
+            "i": i,
+            "locale": f.locale,
+            "source": f.source,
+            "current": f.candidate,
+            "problems": [x.message for x in f.issues],
+        }
+        for i, f in enumerate(findings)
+    ]
+    prompt = (
+        "You are a native-speaker localization editor. For each item, rewrite the "
+        '"current" translation so it reads naturally to a native speaker of the given '
+        "locale, keeping the meaning of the source and preserving every placeholder "
+        '(like {name}, {count}). Return STRICT JSON: '
+        '{"fixes":[{"i":number,"suggestion":string}]}.\n\n'
+        + json.dumps(items, ensure_ascii=False, indent=2)
+    )
+    body = json.dumps({
+        "contents": [{"role": "user", "parts": [{"text": prompt}]}],
+        "generationConfig": {"temperature": 0, "responseMimeType": "application/json"},
+    }).encode("utf-8")
+
+    req = urllib.request.Request(
+        url, data=body,
+        headers={"content-type": "application/json", "x-goog-api-key": key},
+        method="POST",
+    )
+    with urllib.request.urlopen(req) as resp:  # noqa: S310
+        data = json.loads(resp.read().decode("utf-8"))
+
+    text = "".join(
+        p.get("text", "") for p in data.get("candidates", [{}])[0]
+        .get("content", {}).get("parts", [])
+    )
+    try:
+        parsed = json.loads(text)
+    except json.JSONDecodeError:
+        start, end = text.find("{"), text.rfind("}")
+        parsed = json.loads(text[start:end + 1]) if start != -1 else {"fixes": []}
+
+    by_index = {
+        fix["i"]: fix["suggestion"]
+        for fix in parsed.get("fixes", [])
+        if isinstance(fix.get("i"), int) and isinstance(fix.get("suggestion"), str)
+    }
+    for i, f in enumerate(findings):
+        f.suggestion = by_index.get(i)

lang_natural-0.1.0/src/lang_natural/placeholders.py

@@ -0,0 +1,32 @@
+"""Placeholder verification — deterministic, no LLM."""
+import re
+from collections import Counter
+
+_PATTERNS = [
+    re.compile(r"\{\{\s*[\w.$-]+\s*\}\}"),  # {{name}}
+    re.compile(r"\{\s*[\w.$-]+\s*\}"),        # {name}
+    re.compile(r"%\d*\$?[sdifege@%]"),        # %s %1$s
+    re.compile(r":[a-zA-Z_]\w*"),              # :name
+]
+
+
+def extract_placeholders(text: str) -> list[str]:
+    found: list[str] = []
+    for pat in _PATTERNS:
+        for m in pat.findall(text):
+            found.append(re.sub(r"\s+", "", m))
+    return found
+
+
+def check_placeholders(source: str, candidate: str) -> dict:
+    src = Counter(extract_placeholders(source))
+    cand = Counter(extract_placeholders(candidate))
+    missing: list[str] = []
+    extra: list[str] = []
+    for tok, n in src.items():
+        for _ in range(n - cand.get(tok, 0)):
+            missing.append(tok)
+    for tok, n in cand.items():
+        for _ in range(n - src.get(tok, 0)):
+            extra.append(tok)
+    return {"missing": missing, "extra": extra, "ok": not missing and not extra}

lang_natural-0.1.0/src/lang_natural/report.py

@@ -0,0 +1,152 @@
+"""Run the local detector and render the terminal report."""
+import os
+import sys
+from dataclasses import dataclass, field
+
+from .config import Config
+from .detector import detect, Issue
+from .files import load_locale, pair_locale
+
+_RANK = {"info": 1, "warning": 2, "error": 3}
+_USE_COLOR = sys.stdout.isatty() and not os.environ.get("NO_COLOR") and os.environ.get("TERM") != "dumb"
+
+
+def _c(code):
+    def fn(s):
+        return f"\x1b[{code}m{s}\x1b[0m" if _USE_COLOR else str(s)
+    return fn
+
+
+BOLD, DIM, RED, GREEN, YELLOW, BLUE, CYAN, GRAY = (
+    _c(1), _c(2), _c(31), _c(32), _c(33), _c(34), _c(36), _c(90)
+)
+_SEV_COLOR = {"error": RED, "warning": YELLOW, "info": BLUE}
+_SEV_LABEL = {"error": "error", "warning": "warn ", "info": "info "}
+
+
+@dataclass
+class Finding:
+    key: str
+    locale: str
+    file: str
+    source: str
+    candidate: str
+    issues: list[Issue]
+    suggestion: str | None = None
+
+
+@dataclass
+class LocaleReport:
+    locale: str
+    file: str
+    findings: list[Finding] = field(default_factory=list)
+    missing_keys: list[str] = field(default_factory=list)
+    extra_keys: list[str] = field(default_factory=list)
+    checked: int = 0
+
+
+@dataclass
+class RunSummary:
+    reports: list[LocaleReport]
+    ok: bool
+    stats: dict
+
+
+def run(config: Config) -> RunSummary:
+    disabled = set(config.disable_rules)
+    source = load_locale(config.locales_dir, config.source_locale)
+    reports: list[LocaleReport] = []
+
+    for locale in config.target_locales:
+        target = load_locale(config.locales_dir, locale)
+        pr = pair_locale(source, target)
+        findings: list[Finding] = []
+        for p in pr.pairs:
+            issues = detect(
+                p["key"], locale, p["source"], p["candidate"],
+                median_len_ratio=pr.median_len_ratio, disabled=disabled,
+            )
+            if issues:
+                findings.append(Finding(
+                    key=p["key"], locale=locale, file=target.file,
+                    source=p["source"], candidate=p["candidate"], issues=issues,
+                ))
+        reports.append(LocaleReport(
+            locale=locale, file=target.file, findings=findings,
+            missing_keys=pr.missing_keys, extra_keys=pr.extra_keys, checked=len(pr.pairs),
+        ))
+
+    all_findings = [f for r in reports for f in r.findings]
+    errors = sum(1 for f in all_findings if any(i.severity == "error" for i in f.issues))
+    warnings = sum(
+        1 for f in all_findings
+        if not any(i.severity == "error" for i in f.issues)
+        and any(i.severity == "warning" for i in f.issues)
+    )
+    fail_rank = _RANK[config.fail_on]
+    ok = not any(_RANK[i.severity] >= fail_rank for f in all_findings for i in f.issues)
+
+    return RunSummary(
+        reports=reports,
+        ok=ok,
+        stats={
+            "checked": sum(r.checked for r in reports),
+            "flagged": len(all_findings),
+            "errors": errors,
+            "warnings": warnings,
+        },
+    )
+
+
+def _rel(path: str) -> str:
+    try:
+        return os.path.relpath(path)
+    except ValueError:
+        return path
+
+
+def render_report(summary: RunSummary) -> str:
+    lines = ["", BOLD("  lang-natural  ") + DIM("— local translation check (no LLM)"), ""]
+    for r in summary.reports:
+        _render_locale(r, lines)
+
+    s = summary.stats
+    lines.append("  " + DIM("─" * 50))
+    parts = [
+        BOLD(str(s["checked"])) + " checked",
+        RED(f"{s['errors']} errors") if s["errors"] else DIM("0 errors"),
+        YELLOW(f"{s['warnings']} warnings") if s["warnings"] else DIM("0 warnings"),
+    ]
+    lines.append("  " + DIM("  ·  ").join(parts))
+    lines.append("  " + (GREEN(BOLD("✓ no blocking issues")) if summary.ok
+                         else RED(BOLD("✗ issues found — see above"))))
+    lines.append("")
+    return "\n".join(lines)
+
+
+def _render_locale(r: LocaleReport, lines: list[str]) -> None:
+    rel = _rel(r.file)
+    status = (GREEN(f"✓ {r.checked} clean") if not r.findings
+              else RED(f"✗ {len(r.findings)}/{r.checked} flagged"))
+    lines.append("  " + BOLD(CYAN(r.locale.upper())) + "  " + DIM(rel) + "  " + status)
+    if r.missing_keys:
+        lines.append("    " + YELLOW("missing keys: ") + DIM(_preview(r.missing_keys)))
+
+    for f in r.findings:
+        worst = "info"
+        for i in f.issues:
+            if _RANK[i.severity] > _RANK[worst]:
+                worst = i.severity
+        lines.append("")
+        lines.append(f"    {_SEV_COLOR[worst]('[' + _SEV_LABEL[worst] + ']')} {BOLD(f.key)} {DIM('— ' + rel)}")
+        lines.append(f"      {GRAY('source:  ')}{f.source}")
+        lines.append(f"      {GRAY('current: ')}{DIM('(empty)') if f.candidate == '' else f.candidate}")
+        for i in f.issues:
+            lines.append(f"      {_SEV_COLOR[i.severity]('• ' + i.message)}")
+        if f.suggestion:
+            lines.append(f"      {GRAY('fix:     ')}{GREEN(f.suggestion)}")
+    lines.append("")
+
+
+def _preview(keys: list[str], n: int = 8) -> str:
+    return ", ".join(keys) if len(keys) <= n else ", ".join(keys[:n]) + f", +{len(keys) - n} more"

lang_natural-0.1.0/src/lang_natural/script.py

@@ -0,0 +1,48 @@
+"""Script / writing-system detection — no LLM.
+
+Mirrors the JS version: if a non-Latin locale's translation is mostly Latin
+letters, it's almost certainly untranslated or wrong.
+"""
+
+_LOCALE_SCRIPT = {
+    "ar": "arabic", "fa": "arabic", "ur": "arabic",
+    "hi": "devanagari", "mr": "devanagari", "ne": "devanagari",
+    "ru": "cyrillic", "uk": "cyrillic", "bg": "cyrillic", "sr": "cyrillic",
+    "zh": "han", "ja": "han", "ko": "hangul",
+    "th": "thai", "he": "hebrew", "el": "greek",
+}
+
+# Inclusive codepoint ranges per script.
+_RANGES = {
+    "latin": [(0x0041, 0x005A), (0x0061, 0x007A), (0x00C0, 0x024F)],
+    "arabic": [(0x0600, 0x06FF), (0x0750, 0x077F), (0x08A0, 0x08FF), (0xFB50, 0xFDFF), (0xFE70, 0xFEFF)],
+    "devanagari": [(0x0900, 0x097F)],
+    "cyrillic": [(0x0400, 0x04FF)],
+    "han": [(0x4E00, 0x9FFF), (0x3400, 0x4DBF), (0x3040, 0x30FF)],
+    "hangul": [(0xAC00, 0xD7AF), (0x1100, 0x11FF)],
+    "thai": [(0x0E00, 0x0E7F)],
+    "hebrew": [(0x0590, 0x05FF)],
+    "greek": [(0x0370, 0x03FF)],
+}
+
+
+def expected_script(locale: str) -> str:
+    base = locale.replace("_", "-").split("-")[0].lower()
+    return _LOCALE_SCRIPT.get(base, "latin")
+
+
+def _in_script(ch: str, script: str) -> bool:
+    cp = ord(ch)
+    return any(lo <= cp <= hi for lo, hi in _RANGES[script])
+
+
+def script_ratio(text: str, script: str) -> float:
+    letters = [c for c in text if c.isalpha()]
+    if not letters:
+        return 1.0
+    in_script = sum(1 for c in letters if _in_script(c, script))
+    return in_script / len(letters)
+
+
+def is_non_latin_locale(locale: str) -> bool:
+    return expected_script(locale) != "latin"