Publisher Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require --dev laravel-lang/publisher
   

   Add to composer.json under require-dev if not using Laravel’s default package discovery.

2. Publish Core Translations:

   php artisan lang:publish
   

   This generates resources/lang/ with default Laravel translations (e.g., auth.php, validation.php) from Laravel-Lang’s upstream repository.

3. First Use Case:

   • Override a Translation: Edit resources/lang/en/auth.php to customize the "failed" key.
   • Add a New Locale: Run php artisan lang:publish fr to publish French translations.

Where to Look First

• Official Documentation for CLI command reference.
• config/lang.php (auto-generated) for configuration like default_locale or smart_punctuation.
• resources/lang/ directory structure to understand how translations are organized (e.g., en/, fr/).

Implementation Patterns

Core Workflows

1. Publishing Translations:

   • Full Publish: php artisan lang:publish (all supported locales).
   • Single Locale: php artisan lang:publish fr (French only).
   • Custom Source: Override the default Laravel-Lang source by setting the source config:

     'source' => 'https://github.com/your-repo/translations',
     

2. Updating Translations:

   • Pull upstream changes without overwriting local overrides:

     php artisan lang:update
     

   • Force overwrite local files (use with caution):

     php artisan lang:update --force
     

3. Removing Locales:

   • Delete a locale entirely (e.g., es):

     php artisan lang:remove es
     

4. Environment-Specific Config:

   • Set PUBLISHER_DEFAULT_LOCALE in .env to avoid hardcoding:

     PUBLISHER_DEFAULT_LOCALE=es
     

Integration Tips

• CI/CD Pipeline: Add to deploy.sh or GitHub Actions to auto-update translations on main:

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

  Use --force sparingly (e.g., only in staging).

• Custom Translation Files: Place custom files (e.g., resources/lang/en/custom.php) outside the lang/ directory published by Laravel-Lang to avoid being overwritten.

• Lumen Support: Ensure lang_path() is defined in bootstrap/app.php:

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

• Validation Messages: Extend validation.php by adding keys under a namespace (e.g., custom.*) to avoid conflicts:

  'custom' => [
      'email' => 'The :attribute must be a valid email address.',
  ],
  

• Dynamic Locale Switching: Use middleware to set the locale dynamically:

  public function handle(Request $request, Closure $next) {
      app()->setLocale($request->header('Accept-Language') ?? config('app.locale'));
      return $next($request);
  }
  

Gotchas and Tips

Pitfalls

1. Local Overrides Lost:

   • Running lang:update --force wipes all local changes. Use --dry-run first to preview changes:

     php artisan lang:update --dry-run
     

   • Solution: Commit custom translations to version control before updating.

2. Namespace Collisions:

   • If you add keys like auth.password to validation.php, they’ll conflict with Laravel’s core auth.php. Use namespaced keys (e.g., validation.custom.*).

3. Lumen Compatibility:

   • Lumen lacks lang_path() by default. Ensure it’s defined (see Integration Tips) or use the full path:

     php artisan lang:publish --path=/full/path/to/resources/lang
     

4. Smart Punctuation Quirks:

   • Enabling smart_punctuation in config/lang.php may break HTML-escaped strings. Disable for API responses:

     'smart_punctuation' => env('APP_ENV') !== 'local',
     

5. Git Ignore:

   • The lang/ directory may contain sensitive data (e.g., placeholder emails). Add to .gitignore if needed, but ensure backups exist.

Debugging

• Command Not Found: Ensure the package is listed under require-dev in composer.json and run composer dump-autoload.

• Permission Denied: Use --force with file operations or adjust storage permissions:

  chmod -R 775 resources/lang/
  

• Locale Not Found: Verify the locale exists in Laravel-Lang’s supported locales. For custom locales, use php artisan lang:publish custom_locale and manually add translations.

Extension Points

1. Custom Sources: Extend the LaravelLang\Publisher\Contracts\Source interface to pull translations from a custom repository:

   // app/Providers/PublisherServiceProvider.php
   use LaravelLang\Publisher\Contracts\Source;
   
   class CustomSource implements Source {
       public function get($locale) { /* ... */ }
   }
   

   Bind it in the service provider:

   $this->app->bind('publisher.source', function () {
       return new CustomSource();
   });
   

2. Post-Update Hooks: Listen to the lang.published event to run custom logic after updates:

   // app/Providers/EventServiceProvider.php
   protected $listen = [
       'LaravelLang\Publisher\Events\LangPublished' => [
           \App\Listeners\SyncTranslationsToS3::class,
       ],
   ];
   

3. Configuration Overrides: Override config/lang.php in config/lang.php (auto-generated) to disable features like smart_punctuation or change the default_locale.

Pro Tips

• Backup Strategy: Use git stash or rsync to backup resources/lang/ before running lang:update --force.

• Partial Updates: Update only specific files by leveraging the --file option (if supported in future versions) or manually merge changes.

• Locale-Specific Config: Use config('app.locale') in Blade to conditionally load assets:

  @if(app()->getLocale() === 'fr')
      <link rel="stylesheet" href="{{ asset('css/fr.css') }}">
  @endif
  

• Testing: Mock translations in tests using trans() with a custom provider:

  // tests/TestCase.php
  protected function getEnvironmentSetUp($app) {
      $app['translator']->setLocale('test');
      $app['translator']->addNamespace('test', __DIR__.'/stubs/lang');
  }