lang-natural

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.

Works in any JavaScript/TypeScript project — a Next.js/React frontend or a Node backend.

Install

npm install -D lang-natural

Configure — lang-natural.config.js

export default {
  localesDir: "./messages",
  sourceLocale: "en",
  targetLocales: ["ar", "es", "hi"],
  failOn: "error",   // error | warning | info
};

Run

npx lang-natural            # scan and print the report
npx lang-natural --json     # machine-readable output
npx 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

import { detect } from "lang-natural";

const issues = detect({
  key: "cart.itemCount",
  locale: "ar",
  source: "You have {count} items",
  candidate: "لديك عناصر",
});
issues.forEach((i) => console.log(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).

CI (GitHub Actions)

- run: npx lang-natural           # no key needed for detection

MIT