Translation Validator

⚡ Ultra-fast translation key validator for TypeScript projects with i18n support.

Validates that all translation keys used in your React/TypeScript code actually exist in your translation files. Built with Rust for maximum performance.

✨ Features

• ⚡ Blazingly Fast - Validates 600+ files in ~1 second using parallel processing
• 🌍 Multi-language - Auto-detects any number of language files (en, cs, fr, de, etc.)
• 🎯 100% Accurate - Handles multiple useTranslate() scopes per file
• 🔧 Zero Config - Works out of the box
• 🚀 Easy Integration - Pre-built binaries, no Rust required
• 📦 Lightweight - Single binary, no dependencies

📦 Installation

Option 1: Pre-built Binary (Recommended)

Download the latest release for your platform:

macOS:

curl -L https://github.com/lafluence/translation-validator/releases/latest/download/translation-validator-macos -o translation-validator
chmod +x translation-validator

Linux:

curl -L https://github.com/lafluence/translation-validator/releases/latest/download/translation-validator-linux -o translation-validator
chmod +x translation-validator

Option 2: Build from Source

Requires Rust 1.70+

git clone https://github.com/lafluence/translation-validator.git
cd translation-validator
cargo build --release
# Binary will be in target/release/translation-validator

🚀 Quick Start

1. Project Structure

Your project should have this structure:

your-project/
├── src/
│   ├── translations/
│   │   ├── en.ts       # English translations
│   │   ├── cs.ts       # Czech translations  
│   │   ├── fr.ts       # French (optional)
│   │   └── ...         # Any 2-letter language code
│   └── components/
│       └── *.tsx       # Your React components
└── tools/
    └── translation-validator  # This binary

2. Translation File Format

// src/translations/en.ts
export const en = {
  common: {
    save: "Save",
    cancel: "Cancel",
    delete: "Delete",
  },
  errors: {
    messages: {
      generic: "Something went wrong",
      notFound: "Not found",
    },
  },
} as const;

export type TranslationKeys = typeof en;

3. Usage in Components

import { useTranslate } from "hooks/useTranslate";

const MyComponent = () => {
  const { t } = useTranslate("common");
  
  return (
    <button>{t("save")}</button>  // ✅ Valid
    // <button>{t("invalid")}</button>  // ❌ Fails validation
  );
};

4. Run Validation

# From your project root
./tools/translation-validator

# Output:
# 🔍 Validating translation keys...
# 📦 Loaded 100 EN keys from src/translations/en.ts
# 📦 Loaded 98 CS keys from src/translations/cs.ts
# 📂 Scanning 250 files...
# ✅ All translation keys valid! (250 files checked in 0.8s)

🎯 Supported Patterns

✅ Basic Scoped Translation

const { t } = useTranslate("errors.messages");
t("generic")  // Validates: errors.messages.generic

✅ Multiple Scopes Per File

const { t } = useTranslate("common");
const { tScope: tErrors } = useTranslate("errors.messages");

t("save")          // Validates: common.save
tErrors("generic") // Validates: errors.messages.generic

✅ Renamed Variables

const { tScope: tScopeKeywords } = useTranslate("search.keywords");
tScopeKeywords("placeholder")  // Validates: search.keywords.placeholder

✅ Full Path Translation

const { tNoPath } = useTranslate("any.scope");
tNoPath("errors.messages.generic")  // Validates full path

✅ Function Parameters (Smart Matching)

const MyButton = ({ t }) => (
  <button>{t("save")}</button>  // Finds best match: common.save
);

📊 Language Auto-Detection

The validator automatically detects all translation files matching the pattern src/translations/*.ts:

src/translations/
├── en.ts  ✅ Auto-detected
├── cs.ts  ✅ Auto-detected  
├── fr.ts  ✅ Auto-detected
├── de.ts  ✅ Auto-detected
└── es.ts  ✅ Auto-detected

It will validate that keys exist in all detected languages.

🔧 Integration

package.json Script

{
  "scripts": {
    "translate:validate": "./tools/translation-validator",
    "checks": "tsc && eslint && pnpm translate:validate"
  }
}

CI/CD (GitHub Actions)

- name: Validate Translations
  run: |
    chmod +x ./tools/translation-validator
    ./tools/translation-validator

Pre-commit Hook

#!/bin/sh
./tools/translation-validator || exit 1

🏗️ How It Works

1. Auto-detects Languages - Scans src/translations/ for *.ts files
2. Loads Translation Keys - Parses all language files and extracts keys
3. Scans Source Files - Walks through all .ts and .tsx files
4. Detects Scopes - Finds useTranslate("scope") calls and maps variables to scopes
5. Validates Calls - Checks each t("key") against the correct scope
6. Reports Errors - Shows missing keys with file name, line number, and which languages are missing them

📈 Performance

Benchmarked on a real TypeScript project:

• Translation Keys: 2,474 EN + 2,453 CS = 4,927 total
• Files Scanned: 614 TypeScript files
• Validation Time: ~1.1 seconds

Comparison: | Tool | Time | Accuracy | Notes | |------|------|----------|-------| | Rust Validator | 1.1s | ✅ 100% | This tool | | JavaScript Validator | 0.5s | ❌ False positives | Has bugs | | ESLint Plugin | ~5s | ✅ 100% | Real-time validation |

🐛 Troubleshooting

Binary Not Executable

chmod +x translation-validator

No Translation Files Found

Make sure you have files matching src/translations/*.ts where * is a 2-letter language code (en, cs, fr, etc.).

False Positives

The validator skips:

• Dynamic keys: t(someVariable)
• Template literals: t(\key-${id}`)`

For dynamic translations, use tNoPath() with the full key path.

🛠️ Development

Build

cargo build --release

Run Tests

cargo test

Dependencies

• regex - Pattern matching
• walkdir - Directory traversal
• rayon - Parallel processing
• colored - Terminal colors

📄 License

MIT License - see LICENSE file for details

🤝 Contributing

Contributions welcome! Please feel free to submit a Pull Request.

1. Fork the project
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

🙏 Acknowledgments

Built for validating i18n translations in React/TypeScript projects using the useTranslate hook pattern.

📮 Support

• 🐛 Report a bug
• 💡 Request a feature
• 💬 Discussions