Status Generator Laravel Package

Getting Started

Run vendor/bin/lang to explore available commands. Start with these essentials:

1. Initialize missing locales (e.g., for es, fr):

   vendor/bin/lang create --locale=es
   

   Or generate all missing locales at once:

   vendor/bin/lang create
   

2. Check translation status (identify missing/translated keys):

   vendor/bin/lang status
   

   Output: A table showing translation coverage per locale (e.g., en, es).

3. Sync keys (update missing translations from source files):

   vendor/bin/lang sync
   

First Use Case: After adding a new language file (e.g., resources/lang/es/auth.php), run lang sync to detect and add missing keys from en to es.

Implementation Patterns

Workflow Integration

1. CI/CD Pipeline Add to phpunit.yml or GitHub Actions:

   - name: Sync translations
     run: vendor/bin/lang sync
   - name: Validate status
     run: vendor/bin/lang status --format=json | jq -e '.missing == 0'
   

2. Local Development

   # After pulling upstream Laravel updates
   vendor/bin/lang download --url=https://github.com/laravel/framework/archive/refs/heads/10.x.zip --project=framework --ver=10.x --copy=lang
   vendor/bin/lang sync
   

3. Automated Translation Drafts

   vendor/bin/lang translate --locale=es --key=validation.required
   

Key Patterns

• Project-Specific Config: Extend via .lang-status.php (see config quirks).
• Partial Syncs: Use --path to target specific files (e.g., resources/views):

  vendor/bin/lang sync --path=resources/views/auth
  

• Downstream Sync: Copy translations from Laravel core to your package:

  vendor/bin/lang download --url=https://github.com/laravel/laravel/archive/refs/heads/10.x.zip --project=laravel --ver=10.x --copy=lang --only-copy
  

Laravel-Specific Optimizations

• trans_choice Support: Automatically detects pluralization keys (e.g., validation.max.string).
• File Filtering: Skips internal files (e.g., vendor/, node_modules/) by default.

Gotchas and Tips

Pitfalls

1. Locale Creation Without English Running lang create fails if resources/lang/en/ doesn’t exist. Fix: Manually create en/ or use --force (if supported in future versions).

2. Key Detection False Positives Ternary operators (?:) or complex strings may trigger false matches. Tip: Use --debug to inspect parsed keys:

   vendor/bin/lang sync --debug
   

3. Google Translate API Limits The translate command uses Google’s free tier. Tip: Cache results in storage/app/translations/ to avoid rate limits.

4. Path Conflicts Downloading from --copy=lang may overwrite existing files. Tip: Use --only-copy to bypass key lookups:

   vendor/bin/lang download --url=... --only-copy
   

Debugging

• Silent Failures: Add -v for verbose output:

  vendor/bin/lang sync -v
  

• Corrupted Files: If lang status reports errors, manually validate JSON/PHP syntax in resources/lang/.

Extension Points

1. Custom Key Parsers Extend LaravelLang\StatusGenerator\Parsers\Parser to handle project-specific syntax (e.g., custom translation helpers).

2. Post-Sync Hooks Use Laravel’s commands event to trigger actions after lang sync:

   // app/Providers/EventServiceProvider.php
   protected $listen = [
       'Illuminate\Console\Events\ArtisanStarting' => [
           \App\Listeners\PostSyncHook::class,
       ],
   ];
   

3. Config Overrides Create .lang-status.php in your project root to customize:

   return [
       'skip_paths' => ['resources/views/vendor/'],
       'default_locale' => 'pt_BR',
   ];
   

Pro Tips

• Batch Translations: Use --locale=es,fr to translate multiple locales at once:

  vendor/bin/lang translate --locale=es,fr --key=validation.unique
  

• Laravel 13+: Leverage Laravel\Lang\StatusGenerator\Services\LocaleService directly in custom commands for programmatic access.
• Git Integration: Add resources/lang/ to .gitignore and commit only synced files via:

  vendor/bin/lang sync && git add resources/lang/