What if your tooling could catch these problems automatically — across frameworks — locally and in CI, and even help you fix them inside VS Code?

Meet i18nGuard: an internationalization linter and validation tool for JavaScript/TypeScript projects that supports i18next, React‑Intl (FormatJS), and Lingui. It ships with a CLI, a VS Code extension, SARIF reporting for code scanning, pseudo‑localization, and translation coverage budgets.

• GitHub: deuwi/i18nGuard

• npm (CLI): @i18nguard/cli

TL;DR

• Detect hard‑coded strings, missing keys, and unused keys

• Works with i18next, React‑Intl (FormatJS), and Lingui

• CLI for local/CI, VS Code extension for one‑click fixes

• JSON/HTML/SARIF reports and coverage thresholds

Why another i18n tool?

Most teams rely on ad‑hoc linters or per‑framework scripts. i18nGuard aims to be:

• Framework‑aware: i18next, React‑Intl, Lingui — one tool, consistent results

• Dev‑friendly: instant feedback in VS Code with Quick Fixes

• CI‑ready: SARIF output, budgets, and fail‑on‑error for PR gates

• Practical: pseudo‑localization and actionable reports

Key features

• Smart detection of hard‑coded strings in UI

• Validation of missing and unused keys across locales

• Multi‑framework adapters: i18next, React‑Intl, Lingui

• VS Code integration (real‑time diagnostics + Quick Fix)

• CI/CD friendly: JSON/HTML/SARIF reports, fail‑on‑error

• Pseudo‑localization and translation coverage budgets

Quick demo

• Run a CLI scan and get a concise summary of i18n issues

• Open the HTML report or upload SARIF to GitHub code scanning

• In VS Code, use Quick Fix to externalize strings and write keys to catalogs

Tip: Include a short GIF showing i18nguard scan and a Quick Fix in VS Code.

Quick Start

Install the CLI globally or as a dev dependency:

# Global
npm install -g @i18nguard/cli

# Project
npm install --save-dev @i18nguard/cli

Create an i18nscan.config.ts at your project root:

import { defineConfig } from '@i18nguard/core';

export default defineConfig({
  library: 'i18next', // or 'formatjs' or 'lingui' or 'auto'
  src: ['src/**/*.{ts,tsx,js,jsx}'],
  locales: ['en', 'fr', 'es'],
  defaultLocale: 'en',
  catalogs: {
    i18next: {
      pathPattern: 'public/locales/{locale}/{ns}.json',
      namespaces: ['common', 'auth', 'dashboard']
    }
  },
  budgets: {
    coverage: {
      fr: 95,
      es: 80
    },
    maxNewHardCodedPerPR: 0
  },
  ignore: ['**/*.test.*', '**/node_modules/**'],
  keygen: {
    strategy: 'filePathSlug',
    maxLen: 60
  },
  report: {
    formats: ['json', 'html'],
    outputDir: 'reports/i18n'
  }
});

Run a scan:

# Basic scan
i18nguard scan

# JSON and HTML reports
i18nguard scan --format json --output results.json
i18nguard report --input results.json --format html --output report.html

Prefer using the latest dev build?

# Clone and build for latest features
git clone https://github.com/deuwi/i18nGuard.git
cd i18nGuard
pnpm install
pnpm build

# Run via pnpm filter without global install
pnpm --filter @i18nguard/cli exec i18nguard scan

VS Code extension highlights (v1.1.0)

• Real‑time diagnostics for hard‑coded strings, missing and unused keys

• Quick Fix to externalize strings and write keys to translation catalogs

• Framework‑aware generation (i18next, React‑Intl, Lingui)

• Multi‑locale defaults:

  • Writes source text to the default locale (e.g., en)

  • Writes TODO:Translate(source) to other locales (e.g., fr, es)

• Namespace‑aware (i18next), Windows‑friendly paths

• Precise highlighting of string literals (not whole calls)

• Progress feedback and clear status messages

Marketplace listing is coming; you can install the VSIX locally if you build from the repo.

CI/CD and SARIF

Catch i18n issues on every PR with GitHub Actions:

name: i18n Validation
on: [push, pull_request]

jobs:
  i18n:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npx i18nguard scan --format sarif --output i18n.sarif --fail-on-error
      - name: Upload SARIF (GitHub code scanning)
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: i18n.sarif

Budgets help you enforce translation quality:

• maxNewHardCodedPerPR: 0 to block new hard‑coded strings

• Per‑locale coverage thresholds to keep catalogs healthy

Configuration examples

Next.js:

export default defineConfig({
  library: 'i18next',
  src: ['pages/**/*.{ts,tsx}', 'components/**/*.{ts,tsx}'],
  catalogs: {
    i18next: {
      pathPattern: 'public/locales/{locale}/{ns}.json',
      namespaces: ['common', 'navigation']
    }
  }
});

Create React App:

export default defineConfig({
  library: 'i18next',
  src: ['src/**/*.{ts,tsx,js,jsx}'],
  catalogs: {
    i18next: {
      pathPattern: 'src/locales/{locale}.json', // No namespaces
      namespaces: ['translation']
    }
  }
});

FormatJS / React‑Intl:

export default defineConfig({
  library: 'formatjs',
  src: ['src/**/*.{ts,tsx,js,jsx}'],
  locales: ['en', 'fr', 'es'],
  defaultLocale: 'en',
  catalogs: {
    formatjs: {
      messagesGlobs: ['src/locales/{locale}.json']
    }
  }
});

Lingui:

export default defineConfig({
  library: 'lingui',
  src: ['src/**/*.{ts,tsx,js,jsx}'],
  locales: ['en', 'fr', 'es'],
  defaultLocale: 'en',
  catalogs: {
    lingui: {
      pathPattern: 'src/locales/{locale}/messages.po'
    }
  }
});

Roadmap

• VS Code: FormatJS and Lingui support in the extension

• GitHub Action: turnkey action with inputs and PR comments

• Advanced ICU validation and watch mode

• Pseudo‑localization enhancements in the CLI

Contributions are welcome — check the repo for open issues and ideas.

Get started

• Install the CLI: npm i -D @i18nguard/cli (or global)

• Add i18nscan.config.ts and run i18nguard scan

• Try the VS Code extension locally

• Wire it into CI with SARIF for code scanning

• GitHub: deuwi/i18nGuard

• npm (CLI): @i18nguard/cli

• Sponsor: GitHub Sponsors

If you found this useful, drop a ⭐ on GitHub and share feedback — it helps a lot!