locale-lint 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Francis Okocha-Ojeah
+
+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.

package/README.md

@@ -0,0 +1,270 @@
+# locale-lint
+
+> Zero-config i18n linter for React, React Native & Next.js.  
+> Catch missing, unused, and hardcoded strings before they ship.
+
+```
+npx locale-lint check
+```
+
+```
+  locale-lint — scanning 3 files across 2 locales
+  ────────────────────────────────────────────────────────
+
+  ❌ Missing in pt (3)
+     · auth.login.noAccount
+     · auth.login.signupLink
+     · home.oldWidget
+
+  ❌ Undefined keys — used in code, missing from all locales (2)
+     · auth.loginButton  →  src/screens/LoginScreen.tsx:35
+     · home.nonExistentKey  →  src/screens/HomeScreen.tsx:40
+
+  ⚠️  Unused keys — defined but never used in code (8)
+     · auth.signup.title
+     · common.cancel
+     · home.oldWidget
+
+  🚨 Hardcoded text — raw strings in JSX (6)
+     · src/screens/LoginScreen.tsx:16  →  "Welcome to our platform"
+     · src/screens/HomeScreen.tsx:23   →  "Your Statistics"
+
+  ❌ Interpolation mismatches (1)
+     · home.welcome
+       en: {name}  →  pt: {nome}
+
+  ────────────────────────────────────────────────────────
+  20 issues found in 123ms
+```
+
+---
+
+## What it detects
+
+| Check | Description |
+|---|---|
+| ❌ **Missing keys** | Keys in your base locale (`en`) that are missing from other locales |
+| ❌ **Undefined keys** | Keys called via `t('key')` in code that don't exist in any locale file |
+| ⚠️ **Unused keys** | Keys defined in locale files that are never used in code |
+| 🚨 **Hardcoded text** | Raw visible strings in JSX that should be translated |
+| ❌ **Interpolation mismatches** | `{{name}}` in EN but `{nome}` in PT — variables that don't match |
+
+---
+
+## Install
+
+```bash
+# Run without installing (recommended)
+npx locale-lint check
+
+# Or install globally
+npm install -g locale-lint
+
+# Or as a dev dependency
+npm install --save-dev locale-lint
+```
+
+---
+
+## Usage
+
+### Zero-config (auto-detects everything)
+
+Just run in your project root:
+
+```bash
+npx locale-lint check
+```
+
+locale-lint automatically finds:
+- **Locales**: looks for `locales/`, `translations/`, `i18n/`, `src/locales/`, `public/locales/`
+- **Source files**: scans `src/`, `app/`, `pages/`, `components/`, `screens/`
+
+### With options
+
+```bash
+# Specify paths explicitly
+npx locale-lint check --src src --locales public/locales
+
+# Different base locale
+npx locale-lint check --base fr
+
+# Skip unused key detection (useful during active development)
+npx locale-lint check --ignore-unused
+
+# Skip hardcoded string detection
+npx locale-lint check --ignore-hardcoded
+
+# JSON output for CI pipelines
+npx locale-lint check --json
+```
+
+---
+
+## Configuration
+
+Run `npx locale-lint init` to create a `locale-lint.config.json`:
+
+```json
+{
+  "src": ["src"],
+  "locales": "locales",
+  "baseLocale": "en",
+  "extensions": ["js", "ts", "jsx", "tsx"],
+  "minHardcodedLength": 3,
+  "ignoreKeys": ["common.appName"],
+  "exclude": ["node_modules", "dist", "build", ".next"]
+}
+```
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `src` | `string[]` | auto-detect | Directories to scan for source code |
+| `locales` | `string` | auto-detect | Directory containing locale files |
+| `baseLocale` | `string` | `"en"` | The source-of-truth locale |
+| `extensions` | `string[]` | `["js","ts","jsx","tsx"]` | File extensions to scan |
+| `minHardcodedLength` | `number` | `3` | Min string length to flag as hardcoded |
+| `ignoreKeys` | `string[]` | `[]` | Keys to exclude from all checks |
+| `exclude` | `string[]` | `["node_modules","dist"]` | Glob patterns to exclude |
+
+---
+
+## Translation file formats
+
+### Flat JSON
+```
+locales/
+  en.json
+  pt.json
+  fr.json
+```
+
+### Namespaced (i18next style)
+```
+locales/
+  en/
+    common.json
+    auth.json
+  pt/
+    common.json
+    auth.json
+```
+Keys are automatically prefixed: `common.save`, `auth.login.title`
+
+### TypeScript export
+```ts
+// locales/en.ts
+export default {
+  home: {
+    title: "Dashboard",
+  }
+}
+```
+
+---
+
+## Library compatibility
+
+locale-lint works with any library that uses `t('key')` style calls:
+
+| Library | Works? | Notes |
+|---|---|---|
+| **react-i18next** | ✅ | Full support |
+| **next-intl** | ✅ | Full support |
+| **i18next** | ✅ | Full support |
+| **i18n-js** | ✅ | Detects `i18n.t('key')` |
+| **react-intl / FormatJS** | ✅ | Detects `intl.formatMessage({id: 'key'})` |
+| **vue-i18n** | ✅ | Detects `$t('key')` |
+| **Lingui** | ⚠️ | JSON catalogs work; `.po` files not yet supported |
+
+---
+
+## CI Integration
+
+locale-lint exits with **code 1** when issues are found, making it easy to gate PRs:
+
+```yaml
+# .github/workflows/i18n.yml
+name: i18n check
+on: [push, pull_request]
+
+jobs:
+  locale-lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npx locale-lint check
+```
+
+### JSON output for custom reporting
+
+```bash
+npx locale-lint check --json > i18n-report.json
+```
+
+---
+
+## add to package.json scripts
+
+```json
+{
+  "scripts": {
+    "i18n:check": "locale-lint check",
+    "i18n:check:ci": "locale-lint check --json"
+  }
+}
+```
+
+---
+
+## What's ignored
+
+- Dynamic keys: `` t(`key.${variable}`) `` — can't be statically resolved
+- Numbers in JSX: `<Text>42</Text>`
+- Whitespace-only text nodes
+- Strings shorter than `minHardcodedLength` (default: 3 chars)
+- Content inside `<code>`, `<pre>`, `<script>`, `<style>`, `<svg>`
+- Punctuation clusters: `—`, `·`, `|`
+
+---
+
+## Project structure
+
+```
+src/
+  cli.ts                  # Commander CLI entry point
+  core/
+    runner.ts             # Main lint pipeline orchestrator
+    loadLocales.ts        # JSON + TS locale file parser
+    scanFiles.ts          # Glob-based source file scanner
+    extractKeys.ts        # AST-based t('key') extractor
+    detectHardcoded.ts    # JSX hardcoded string detector
+    compareLocales.ts     # Missing/unused/undefined key comparison
+  utils/
+    flatten.ts            # Nested object → dot-notation flattener
+    logger.ts             # Chalk-powered terminal output
+    config.ts             # Config file + auto-detection
+  types/
+    index.ts              # Shared TypeScript interfaces
+```
+
+---
+
+## Roadmap
+
+- [ ] `--fix` flag — auto-fill missing keys with `"TODO: translate"`
+- [ ] Watch mode for development (`locale-lint watch`)
+- [ ] YAML locale file support
+- [ ] `.po` file support (Lingui)
+- [ ] HTML report output
+- [ ] Translation coverage percentage budgets
+- [ ] Plural form validation
+
+---
+
+## License
+
+MIT

