README

A comprehensive Laravel package for checking translation integrity by detecting duplicate keys, missing translations, and unused keys in your Laravel applications.

Features

🔍 Duplicate Key Detection: Find duplicate translation keys in PHP array and JSON language files
🚫 Missing Key Detection: Scan your codebase for translation function calls and identify missing translations
🗑️ Unused Key Detection: Find translation keys that exist but are not used in your code
📊 Multiple Output Formats: Get results in table, JSON, or text format
🎯 CI/CD Ready: Fail-on-error options for automated pipelines
⚙️ Highly Configurable: Customize paths, file patterns, and translation function patterns

Installation

Via Composer

composer require kilic-berkay/laravel-translation-integrity-checker

Manual Installation

Clone this repository into your project
Add the package to your composer.json:

{
    "require": {
        "kilic-berkay/laravel-translation-integrity-checker": "*"
    },
    "repositories": [
        {
            "type": "path",
            "url": "./Translation Integrity Checker"
        }
    ]
}

Run composer install

Service Provider Registration

The package will auto-register with Laravel. If you need to manually register it, add the service provider to your config/app.php:

'providers' => [
    // ...
    KilicBerkay\TranslationIntegrityChecker\TranslationIntegrityCheckerServiceProvider::class,
],

Publish Configuration (Optional)

php artisan vendor:publish --tag=translation-integrity-checker-config

Usage

Basic Commands

Check for Duplicate Keys

# Check for duplicate translation keys
php artisan lang:check-duplicates

# With custom language path
php artisan lang:check-duplicates --lang-path=/custom/lang/path

# Output in JSON format
php artisan lang:check-duplicates --format=json

# Fail on error (useful for CI/CD)
php artisan lang:check-duplicates --fail-on-error

Check for Missing Keys

# Check for missing translation keys
php artisan lang:check-missing

# With custom source paths
php artisan lang:check-missing --source-paths=app --source-paths=resources/views

# Output in text format
php artisan lang:check-missing --format=text

Check for Unused Keys

# Check for unused translation keys
php artisan lang:check-unused

# With custom configuration
php artisan lang:check-unused --lang-path=/custom/lang --source-paths=app

Run All Checks

# Run all checks
php artisan lang:check-all

# Skip specific checks
php artisan lang:check-all --skip-unused

# Custom configuration for all checks
php artisan lang:check-all --lang-path=/custom/lang --source-paths=app --format=json

Example Output

Duplicate Keys Check

🔍 Checking for duplicate translation keys...
❌ Duplicate translation keys found:

Locale: en
File: auth.php
┌─────────────┬─────┐
│ Key         │ Count│
├─────────────┼─────┤
│ auth.failed │ 2    │
│ auth.throttle│ 3   │
└─────────────┴─────┘

Missing Keys Check

🔍 Checking for missing translation keys...
❌ Missing translation keys found:

Locale: en
┌─────────────────┐
│ Missing Key     │
├─────────────────┤
│ auth.new_user   │
│ validation.email │
└─────────────────┘

Unused Keys Check

🔍 Checking for unused translation keys...
⚠️  Unused translation keys found:

Locale: en
┌─────────────────┐
│ Unused Key      │
├─────────────────┤
│ old.translation │
│ deprecated.key  │
└─────────────────┘

Configuration

The package configuration file (config/translation-integrity-checker.php) allows you to customize:

Language Files Path

'lang_path' => resource_path('lang'),

Source Paths to Scan

'source_paths' => [
    app_path(),
    resource_path('views'),
    resource_path('js'),
    base_path('routes'),
],

File Patterns

'file_patterns' => [
    '*.php',
    '*.blade.php',
    '*.vue',
    '*.js',
    '*.ts',
],

Translation Function Patterns

'translation_patterns' => [
    // Laravel translation helpers
    '/__\s*\(\s*[\'"]([^\'"]+)[\'"]\s*\)/',
    '/trans\s*\(\s*[\'"]([^\'"]+)[\'"]\s*\)/',
    '/@lang\s*\(\s*[\'"]([^\'"]+)[\'"]\s*\)/',
    
    // Vue.js i18n patterns
    '/\$t\s*\(\s*[\'"]([^\'"]+)[\'"]\s*\)/',
    
    // JavaScript i18n patterns
    '/i18n\.t\s*\(\s*[\'"]([^\'"]+)[\'"]\s*\)/',
],

Excluded Paths

'excluded_paths' => [
    base_path('vendor'),
    base_path('node_modules'),
    base_path('storage'),
    base_path('bootstrap/cache'),
],

CI/CD Integration

GitHub Actions

name: Translation Integrity Check

on: [push, pull_request]

jobs:
  translation-check:
    runs-on: ubuntu-latest
    
    steps:
    - uses: actions/checkout@v3
    
    - name: Setup PHP
      uses: shivammathur/setup-php@v2
      with:
        php-version: '8.1'
        
    - name: Install dependencies
      run: composer install --prefer-dist --no-progress
        
    - name: Run translation integrity checks
      run: php artisan lang:check-all --fail-on-error

GitLab CI

translation-check:
  stage: test
  script:
    - composer install --prefer-dist --no-progress
    - php artisan lang:check-all --fail-on-error
  only:
    - merge_requests
    - main

Jenkins Pipeline

pipeline {
    agent any
    
    stages {
        stage('Translation Check') {
            steps {
                sh 'composer install --prefer-dist --no-progress'
                sh 'php artisan lang:check-all --fail-on-error'
            }
        }
    }
}

Environment Variables

You can configure the package behavior using environment variables:

# Output format (table, json, text)
TRANSLATION_CHECKER_OUTPUT_FORMAT=json

# Fail on errors (true/false)
TRANSLATION_CHECKER_FAIL_ON_ERRORS=true

# Verbose output (true/false)
TRANSLATION_CHECKER_VERBOSE=false

Advanced Usage

Custom Translation Patterns

Add custom patterns to detect your specific translation function calls:

'translation_patterns' => [
    // Your custom patterns
    '/myCustomTrans\s*\(\s*[\'"]([^\'"]+)[\'"]\s*\)/',
    '/translate\s*\(\s*[\'"]([^\'"]+)[\'"]\s*\)/',
],

Excluding Specific Files

'excluded_paths' => [
    base_path('vendor'),
    base_path('node_modules'),
    base_path('storage'),
    base_path('bootstrap/cache'),
    base_path('tests'), // Exclude test files
],

Multiple Language Paths

If you have translations in multiple locations, you can run checks for each:

# Check main language files
php artisan lang:check-all --lang-path=resources/lang

# Check package language files
php artisan lang:check-all --lang-path=vendor/package/lang

Troubleshooting

Common Issues

No language files found: Ensure your lang_path configuration points to the correct directory
Missing translations not detected: Check that your translation_patterns match your actual function calls
Performance issues: Consider excluding large directories like vendor and node_modules

Debug Mode

Enable verbose output to see detailed information:

php artisan lang:check-all --verbose

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests
Submit a pull request

License

This package is open-sourced software licensed under the MIT license.

Support

For support, please open an issue on GitHub or contact the maintainers.

Changelog

v1.0.0

Initial release
Duplicate key detection
Missing key detection
Unused key detection
Multiple output formats
CI/CD integration support

kilic-berkay / laravel-translation-integrity-checker

Maintainers

Package info

Statistics

Security