Publisher Laravel Package

Getting Started

Minimal Steps to First Use

1. Installation

   composer require --dev laravel-lang/publisher
   

   Ensure your Laravel version (10–13) is supported (check releases).

2. Publish Config

   php artisan vendor:publish --provider="LaravelLang\Publisher\PublisherServiceProvider"
   

   This creates config/publisher.php with default settings (e.g., locales, default_locale, smart_punctuation).

3. Publish Translations

   php artisan lang:publish
   

   • Publishes Laravel Lang’s core translations (e.g., auth.php, validation.php) to resources/lang/{locale}/.
   • Overrides existing files only if upstream versions are newer (configurable via force_overwrite).

4. Verify Check resources/lang/ for new locale folders (e.g., en, fr, es). Test with:

   __('validation.required', [], 'es'); // Should return Spanish validation message
   

First Use Case: Adding a New Locale

1. Update Config

   // config/publisher.php
   'locales' => [
       'en', 'es', 'fr', 'de', // Add your locales
   ],
   

2. Publish Updates

   php artisan lang:publish
   

3. Set Default Locale (if needed)

   // config/app.php
   'locale' => 'es',
   

Where to Look First

• Documentation for CLI commands, config options, and troubleshooting.
• config/publisher.php for customization (e.g., ignore_files, smart_punctuation per locale).
• resources/lang/ to inspect published files and manual overrides.

Implementation Patterns

Core Workflows

1. Publishing and Updating Translations

• Initial Setup

  php artisan lang:publish --locales=es,fr --force
  

  • --locales: Target specific locales (comma-separated).
  • --force: Overwrite existing files (use cautiously).

• Incremental Updates

  php artisan lang:update
  

  • Only updates files where upstream versions are newer than local overrides.

• Selective Publishing

  php artisan lang:publish --files=auth,validation
  

  • Publishes only specified files (e.g., auth.php, validation.php).

2. Removing Locales

php artisan lang:remove --locales=it

• Deletes the it locale folder and all its files.

3. CI/CD Integration

GitHub Actions Example (.github/workflows/locales.yml):

name: Sync Locales
on:
  schedule:
    - cron: '0 0 * * 0' # Weekly sync
  workflow_dispatch:

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-php@v3
        with:
          php-version: '8.2'
      - run: composer install --dev
      - run: php artisan lang:update --locales=es,fr
      - run: git config --global user.name "CI Bot"
      - run: git config --global user.email "ci@example.com"
      - run: git add resources/lang/
      - run: git commit -m "chore: sync translations" || echo "No changes"
      - run: git push

• Best Practices:
  • Run in a separate branch to avoid merge conflicts.
  • Use --dry-run first to preview changes:

    php artisan lang:update --dry-run
    

4. Customizing Translations

• Override Defaults: Edit resources/lang/{locale}/ files manually. Publisher respects local overrides during updates.
• Add Custom Files: Place additional translation files (e.g., custom.php) in resources/lang/{locale}/ and exclude them from publishing:

  // config/publisher.php
  'ignore_files' => ['custom.php'],
  

5. Smart Punctuation

Enable for French/other locales:

// config/publisher.php
'smart_punctuation' => [
    'fr' => true,
    'es' => false,
],

• Automatically replaces straight quotes (") with curly quotes (“ ”) for locales that require it.

Integration Tips

Laravel Localization

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

  // app/Http/Middleware/SetLocale.php
  public function handle($request, Closure $next) {
      App::setLocale($request->header('Accept-Language') ?? config('app.fallback_locale'));
      return $next($request);
  }
  

• Fallback Chains: Configure in config/app.php:

  'fallback_locales' => ['es' => ['en'], 'fr' => ['en']],
  

Testing

• Unit Tests: Mock translations:

  use LaravelLang\Publisher\Facades\Publisher;
  
  public function test_translation() {
      Publisher::fake(); // Override translations for testing
      Publisher::shouldReturn('Hello', 'test.key');
      $this->assertEquals('Hello', __('test.key'));
  }
  

• Feature Tests: Test locale-specific routes:

  public function test_french_validation() {
      $response = $this->withHeader('Accept-Language', 'fr')
                       ->post('/register', ['name' => '']);
      $response->assertSessionHasErrors('name', 'Le champ nom est requis.');
  }
  

Monorepos/Modular Apps

• Shared Config: Centralize config/publisher.php in a shared package.
• Atomic Updates: Use --files to sync only changed modules:

  php artisan lang:update --files=auth,pagination --locales=es
  

Gotchas and Tips

Pitfalls

1. File Conflicts

   • Issue: Local overrides are lost during updates if upstream files are newer.
   • Fix: Use --force sparingly. Prefer manual merges or:

     php artisan lang:update --dry-run  # Preview changes first
     

   • Pro Tip: Use git diff to compare local vs. upstream files before updating.

2. Locale-Specific Quirks

   • French Smart Punctuation: May break HTML/JS if not escaped. Disable for non-text files:

     'smart_punctuation' => ['fr' => ['except' => ['*.php']]],
     

   • Right-to-Left (RTL) Languages: Arabic/Hebrew may need additional CSS/HTML adjustments (not handled by the publisher).

3. Circular Dependencies

   • Issue: Infinite loops if translation files reference each other (e.g., auth.php includes validation.php which includes auth.php).
   • Fix: Flatten nested keys or use the --no-deep-merge flag (if available in future versions).

4. Case Sensitivity

   • Issue: Linux/macOS vs. Windows file systems may cause case-sensitivity issues (e.g., Auth.php vs. auth.php).
   • Fix: Standardize filenames in ignore_files or use .gitattributes:

     resources/lang/* text=auto eol=lf
     

5. Lumen Support

   • Issue: lang_path() may not be autoloaded in Lumen.
   • Fix: Manually define in bootstrap/app.php:

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

Debugging

1. Verbose Output

   php artisan lang:publish --verbose
   

   • Shows which files are being skipped/overwritten.

2. Log File Conflicts Enable logging in config/publisher.php:

   'log_conflicts' => true,
   

   • Logs conflicts to storage/logs/publisher.log.

3. Checksum Mismatches

   • If updates fail silently, verify file permissions:

     chmod -R 755 resources/lang/
     

Configuration Quirks

1. .env Overrides

   • Set publisher options in .env:

     PUBLISHER_LOCALES=es,fr
     PUBLISHER_FORCE_OVERWRITE=false
     

   • Note: Only supports string/boolean values (not nested arrays).

2. Project Name Detection

   • The package auto-detects