🌍 i18n Quality Lint

The ultimate i18n quality linter - Detect untranslated strings, sync keys, and maintain consistency across 60+ languages (including Klingon! 🖖)

✨ What it does

🔍 Translation Quality

• Detects untranslated strings in 60+ languages
• Supports nested JSON structures
• Configurable allowlists for technical terms
• Individual settings per file

🔄 Key Synchronization

• Finds missing/extra keys between files
• Optional key order checking
• Excludes files from sync when needed
• Smart reference file detection
• Manual key order synchronization tool

🎨 Developer Experience

• Colored console output with issue highlighting
• CI/CD friendly with exit codes
• Zero dependencies
• Comprehensive test coverage

🚀 Quick Start

# Install
npm install --save-dev i18n-quality-lint

# Create config
echo '{
  "files": [
    {
      "path": "src/i18n/en.json",
      "language": "english"
    },
    {
      "path": "src/i18n/es.json",
      "language": "spanish"
    }
  ]
}' > .i18ncheckrc.json

# Run check
npx i18n-quality-lint

📊 Example Output

$ npx i18n-quality-lint

Checking: src/i18n/es.json (Spanish)
Found: 2 untranslated values
  PASSWORD: "Password"           # ← English in Spanish file
  CANCEL: "Cancel"

Checking: src/i18n/en.json (English)  
Found: 1 untranslated values
  WELCOME: "Bienvenidos"         # ← Spanish in English file

🔄 Checking key synchronization between files...
Found: 2 synchronization issues
  src/i18n/es.json:
    Missing keys (1):
      EXTRA_KEY                   # ← Key exists in EN but not ES
    Key order issues (1):         # ← Optional: different key order
      Position 1: expected 'WELCOME', found 'LOGIN'

⚙️ Configuration

Create .i18ncheckrc.json in your project root:

📝 Basic Configuration

{
  "files": [
    {
      "path": "src/i18n/en.json",
      "language": "english"
    },
    {
      "path": "src/i18n/es.json",
      "language": "spanish"
    }
  ]
}

🔧 Advanced Configuration

{
  "files": [
    {
      "path": "src/i18n/en.json",
      "language": "english",
      "ignoreKeys": ["DEBUG_MODE", "ADMIN.SECRET_PANEL"],
      "allowlist": ["API", "JWT", "OAuth", "GitHub"]
    },
    {
      "path": "src/i18n/es.json",
      "language": "spanish",
      "ignoreKeys": ["BULK_ACTIONS"],
      "allowlist": ["AWS", "SSO", "ID"]
    },
    {
      "path": "src/i18n/partial.json",
      "language": "french",
      "excludeFromSync": true
    }
  ],
  "checkKeyOrder": true,
  "failOnFindings": true,
  "outputDir": "i18n-reports"
}

📝 Configuration Options

📁 FileConfig Options

🌍 Supported Languages (60+)

📦 Installation

# Project installation (recommended)
npm install --save-dev i18n-quality-lint

# Global installation
npm install -g i18n-quality-lint

💻 Usage

Command Line

# Quick check (console output only)
npx i18n-quality-lint

# Check and save results to file
npx i18n-quality-lint --save

# Sync key order across files (manual operation)
npx i18n-sync-keys

Package.json Scripts

{
  "scripts": {
    "i18n:check": "i18n-quality-lint",
    "i18n:check:save": "i18n-quality-lint --save",
    "i18n:sync-keys": "i18n-sync-keys",
    "i18n:ci": "i18n-quality-lint --fail-on-findings"
  }
}

CI/CD Integration

# GitHub Actions example
- name: Check i18n quality
  run: npx i18n-quality-lint

💼 Use Cases

🏢 Enterprise Projects

• Multi-language applications with 10+ locales
• Ensure consistency across large translation teams
• Automated quality checks in CI/CD pipelines

👥 Development Teams

• Catch translation issues before production
• Maintain synchronized keys across all languages
• Standardize technical terms and abbreviations

🚀 Open Source Projects

• Community-driven translations
• Validate contributor submissions
• Maintain translation quality standards

🎆 Real-world Examples

E-commerce Platform

{
  "files": [
    { "path": "locales/en.json", "language": "english" },
    { "path": "locales/es.json", "language": "spanish" },
    { "path": "locales/fr.json", "language": "french" },
    { "path": "locales/de.json", "language": "german" }
  ],
  "checkKeyOrder": true,
  "failOnFindings": true
}

SaaS Application

{
  "files": [
    {
      "path": "src/i18n/en.json",
      "language": "english",
      "allowlist": ["API", "OAuth", "SaaS", "GitHub"]
    },
    {
      "path": "src/i18n/fr.json",
      "language": "french",
      "ignoreKeys": ["LEGAL.TERMS_OF_SERVICE"],
      "allowlist": ["API", "OAuth"]
    }
  ]
}

🔄 Key Order Synchronization

NEW! Separate tool to manually synchronize key order across translation files:

# Sync key order (uses first file as reference)
npx i18n-sync-keys

Features:

• Uses first file in config as reference for key order
• Preserves all values and extra keys
• Respects excludeFromSync setting
• Safe operation - only reorders, never deletes

Example:

# Before sync:
# en.json: {"WELCOME": "Welcome", "LOGIN": "Login"}
# es.json: {"LOGIN": "Iniciar", "WELCOME": "Bienvenido"}

# After sync:
# en.json: {"WELCOME": "Welcome", "LOGIN": "Login"} (unchanged)
# es.json: {"WELCOME": "Bienvenido", "LOGIN": "Iniciar"} (reordered)

🔧 Advanced Features

Nested Key Support

{
  "ignoreKeys": [
    "ADMIN.SECRET_PANEL",           // Ignore specific nested key
    "DEBUG",                        // Ignore entire section
    "LEGAL.TERMS.SECTION_1.CLAUSE_A" // Deep nesting support
  ]
}

Key Order Checking

{
  "checkKeyOrder": true  // Ensures consistent key order across files
}

Selective Sync Exclusion

{
  "files": [
    { "path": "main.json", "language": "english" },
    { 
      "path": "partial.json", 
      "language": "french",
      "excludeFromSync": true  // Skip sync checks for this file
    }
  ]
}

❓ FAQ

{
  "allowlist": ["API", "OAuth", "JWT", "GitHub", "npm"]
}

{
  "ignoreKeys": ["DEBUG_MODE", "ADMIN.SECRET_PANEL", "LEGAL.TERMS"]
}

{
  "failOnFindings": true
}

🔄 Backward Compatibility

Old configuration format is still supported:

{
  "files": ["src/i18n/es.json"],
  "ignoreKeys": ["BULK_ACTIONS"],
  "allowlist": ["AWS", "API"]
}

🤖 AI Agents & LLM Integration

For AI agents and LLM integration, see AI-README.md for structured documentation.

📊 Stats

• ✅ 60+ languages supported
• ✅ Zero dependencies
• ✅ 12 comprehensive tests
• ✅ CI/CD ready
• ✅ 7.3kB package size

📝 License

MIT © Lev Korsunskyi