Publisher Laravel Package

Getting Started

Minimal Setup

1. Install via Composer (dev dependency):

   composer require --dev laravel-lang/publisher
   

2. Publish default translations (core Laravel strings):

   php artisan lang:publish
   

   • Outputs files to resources/lang/ (e.g., en/auth.php, es/validation.php).
   • Preserves existing files if they exist.

3. Verify structure:

   tree resources/lang -L 2
   

   Expected output:

   resources/lang/
   ├── en/
   │   ├── auth.php
   │   ├── validation.php
   │   └── ...
   └── [other_locales]/
   

First Use Case: Localizing Auth Messages

1. Publish translations:

   php artisan lang:publish
   

2. Edit resources/lang/en/auth.php (e.g., change "Login" to "Sign In").
3. Test in app:

   echo trans('auth.login'); // Outputs "Sign In"
   

Implementation Patterns

Workflow: Managing Translations

1. Publish upstream updates (e.g., Laravel 13 auth strings):

   php artisan lang:update
   

   • Merges changes from laravel-lang/locales into resources/lang/.
   • Uses 3-way merge to preserve local overrides.

2. Add a new locale (e.g., French):

   php artisan lang:publish fr
   

   • Publishes all files for fr to resources/lang/fr/.

3. Remove unused locales:

   php artisan lang:remove de
   

   • Deletes resources/lang/de/ and updates config.

Integration with Laravel

• Translation Helpers: Works natively with trans(), __(), and Lang::get().
• Validation Messages: Extends Laravel’s built-in validation language files.
• Config Overrides: Supports .env overrides (e.g., LANG_PUBLISHER_DEFAULT_LOCALE=es).

Customization Patterns

1. Extend with Custom Locales:

   // config/lang-publisher.php
   'locales' => [
       'en' => 'English',
       'fr' => 'Français',
       'custom' => [
           'path' => 'vendor/custom-translations',
           'name' => 'Custom',
       ],
   ],
   

2. Post-Publish Hooks:

   // app/Providers/AppServiceProvider.php
   use LaravelLang\Publisher\Events\LangPublished;
   
   public function boot()
   {
       LangPublished::listen(function ($event) {
           // Run custom logic after publish/update
           Log::info("Translations updated for {$event->locale}");
       });
   }
   

CI/CD Integration

• Automate updates in CI (e.g., GitHub Actions):

  - name: Update translations
    run: php artisan lang:update --force
  

• Prevent merge conflicts:

  php artisan lang:update --dry-run  # Check changes before applying
  

Gotchas and Tips

Pitfalls

1. File Overwrites:

   • lang:publish overwrites existing files by default. Use --force to skip confirmation.
   • Fix: Backup resources/lang/ before running:

     cp -r resources/lang/ resources/lang.bak/
     

2. Locale Conflicts:

   • If resources/lang/ contains files not in laravel-lang/locales, they’re ignored during updates.
   • Fix: Use lang:publish --all to include all files.

3. Subkey Merging:

   • Nested arrays (e.g., auth.failed) may lose local overrides if upstream keys are added.
   • Fix: Use lang:update --preserve to retain all subkeys.

4. Lumen Support:

   • Requires manual lang_path() definition in bootstrap/app.php:

     $app->withFacades();
     if (! function_exists('lang_path')) {
         function lang_path() { return __DIR__.'/../resources/lang'; }
     }
     

Debugging

• Dry Runs:

  php artisan lang:update --dry-run -v
  

  • Shows diffs without modifying files.

• Log Output: Enable verbose mode to trace file operations:

  php artisan lang:publish -v
  

Configuration Quirks

1. .env Overrides:

   LANG_PUBLISHER_DEFAULT_LOCALE=es
   LANG_PUBLISHER_SMART_PUNCTUATION=true  # French/Italian rules
   

   • Note: Smart punctuation requires HTML-aware strings (see release 14.6.4).

2. Project Name Check:

   • Fails if config/app.php lacks a name key. Fix:

     'name' => env('APP_NAME', 'Laravel'),
     

Extension Points

1. Custom Publishers: Extend LaravelLang\Publisher\Publisher to support non-Laravel-Lang sources:

   class CustomPublisher extends Publisher
   {
       protected function getSourcePath(): string
       {
           return base_path('vendor/custom-translations');
       }
   }
   

2. Event Listeners:

   • LangPublished: Triggered after publish/update.
   • LangRemoved: Triggered after locale deletion.

3. Command Overrides: Publish a custom command:

   php artisan vendor:publish --tag="lang-publisher-commands"
   

   • Override app/Console/Commands/LangPublishCommand.php.

Performance Tips

• Exclude Large Files:

  // config/lang-publisher.php
  'exclude' => [
      'resources/lang/large-file.json',
  ],
  

• Parallel Updates: For monorepos, update locales in parallel:

  parallel -j 4 'php artisan lang:update {}' ::: en es fr de