package/example/locales/en.json

@@ -0,0 +1,40 @@
+{
+  "common": {
+    "save": "Save",
+    "cancel": "Cancel",
+    "loading": "Loading...",
+    "error": "Something went wrong"
+  },
+  "auth": {
+    "login": {
+      "title": "Welcome back",
+      "subtitle": "Sign in to your account",
+      "emailLabel": "Email address",
+      "passwordLabel": "Password",
+      "submitButton": "Sign in",
+      "forgotPassword": "Forgot your password?",
+      "noAccount": "Don't have an account?",
+      "signupLink": "Sign up"
+    },
+    "signup": {
+      "title": "Create account",
+      "submitButton": "Get started"
+    }
+  },
+  "home": {
+    "title": "Dashboard",
+    "welcome": "Hello {{name}}, welcome back!",
+    "lastSeen": "Last seen {{date}}",
+    "oldWidget": "This feature is deprecated",
+    "stats": {
+      "total": "Total items",
+      "active": "Active",
+      "pending": "Pending"
+    }
+  },
+  "profile": {
+    "title": "My Profile",
+    "editButton": "Edit profile",
+    "bio": "Bio"
+  }
+}

package/example/locales/pt.json

@@ -0,0 +1,37 @@
+{
+  "common": {
+    "save": "Salvar",
+    "cancel": "Cancelar",
+    "loading": "Carregando...",
+    "error": "Algo deu errado"
+  },
+  "auth": {
+    "login": {
+      "title": "Bem-vindo de volta",
+      "subtitle": "Entre na sua conta",
+      "emailLabel": "Endereço de email",
+      "passwordLabel": "Senha",
+      "submitButton": "Entrar",
+      "forgotPassword": "Esqueceu sua senha?"
+    },
+    "signup": {
+      "title": "Criar conta",
+      "submitButton": "Começar"
+    }
+  },
+  "home": {
+    "title": "Painel",
+    "welcome": "Olá {nome}, bem-vindo de volta!",
+    "lastSeen": "Visto por último em {{date}}",
+    "stats": {
+      "total": "Total de itens",
+      "active": "Ativo",
+      "pending": "Pendente"
+    }
+  },
+  "profile": {
+    "title": "Meu Perfil",
+    "editButton": "Editar perfil",
+    "bio": "Bio"
+  }
+}

