local-guard

A command-line tool for React Native projects that scans your source files and locale JSON files to find translation issues before they reach production.

What does it do?

local-guard catches two types of problems:

1. Missing translations - Keys used in code but missing from your locale files
2. Hardcoded text - Visible user-facing text that bypasses localization

Installation

Option 1: Run directly with npx (recommended for testing)

npx local-guard scan

Option 2: Install as a local dependency

npm install --save-dev local-guard

Then add a script to your package.json:

{
  "scripts": {
    "i18n:scan": "local-guard scan",
    "i18n:compare": "local-guard compare-locales"
  }
}

Run it with:

npm run i18n:scan

Option 3: Install globally

npm install -g local-guard
local-guard scan

Quick Start

1. Create a config file local-guard.config.json in your project root:

{
  "src": ["src/**/*.{js,jsx,ts,tsx}"],
  "ignore": [
    "**/*.test.*",
    "**/*.spec.*",
    "**/*.stories.*"
  ],
  "locales": {
    "baseLocale": "en",
    "files": {
      "en": "src/locales/en.json",
      "ar": "src/locales/ar.json",
      "ku": "src/locales/ku.json"
    }
  },
  "translationFunctions": ["i18n.t", "I18n.t", "t", "translate"],
  "visibleProps": ["title", "placeholder", "label", "message"],
  "literalWhitelist": ["HP", "XP", "OK"],
  "minLiteralLength": 2,
  "failOn": ["missing-key", "missing-locale", "hardcoded-text"]
}

2. Run the scanner:

local-guard scan

Configuration Options

| Option | Type | Required | Description | |--------|------|----------|-------------| | src | string[] | For scan only | Glob patterns for source files to scan | | ignore | string[] | No | Glob patterns for files to skip | | locales.baseLocale | string | Yes | The primary/fallback locale (e.g., "en") | | locales.files | object | For scan only | Map of locale codes to JSON file paths | | locales.directory | string | For compare-locales only | Path to folder containing locale subfolders | | translationFunctions | string[] | No | Function names that call translations | | visibleProps | string[] | No | JSX props that contain visible text | | literalWhitelist | string[] | No | Text strings to ignore (e.g., "OK", "HP") | | minLiteralLength | number | No | Minimum text length to flag as hardcoded (default: 2) | | failOn | string[] | No | Categories that should cause exit code 1 |

Default Values

{
  "translationFunctions": ["i18n.t", "I18n.t", "t", "translate"],
  "visibleProps": ["title", "placeholder", "label", "accessibilityLabel", "message", "confirmText", "cancelText"],
  "literalWhitelist": ["HP", "XP", "PvP", "OK"],
  "minLiteralLength": 2,
  "failOn": ["missing-key", "missing-locale", "hardcoded-text"]
}

Usage Examples

Basic scan

local-guard scan

Compare locales (folder-based)

local-guard compare-locales

JSON output (for CI/CD pipelines)

local-guard scan --format json

Fail on warnings (strict mode)

local-guard scan --fail-on-warning

Custom config file

local-guard scan --config ./my-custom-config.json

Compare locales with custom base locale

local-guard compare-locales --base-locale fr

Combine options

local-guard scan --config ./local-guard.config.json --format json --fail-on-warning

Output Categories

| Category | Severity | Meaning | |----------|----------|---------| | missing-key | error | Code uses a translation key that doesn't exist in the base locale | | missing-locale | error | A key exists in base locale but is missing in another locale | | missing-in-locale | error | A key is missing in another locale's file (will fall back to base locale) | | hardcoded-text | error | Visible text directly in JSX or props without localization | | dynamic-key | warning | Translation call uses a variable (can't be validated statically) | | unused-key | info | A key in locale JSON is never used in code | | config-error | error | Config file or locale file is invalid | | parse-error | error | Source file couldn't be parsed |

Exit Codes

| Code | Meaning | |------|---------| | 0 | No errors (warnings allowed unless --fail-on-warning is set) | | 1 | One or more errors in configured fail-on categories | | 2 | Config file missing or invalid, or locale files couldn't be loaded |

Ignoring False Positives

Ignore a specific line

Add // local-guard-ignore-next-line comment above a line to skip checking:

// i18n-ignore-next-line
<Text>DEBUG: some debug text</Text>

Whitelist specific strings

Add to your config's literalWhitelist:

{
  "literalWhitelist": ["HP", "XP", "OK", "Loading..."]
}

Project Structure

For scan command (single files per locale)

Your locale files should be nested JSON objects:

// src/locales/en.json
{
  "common": {
    "save": "Save",
    "cancel": "Cancel"
  },
  "buttons": {
    "start": "Start Game"
  }
}

These become keys like common.save and buttons.start.

For compare-locales command (folder structure)

Organize your locale files in subfolders, one folder per locale:

src/
  locales/
    en/
      common.json
      buttons.json
      settings.json
    fr/
      common.json
      buttons.json      ← might have missing keys
    de/
      common.json       ← might have missing keys
                      ← buttons.json might be completely missing

Each locale folder contains multiple JSON files. The tool compares corresponding files across locales to find missing translations.

Example common.json:

// en/common.json
{
  "save": "Save",
  "cancel": "Cancel",
  "confirm": "Confirm"
}

// fr/common.json
{
  "save": "Enregistrer",
  "cancel": "Annuler"
  // "confirm" is missing!
}

Integration Examples

Git pre-commit hook

Create .git/hooks/pre-commit:

#!/bin/sh
npx local-guard scan

GitHub Actions

name: i18n-check
on: [pull_request]
jobs:
  i18n:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 18
      - run: npm install
      - run: npx local-guard scan --format json

Troubleshooting

"Config file not found"

Make sure you're running the command from your project root, or specify the config path:

local-guard scan --config ./path/to/config.json

"Failed to load locale file"

Check that the locale file path in your config is correct and the file exists.

"Parse error" on a valid file

The parser supports JavaScript, TypeScript, JSX, and TSX. If you encounter issues, make sure your file syntax is valid.

Development

# Clone the repo
git clone https://github.com/your-repo/local-guard.git
cd local-guard

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build for production
npm run build

# Test with fixtures
npm run test:fixtures

License

MIT