GrumPHP Laravel Translation Checker

A GrumPHP extension that validates Laravel translation files on every commit. Detects missing keys, duplicate keys, and keeps all locale files synchronized.

Features

• Detects missing translation keys across all locales
• Detects duplicate keys within language files (PHP silently overwrites duplicates)
• Supports nested translation keys (dot notation: password.reset)
• Auto-fix mode: automatically adds missing keys from the base language
• Auto-stage mode: stages fixed files for commit
• Configurable: base language, lang path, ignore keys, triggered file extensions
• Framework agnostic: works with any PHP project using Laravel-style lang/ files

Installation

composer require --dev kalimeraa/grumphp-laravel-translation-checker

Configuration

Add the extension and task to your grumphp.yml:

grumphp:
  extensions:
    - Kalimeraa\GrumPHPTranslationChecker\ExtensionLoader
  tasks:
    translation_checker:
      base_lang: en
      lang_path: lang
      check_duplicates: true
      triggered_by: ['php']
      ignore_keys: []

Options

Auto-fix Mode

When auto_fix is enabled, missing keys are automatically copied from the base language:

translation_checker:
  base_lang: en
  auto_fix: pre_commit     # Fix on commit
  auto_stage: pre_commit   # Stage fixed files

Possible values for auto_fix and auto_stage:

• false — disabled (default)
• true — always enabled
• 'pre_commit' — only during git pre-commit
• 'run' — only during manual grumphp run

Ignoring Keys

Some keys are intentionally the same across languages (e.g., currency codes, abbreviations):

translation_checker:
  ignore_keys:
    - EUR
    - USD
    - CRM
    - FAQ

Expected Directory Structure

lang/
├── en/
│   ├── general.php
│   ├── auth.php
│   └── validation.php
├── tr/
│   ├── general.php
│   ├── auth.php
│   └── validation.php
└── de/
    ├── general.php
    ├── auth.php
    └── validation.php

Each file returns a PHP array:

<?php

return [
    'welcome' => 'Welcome',
    'login' => 'Login',
    'password' => [
        'reset' => 'Reset Password',
        'confirm' => 'Confirm Password',
    ],
];

Example Output

When missing keys are found:

Translation check failed!

lang/tr/general.php is missing 4 keys: settings, profile, password.reset, password.confirm
lang/de/auth.php is missing 2 keys: throttle, failed

When duplicate keys are found:

Translation check failed!

lang/en/general.php has duplicate keys: name (2x), email (2x)

Running Manually

./vendor/bin/grumphp run --tasks=translation_checker

License

MIT License. See LICENSE for details.