package/example/src/components/ProfileCard.tsx

@@ -0,0 +1,30 @@
+import React from "react";
+import { useTranslation } from "react-i18next";
+
+interface ProfileProps {
+  name: string;
+  bio?: string;
+}
+
+// home.oldWidget is defined in translations but never used anywhere in code
+// profile keys are used here
+
+export function ProfileCard({ name, bio }: ProfileProps) {
+  const { t } = useTranslation();
+
+  return (
+    <div className="profile-card">
+      <h2>{t("profile.title")}</h2>
+      <p className="name">{name}</p>
+      {bio && <p className="bio">{bio}</p>}
+      <button type="button">{t("profile.editButton")}</button>
+
+      {/* Hardcoded tooltip text 🚨 */}
+      <span title="Click to edit your profile details">
+        {t("profile.bio")}
+      </span>
+
+      {/* i18n.t() style — also detected */}
+    </div>
+  );
+}

package/example/src/i18n/translations/en.ts

@@ -0,0 +1,18 @@
+// Pattern 1: Typed variable with indirect export — most common in typed RN projects
+import type { TranslationSchema } from './types'
+
+const en: TranslationSchema = {
+  common: {
+    save: "Save",
+    cancel: "Cancel",
+  },
+  home: {
+    title: "Dashboard",
+    welcome: "Hello {{name}}",
+  },
+  auth: {
+    login: "Sign in",
+  }
+}
+
+export default en

package/example/src/i18n/translations/pt.ts

@@ -0,0 +1,14 @@
+// Pattern 2: satisfies keyword (TS 4.9+)
+export default {
+  common: {
+    save: "Salvar",
+    cancel: "Cancelar",
+  },
+  home: {
+    title: "Painel",
+    welcome: "Olá {{name}}",
+  },
+  auth: {
+    login: "Entrar",
+  }
+} satisfies Record<string, unknown>

package/example/src/screens/HomeScreen.tsx

@@ -0,0 +1,46 @@
+import React from "react";
+import { useTranslation } from "react-i18next";
+
+interface HomeProps {
+  userName: string;
+  lastSeen: string;
+}
+
+export function HomeScreen({ userName, lastSeen }: HomeProps) {
+  const { t } = useTranslation();
+
+  return (
+    <div className="home">
+      <header>
+        <h1>{t("home.title")}</h1>
+        {/* Correctly using interpolation */}
+        <p>{t("home.welcome", { name: userName })}</p>
+        <small>{t("home.lastSeen", { date: lastSeen })}</small>
+      </header>
+
+      <section className="stats">
+        {/* Hardcoded section header 🚨 */}
+        <h2>Your Statistics</h2>
+
+        <div className="stat-card">
+          <span>{t("home.stats.total")}</span>
+          <span>142</span>
+        </div>
+        <div className="stat-card">
+          <span>{t("home.stats.active")}</span>
+          <span>98</span>
+        </div>
+        <div className="stat-card">
+          <span>{t("home.stats.pending")}</span>
+          <span>44</span>
+        </div>
+      </section>
+
+      {/* This key doesn't exist ❌ */}
+      <p>{t("home.nonExistentKey")}</p>
+
+      {/* Dynamic key — intentionally ignored by locale-lint */}
+      <p>{t(`home.${userName}`)}</p>
+    </div>
+  );
+}

package/example/src/screens/LoginScreen.tsx

