Getting Started

Minimal Setup

Install the package in your Laravel project (8.x–13.x):
```
composer require laravel-lang/status-generator --dev
```
Publish assets (if needed) by running:
```
php artisan vendor:publish --provider="LaravelLang\StatusGenerator\StatusGeneratorServiceProvider"
```
(Note: The package is CLI-focused and typically doesn’t require publishing.)
Verify installation by checking available commands:
```
php artisan lang
```

First Use Case: Check Translation Status

Run the status command to analyze your current translation coverage:

php artisan lang status

Output: A table showing translation completeness per locale (e.g., en, es, fr).
Key Insight: Identify missing or incomplete translations at a glance.

First Use Case: Create Missing Locales

Initialize a new locale (e.g., de for German) by copying the en structure:

php artisan lang create --locale=de

Output: Creates resources/lang/de/ with empty JSON files mirroring resources/lang/en/.

Implementation Patterns

Workflow: Syncing Translations from Upstream

Scenario: Your app depends on Laravel Framework translations (e.g., validation messages, auth strings). Keep them in sync across versions.

Download translations from a Laravel release (e.g., 9.x):
```
php artisan lang download \
  --url=https://github.com/laravel/framework/archive/refs/heads/9.x.zip \
  --project=framework \
  --ver=9.x \
  --copy=lang
```
- --copy=lang: Copies files from the lang directory of the downloaded archive.
- Result: Merges upstream translations into your resources/lang/ directory.
Sync keys to ensure no drift:
```
php artisan lang sync
```
- Action: Updates your translation files with any new keys from the source code (e.g., Blade files, PHP classes).
- Use Case: Critical after pulling new Laravel core updates or adding new features.

Workflow: Automating Google Translate for Bootstrapping

Scenario: Quickly generate draft translations for a new locale (e.g., pt_BR) using Google Translate.

Set up Google Cloud credentials (if using paid tier):
- Add GOOGLE_APPLICATION_CREDENTIALS to your .env:
```
GOOGLE_APPLICATION_CREDENTIALS=/path/to/your/service-account.json
```
- (Free tier uses anonymous API calls with limited quotas.)
Translate missing keys:
```
php artisan lang translate --locale=pt_BR
```
- Output: Fills in missing translations for pt_BR using Google Translate.
- Tip: Review drafts manually—Google Translate may misinterpret technical terms.

Integrate into CI: Add to your composer.json scripts or GitHub Actions:

# .github/workflows/translate.yml
jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: composer install --dev
      - run: php artisan lang translate --locale=es --locale=fr

Integration Tips

Customizing Key Detection:

Override the parser logic by extending LaravelLang\StatusGenerator\Parser.

Example: Add support for custom translation functions (e.g., __t() in your app):

// app/Providers/AppServiceProvider.php
use LaravelLang\StatusGenerator\Parser;

public function boot()
{
    Parser::macro('customFunction', function ($content) {
        return preg_match_all('/__t\(\s*[\'"](.*?)[\'"]/', $content, $matches);
    });
}

Excluding Files/Directories:
- Skip internal or third-party files by adding to config/lang.php:
```
'ignore' => [
    'vendor/*',
    'storage/*',
    'resources/views/vendor/*',
],
```

Multi-Repo Sync:

Use lang download to pull translations from multiple repos (e.g., Laravel Framework + Jetstream):

# Sync Laravel Framework (9.x)
php artisan lang download --url=https://github.com/laravel/framework/archive/refs/heads/9.x.zip --project=framework --copy=lang

# Sync Jetstream (2.x)
php artisan lang download --url=https://github.com/laravel/jetstream/archive/refs/heads/2.x.zip --project=jetstream --copy=resources/lang

CI/CD Pipeline:

Run lang sync and lang status in a pre-release or pre-merge GitHub Action to catch translation drift:

- name: Check translations
  run: |
    php artisan lang sync
    php artisan lang status --format=json > translation_status.json
    # Fail if status shows <90% coverage

Gotchas and Tips

Pitfalls

Google Translate Quotas:
- Free tier has limited requests/day. Monitor usage via Google Cloud Console.
- Workaround: Use --dry-run to preview translations before bulk operations:
```
php artisan lang translate --locale=ja --dry-run
```
Key Mismatches:
- Running lang sync may overwrite custom translations if keys don’t match exactly.
- Solution: Use --skip-existing to preserve manual translations:
```
php artisan lang sync --skip-existing
```
Symfony Version Conflicts:
- The package supports Symfony 7–8. If you encounter addCommand errors, ensure your symfony/console version is compatible (e.g., ^6.0).
- Fix: Update dependencies or pin Symfony to a supported version in composer.json:
```
"require": {
    "symfony/console": "^6.0"
}
```
Corrupted JSON Files:
- If lang status reports errors like "File X has an incorrect structure", manually validate the file:
```
jq empty resources/lang/es/auth.json  # Check JSON syntax
```
- Recovery: Re-generate the locale:
```
php artisan lang create --locale=es --force
```

Debugging Tips

Verbose Output: Enable debug mode for detailed logs:
```
php artisan lang status --verbose
```
- Helps identify skipped files, key detection issues, or path resolution problems.
Dry-Run Downloads: Test lang download without copying files:
```
php artisan lang download --url=... --dry-run
```
- Output: Lists files that would be copied without modifying your project.

Custom Log Path: Redirect logs to a file for CI debugging:

php artisan lang sync --log-file=/tmp/translation_sync.log

Extension Points

Custom Status Formatting: Override the status table output by extending the StatusGenerator class:

// app/Providers/AppServiceProvider.php
use LaravelLang\StatusGenerator\StatusGenerator;

public function boot()
{
    StatusGenerator::macro('customFormat', function () {
        return collect($this->getStatus())
            ->map(fn ($locale) => [
                'locale' => $locale['name'],
                'coverage' => $locale['coverage'] . '%',
                'missing' => $locale['missing_keys']->count(),
            ])
            ->toJson();
    });
}

Use with:

php artisan lang status --format=customFormat

Pre-Translation Hooks: Add logic before Google Translate runs by extending the TranslateCommand:

// app/Console/Commands/TranslateCommand.php
namespace App\Console\Commands;

use LaravelLang\StatusGenerator\Commands\TranslateCommand as BaseTranslateCommand;

class TranslateCommand extends BaseTranslateCommand
{
    protected function getTranslationPairs()
    {
        $pairs = parent::getTranslationPairs();
        // Filter or modify pairs before translation
        return $pairs->filter(fn ($pair) => !str_contains($pair['key'], 'admin.'));
    }
}

Post-Sync Validation: Validate translations after lang sync using a custom rule:

// app/Rules/ValidTranslation.php
use Illuminate\Contracts\Validation\Rule;

class ValidTranslation implements Rule
{
    public function passes($attribute, $value)
    {
        return strlen($value) > 3; // Reject empty or 1-letter translations
    }
}

Integrate with a post-sync Artisan command or

Status Generator Laravel Package