Lost In Translation Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require stevegrunwell/lost-in-translation
   

   This replaces Laravel’s default TranslationServiceProvider with an enhanced version.

2. First Use Case: Run your application in a non-production environment (APP_DEBUG=true). Attempt to load a missing translation (e.g., __('non.existent.key')). The package will:

   • Throw a LostInTranslation\MissingTranslationException (if APP_DEBUG is true).
   • Log the missing key to storage/logs/lost-in-translation.log.

3. Where to Look First:

   • Check the log file (storage/logs/lost-in-translation.log) for missing keys.
   • Review the config/translation.php for package-specific settings (e.g., lost_in_translation section).

Implementation Patterns

Core Workflow

1. Detect Missing Translations:

   • Use __(), trans(), or Lang::get() as usual. The package intercepts calls to missing keys.
   • Example:

     // This will trigger a log entry or exception
     $message = __('some.missing.key');
     

2. Log Analysis:

   • Periodically review storage/logs/lost-in-translation.log to identify gaps in translations.
   • Script to parse logs (e.g., extract unique missing keys):

     grep -oP 'missing key: \K[^ ]+' storage/logs/lost-in-translation.log | sort | uniq
     

3. Integration with CI/CD:

   • Add a script to your CI pipeline to fail builds if missing translations exceed a threshold:

     # Example: Fail if >10 missing keys
     grep -c "missing key:" storage/logs/lost-in-translation.log | awk '{if ($1 > 10) exit 1}'
     

4. Dynamic Translation Loading:

   • Use the package to identify missing keys, then auto-generate translation files:

     // Pseudocode: Fetch missing keys from log and create a new language file
     $missingKeys = collect(file('storage/logs/lost-in-translation.log'))
         ->map(fn ($line) => preg_match('/missing key: (.+)/', $line, $matches) ? $matches[1] : null)
         ->filter()
         ->unique();
     
     $missingKeys->each(fn ($key) => Lang::set('en.' . $key, 'default value'));
     

5. Environment-Specific Behavior:

   • Disable exceptions in production by setting lost_in_translation.throw_exceptions to false in config/translation.php:

     'lost_in_translation' => [
         'throw_exceptions' => env('APP_ENV') !== 'production',
         'log_missing' => true,
     ],
     

Gotchas and Tips

Pitfalls

1. Performance Overhead:

   • Logging every missing translation can bloat storage/logs/lost-in-translation.log. Disable logging in production:

     'lost_in_translation' => [
         'log_missing' => env('APP_ENV') !== 'production',
     ],
     

2. False Positives:

   • Dynamic keys (e.g., __('user.message', ['key' => $dynamic])) may log as missing. Use fallback logic:

     __('user.message', [], 'default fallback');
     

3. Exception Handling:

   • MissingTranslationException is thrown only in debug mode. In production, missing translations silently return the key itself (Laravel’s default behavior). Avoid relying on exceptions for user-facing errors.

4. Log Rotation:

   • The log file (lost-in-translation.log) isn’t rotated by default. Configure Laravel’s log rotation or use a symlink to a temporary file for testing.

5. Namespace Conflicts:

   • If you manually override TranslationServiceProvider, ensure the package’s provider is loaded after your custom provider to avoid conflicts.

Debugging Tips

1. Clear Logs Safely:

   • Use a script to clear logs without deleting the file:

     echo "" > storage/logs/lost-in-translation.log
     

2. Test Locally:

   • Simulate missing translations by temporarily renaming your resources/lang directory or editing config/app.php to point to a non-existent path:

     'lang' => 'nonexistent',
     

3. Custom Exceptions:

   • Extend MissingTranslationException to add context (e.g., line numbers):

     use LostInTranslation\MissingTranslationException;
     
     throw new MissingTranslationException(
         "Missing key: {$key}",
         $this->getTraceAsString() // Include stack trace
     );
     

4. Ignore Specific Keys:

   • Filter out known "safe" missing keys (e.g., placeholder keys) by extending the package’s logic:

     // In a service provider, override the missing key handler
     Translation::setMissingCallback(function ($key) {
         if (str_contains($key, 'placeholder.')) return $key;
         // Default behavior
     });
     

5. CI/CD Integration:

   • Use the log file to generate a report of missing translations in pull requests:

     # Example: Generate a markdown report
     echo "# Missing Translations" > missing-translations.md
     grep -oP 'missing key: \K[^ ]+' storage/logs/lost-in-translation.log | sort | uniq >> missing-translations.md
     

Extension Points

1. Custom Logging:

   • Override the logger by binding a custom Monolog\Logger to the lost-in-translation tag in Laravel’s service container:

     $this->app->bind('lost-in-translation.logger', function () {
         return Log::channel('custom');
     });
     

2. Slack/Email Alerts:

   • Extend the package to notify teams about missing translations in real-time:

     // In a service provider
     Translation::setMissingCallback(function ($key) {
         if (app()->environment('production')) {
             Notification::route('slack', config('services.slack.webhook'))
                 ->notify(new MissingTranslationAlert($key));
         }
     });
     

3. Database Backing:

   • Store missing translations in a database table to track trends over time:

     // Migration
     Schema::create('missing_translations', function (Blueprint $table) {
         $table->id();
         $table->string('key');
         $table->string('locale')->default('en');
         $table->timestamps();
     });
     
     // Observer
     event(new MissingTranslationDetected($key, $locale));
     

4. Dynamic Fallbacks:

   • Use the package to auto-generate translations from context (e.g., extract text from views):

     // Pseudocode: Scrape Blade templates for __() calls
     $missingKeys = collect(file(base_path('resources/views/**/*.blade.php')))
         ->map(fn ($content) => preg_match_all('/__\('([^)]+)'\)/', $content, $matches))
         ->flatten()
         ->unique();