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

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

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

1. 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

1. No language files found: Ensure your lang_path configuration points to the correct directory
2. Missing translations not detected: Check that your translation_patterns match your actual function calls
3. 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

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. 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