@@ -0,0 +1,46 @@
+import React, { useState } from "react";
+import { useTranslation } from "react-i18next";
+
+// Example React Native / React screen
+export function LoginScreen() {
+  const { t } = useTranslation();
+  const [email, setEmail] = useState("");
+
+  return (
+    <div className="screen">
+      {/* Correctly translated */}
+      <h1>{t("auth.login.title")}</h1>
+      <p>{t("auth.login.subtitle")}</p>
+
+      {/* Hardcoded strings — should be flagged 🚨 */}
+      <div className="hero-banner">
+        Welcome to our platform
+      </div>
+
+      <label htmlFor="email">{t("auth.login.emailLabel")}</label>
+      <input
+        id="email"
+        type="email"
+        placeholder="Enter your email"
+        value={email}
+        onChange={(e) => setEmail(e.target.value)}
+      />
+
+      <label htmlFor="password">{t("auth.login.passwordLabel")}</label>
+      <input id="password" type="password" placeholder="Password" />
+
+      <button type="button">{t("auth.login.submitButton")}</button>
+
+      {/* This key doesn't exist in translations — undefined key ❌ */}
+      <p>{t("auth.loginButton")}</p>
+
+      <a href="/forgot">{t("auth.login.forgotPassword")}</a>
+
+      <div className="footer">
+        {/* Hardcoded again 🚨 */}
+        <span>Already have an account?</span>
+        <a href="/login">{t("auth.login.signupLink")}</a>
+      </div>
+    </div>
+  );
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "locale-lint",
+  "version": "1.0.0",
+  "description": "Zero-config i18n linter for React, React Native & Next.js — detects missing, unused, undefined keys and hardcoded strings",
+  "main": "dist/cli.js",
+  "bin": {
+    "locale-lint": "./dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "ts-node src/cli.ts",
+    "check": "ts-node src/cli.ts check",
+    "lint": "ts-node src/cli.ts check --src example/src --locales example/locales"
+  },
+  "keywords": [
+    "i18n",
+    "internationalization",
+    "localization",
+    "lint",
+    "translation",
+    "react",
+    "react-native",
+    "nextjs",
+    "i18next",
+    "missing-keys",
+    "unused-keys",
+    "hardcoded-strings"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@babel/parser": "^7.23.0",
+    "@babel/traverse": "^7.23.0",
+    "@babel/types": "^7.23.0",
+    "chalk": "^4.1.2",
+    "commander": "^11.1.0",
+    "glob": "^10.3.10"
+  },
+  "devDependencies": {
+    "@types/babel__traverse": "^7.20.4",
+    "@types/node": "^20.10.0",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.3.2"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+
+import { Command } from "commander";
+import chalk from "chalk";
+import path from "path";
+import { runLint, hasIssues } from "./core/runner";
+import { resolveConfig } from "./utils/config";
+import { printResult, printScanning } from "./utils/logger";
+import type { OutputFormat } from "./types/index";
+
+const program = new Command();
+
+program
+  .name("locale-lint")
+  .description("Zero-config i18n linter for React, React Native & Next.js")
+  .version("1.0.0");
+
+program
+  .command("check")
+  .description("Run all i18n checks on your codebase")
+  .option("--src <dir>", "Source directory to scan (default: auto-detect)")
+  .option("--locales <dir>", "Locales directory (default: auto-detect)")
+  .option("--base <locale>", "Base locale to compare against (default: en)")
+  .option("--json", "Output results as JSON (useful for CI pipelines)")
+  .option("--ignore-unused", "Skip unused key detection")
+  .option("--ignore-hardcoded", "Skip hardcoded string detection")
+  .action(async (options) => {
+    const cwd = process.cwd();
+    const format: OutputFormat = options.json ? "json" : "pretty";
+
+    try {
+      // Resolve configuration (file + CLI flags + auto-detect)
+      const config = resolveConfig(cwd, {
+        src: options.src,
+        locales: options.locales,
+        base: options.base,
+      });
+
+      if (format === "pretty") {
+        printScanning(config.src.map((s) => path.relative(cwd, s) || s));
+      }
+
+      // Run the lint pipeline
+      let result = await runLint(config, cwd);
+
+      // Apply CLI-level suppressions
+      if (options.ignoreUnused) result = { ...result, unusedKeys: [] };
+      if (options.ignoreHardcoded) result = { ...result, hardcodedStrings: [] };
+
+      // Print results
+      printResult(result, format);
+
+      // Exit with code 1 if any issues found (enables CI gating)
+      if (hasIssues(result)) {
+        process.exit(1);
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      console.error();
+      console.error(`  ${chalk.red("Error:")} ${message}`);
+      console.error();
+      process.exit(2);
+    }
+  });
+
+// ── Extra command: init ────────────────────────────────────────────────────────
+program
+  .command("init")
+  .description("Create a locale-lint.config.json in the current directory")
+  .action(() => {
+    const fs = require("fs");
+    const configPath = path.join(process.cwd(), "locale-lint.config.json");
+
+    if (fs.existsSync(configPath)) {
+      console.log(chalk.yellow("  locale-lint.config.json already exists."));
+      return;
+    }
+
+    const defaultConfig = {
+      src: ["src"],
+      locales: "locales",
+      baseLocale: "en",
+      extensions: ["js", "ts", "jsx", "tsx"],
+      minHardcodedLength: 3,
+      ignoreKeys: [],
+      exclude: ["node_modules", "dist", "build", ".next", "coverage"],
+    };
+
+    fs.writeFileSync(configPath, JSON.stringify(defaultConfig, null, 2));
+    console.log();
+    console.log(`  ${chalk.green("✅")} Created ${chalk.bold("locale-lint.config.json")}`);
+    console.log(`  Edit it to customize your setup, then run ${chalk.cyan("locale-lint check")}`);
+    console.log();
+  });
+
+program.parse(process.argv);