Deuwi

Posted on Sep 22

Stop shipping hard‑coded strings: Meet i18nGuard — an i18n linter for JS/TS (i18next, React‑Intl, Lingui)

#javascript #react #typescript #i18n

Internationalization (i18n) issues are sneaky. A single hard‑coded string slips into a PR, a key is missing in one locale, another key stays unused for months — and users get a half‑translated UI.

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!

DEV Community