README

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

Option	Type	Default	Description
`base_lang`	string	`en`	The reference language to compare against
`lang_path`	string	`lang`	Path to the language files directory
`check_duplicates`	bool	`true`	Check for duplicate keys in files
`triggered_by`	array	`['php']`	File extensions that trigger the check
`ignore_keys`	array	`[]`	Keys to skip during comparison
`auto_fix`	bool/string	`false`	Auto-add missing keys from base language
`auto_stage`	bool/string	`false`	Auto `git add` fixed files

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.

kalimeraa / grumphp-laravel-translation-checker

Maintainers

Package info

Statistics

Security