Status Generator Laravel Package

Getting Started

Minimal Steps

1. Install the package in your Laravel project:

   composer require laravel-lang/status-generator --dev
   

2. Publish the configuration (if needed):

   php artisan vendor:publish --provider="LaravelLang\StatusGenerator\StatusGeneratorServiceProvider"
   

3. Run the status check to see translation coverage:

   vendor/bin/lang status
   

First Use Case: Localization Health Check

Use lang status to generate a report of translation completeness across all locales. This helps identify missing or incomplete translations before a release.

Where to Look First

• Command Reference: vendor/bin/lang (or php artisan lang:* if registered as an artisan command).
• Configuration: config/lang-status.php (if published).
• Key Sync: Use lang sync to ensure all translation keys exist in target locales.

Implementation Patterns

Core Workflows

1. Initial Setup

   • Create missing locales:

     vendor/bin/lang create --locale=es --locale=fr
     

   • Download translations from a reference project (e.g., Laravel Framework):

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

2. Daily Maintenance

   • Sync keys to ensure all translations have entries (even if empty):

     vendor/bin/lang sync
     

   • Translate missing keys using Google Translate (requires API key):

     vendor/bin/lang translate --google-key=YOUR_API_KEY
     

   • Check status before releases:

     vendor/bin/lang status
     

3. Multi-Project Sync

   • Use --copy to mirror translations from other projects (e.g., Jetstream):

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

Integration Tips

• CI/CD Pipeline: Add lang sync and lang status to your pre-release checks to fail builds if translations are incomplete.
• Git Hooks: Use lang sync in a pre-commit hook to ensure translation keys are never missed.
• Custom Parsing: Extend the parser for project-specific translation patterns (e.g., custom blade directives).
• Symfony Compatibility: Works seamlessly with Symfony 7+ and Laravel 8–13.

Example: Full Localization Workflow

# 1. Create new locales
vendor/bin/lang create --locale=de --locale=ja

# 2. Sync keys from English to new locales
vendor/bin/lang sync

# 3. Translate missing keys via Google Translate
vendor/bin/lang translate --google-key=$GOOGLE_API_KEY

# 4. Verify status before release
vendor/bin/lang status

Gotchas and Tips

Pitfalls

1. Google Translate API Key Required

   • The translate command requires a Google Cloud API key. Without it, you’ll need to manually translate keys or disable the feature.
   • Fix: Set up a free-tier Google Cloud project and enable the Translate API.

2. Key Detection Limitations

   • The parser may miss dynamic or complex translation keys (e.g., nested arrays, custom blade syntax).
   • Fix: Use --only-copy to bypass key detection if you’re certain about file structures.

3. Locale File Structure Assumptions

   • Assumes standard Laravel locale file structure (resources/lang/{locale}/). Custom paths may break commands.
   • Fix: Configure custom paths in config/lang-status.php or extend the package.

4. English Locale Dependency

   • Commands like sync and download rely on an existing English (en) locale. Missing en files may cause errors.
   • Fix: Run vendor/bin/lang create without arguments to generate all missing locales.

5. Symfony Version Conflicts

   • Older Symfony versions (<7.4) may cause compatibility issues due to dependency updates.
   • Fix: Ensure your project uses Symfony 7+ or pin dependencies in composer.json.

Debugging Tips

• Verbose Output: Add --verbose to commands for detailed logs (e.g., vendor/bin/lang sync --verbose).
• Dry Runs: Use --dry-run with download or sync to preview changes without applying them.
• Check Logs: Errors often appear in storage/logs/laravel.log. Look for parser or file structure issues.

Extension Points

1. Custom Parsers

   • Extend LaravelLang\StatusGenerator\Parser\Parser to handle project-specific translation patterns (e.g., custom blade directives like @transCustom).
   • Example:

     namespace App\Extensions;
     use LaravelLang\StatusGenerator\Parser\Parser;
     
     class CustomParser extends Parser {
         protected function detectKeys($content) {
             // Add custom regex or logic here
             return parent::detectKeys($content);
         }
     }
     

2. Custom Status Reports

   • Override the status command to generate custom reports (e.g., CSV, JSON) by extending LaravelLang\StatusGenerator\Commands\StatusCommand.

3. Pre-Translation Hooks

   • Add logic before translation to skip specific keys or locales. Override the shouldTranslate method in your custom command.

4. Post-Sync Processing

   • Use Laravel’s queue:work to process translations asynchronously after lang sync for large projects.

Configuration Quirks

• Excluded Files: The package skips internal files by default (e.g., vendor/, node_modules/). Add exclusions to config/lang-status.php:

  'excludes' => [
      'path/to/exclude',
  ],
  

• Locale Paths: Customize locale paths if your project uses non-standard structures:

  'locale_paths' => [
      'custom/lang',
  ],
  

• Google Translate Languages: Ensure your API key has billing enabled for languages outside the free tier (e.g., Chinese, Japanese).

Performance Tips

• Batch Processing: For large projects, process translations in batches to avoid timeouts.
• Cache Results: Cache the output of lang status if running frequently in development.
• Parallel Downloads: Use parallel-lint or similar tools to speed up key detection in large codebases.